beehiiv Developer Documentation

{
  "data": [
    {
      "accepted_subscribers": 0,
      "auto_accepted": false,
      "created_at": 1767225600,
      "id": "rec_agr_00000000-0000-0000-0000-000000000000",
      "offer": {
        "id": "rec_offer_00000000-0000-0000-0000-000000000000",
        "name": "Spring growth offer"
      },
      "pending_spend_cents": 0,
      "pending_subscribers": 0,
      "recommending_publication": {
        "id": "pub_00000000-0000-0000-0000-000000000001",
        "name": "The Morning Brief",
        "url": "https://morningbrief.beehiiv.com/"
      },
      "status": "pending",
      "total_spend_cents": 0,
      "total_subscribers": 0,
      "updated_at": 1767312000,
      "rejected_reason": null
    }
  ],
  "limit": 10,
  "has_more": false,
  "next_cursor": null
}

Currently in beta

This feature is currently in beta and the API is subject to change.

List the applications to your publication’s paid recommendation offers. Filter by status=pending for applications waiting for a decision. An accepted application becomes a partnership with the same ID.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Query parameters

statusenumOptional

Only return applications with this status.

Allowed values:

offer_idstringOptionalformat: "^(rec_offer_[0-9a-fA-F\-]+)$"

Only return applications on this offer.

limitintegerOptional

A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.

cursorstringOptional

Use the opaque cursor token from next_cursor to fetch the next page of results.

order_byenumOptionalDefaults to created

The field that the results are sorted by. Defaults to created.
created - The time the application was submitted.
updated - The time the record was last updated.

Allowed values:

directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to asc.
asc - Ascending, sorts from smallest to largest.
desc - Descending, sorts from largest to smallest.

Allowed values:

Response

datalist of objects

An array of applications.

limitintegerOptional

The limit placed on the results. If no limit was specified in the request, this defaults to 10.

pageintegerOptional>=0Defaults to 1

Offset pagination only: The page number the results are from. Only present when using deprecated offset-based pagination.

total_pagesintegerOptional

Offset pagination only: The total number of pages. Only present when using deprecated offset-based pagination.

has_morebooleanOptional

Cursor pagination only: Indicates whether there are more results available after the current page.

next_cursorstringOptional

Cursor pagination only: The cursor token to use for fetching the next page of results. This will be null if has_more is false.

total_resultsintegerOptional

The total number of results from all pages.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error