beehiiv Developer Documentation

curl -G https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/paid_recommendations/reports/rec_agr_00000000-0000-0000-0000-000000000000 \
     -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
  }
}

Currently in beta

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

Report spend and subscribers gained for one of your publication’s paid recommendation partnerships over a date range. Counts follow the same rules as the list of reports.

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

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

The prefixed ID of the partnership 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.

Response

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error