beehiiv Developer Documentation

curl -X POST https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/paid_recommendations/offers \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Weekly growth offer",
  "cost_per_subscriber_cents": 250,
  "description": "Readers who like practical marketing tips.",
  "budget_cents": 100000,
  "eligible_countries": [
    "US",
    "CA"
  ],
  "verification_mode": "standard",
  "status": "live"
}'

{
  "data": {
    "id": "rec_offer_00000000-0000-0000-0000-000000000000",
    "name": "Weekly growth offer",
    "status": "live",
    "cost_per_subscriber_cents": 250,
    "budget_cents": 100000,
    "eligible_countries": [
      "US",
      "CA"
    ],
    "verification_mode": "standard",
    "over_budget": false,
    "created_at": 1760280000,
    "updated_at": 1760280000,
    "description": "Readers who like practical marketing tips."
  }
}

Currently in beta

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

Create an offer the publication pays to be recommended through. Going live makes it the publication’s only live offer: a previous live offer keeps its partners but stops taking new applications, and its pending applications are rejected.

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

Request

This endpoint expects an object.

namestringRequired

The name of the offer.

cost_per_subscriber_centsintegerRequired>=50

The amount in cents paid for each verified subscriber. The minimum is 50.

descriptionstringOptional

The description shown to publications that might recommend you.

budget_centsintegerOptional>=0

The most the offer can spend in cents.

eligible_countrieslist of stringsOptional

ISO 3166-1 alpha-2 country codes of the subscribers the offer pays for. Leave empty for every country.

verification_modeenumOptional

How subscribers are verified before the offer pays for them. Defaults to standard.

Allowed values:

statusenumOptional

The status to create the offer in. Defaults to draft.

Allowed values:

Response

Created

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error