beehiiv Developer Documentation

curl -G https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/paid_recommendations/reports \
     -H "Authorization: Bearer <token>" \
     -d start_date=2026-09-01 \
     -d end_date=2026-09-30

{
  "data": [
    {
      "partnership_id": "rec_agr_00000000-0000-0000-0000-000000000000",
      "offer": {
        "id": "rec_offer_00000000-0000-0000-0000-000000000000",
        "name": "Spring growth offer"
      },
      "recommending_publication": {
        "id": "pub_00000000-0000-0000-0000-000000000001",
        "name": "The Morning Brief",
        "url": "https://morningbrief.beehiiv.com/"
      },
      "spend_cents": 25000,
      "subscribers_gained": {
        "verified": 100,
        "pending": 15,
        "failed": 5,
        "pending_opt_in": 2
      },
      "cost_per_verified_subscriber_cents": 250
    }
  ],
  "limit": 10,
  "has_more": false,
  "next_cursor": null
}

Currently in beta

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

Report spend and subscribers gained for each of your publication’s paid recommendation partnerships over a date range. Subscribers count toward the day they subscribed, and spend counts toward the day its subscriber subscribed, so the numbers for a range can change as pending subscribers are verified. Dates are whole days in UTC.

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

start_datedateRequired

The first day of the range in YYYY-MM-DD format.

end_datedateRequired

The last day of the range in YYYY-MM-DD format. Must be on or after start_date.

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

Only report on partnerships 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.

Response

datalist of objects

One report per partnership, including partnerships with no activity in the date range.

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