beehiiv Developer Documentation

curl -X PATCH https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/paid_recommendations/offers/rec_offer_00000000-0000-0000-0000-000000000000 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "budget_cents": 200000
}'

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

Currently in beta

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

Update a paid recommendations offer. The cost per subscriber can only change while the offer is a draft; change the price of a live offer in the dashboard.

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

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

The prefixed ID of the offer object

Request

This endpoint expects an object.

namestringOptional

The name of the offer.

descriptionstringOptional

The description shown to publications that might recommend you.

cost_per_subscriber_centsintegerOptional>=50

The amount in cents paid for each verified subscriber. Only a draft offer can change it.

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. Send an empty list for every country.

verification_modeenumOptional

How subscribers are verified before the offer pays for them.

Allowed values:

Response

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