Buy-ups Subscriber REST API

Subscriber-facing REST endpoints for purchasing and managing buy-up add-ons. Cookie auth and subscriber identity — the caller must be the subscriber logged in to WordPress.

Base path: /wp-json/benecaster/v1/shows/{show_id}/buyups

List Available Buy-ups

GET /shows/{show_id}/buyups/available

Returns all active buy-ups the current subscriber is eligible to see, with their current grant state. Requires the subscriber to be logged in; returns 401 otherwise.

Response — array:

[
  {
    "slug": "transcript-archive",
    "name": "Transcript Archive",
    "description": "Full text transcripts for every episode.",
    "price_cents": 500,
    "currency": "usd",
    "is_purchased": false,
    "is_sold_out": false,
    "cancels_at": null
  }
]

is_purchased — true if the subscriber holds an active or cancelling grant.
cancels_at — Unix timestamp if the subscriber has scheduled cancellation; null otherwise.
is_sold_out — true when the cap is reached and the subscriber does not hold a grant.

Purchase a Buy-up

POST /shows/{show_id}/buyups/{buyup_slug}/purchase

Adds the buy-up as a Stripe subscription item to the subscriber’s active subscription. Charges the prorated amount for the current billing period immediately.

Response: 200 OK with { "ok": true, "grant_active": true }.

Errors:

Concurrent purchase error (concurrent_purchase): Capped buy-ups use a MySQL advisory lock to serialize simultaneous purchase requests. If the lock wait times out after 5 seconds, the endpoint returns 409 with the message: “This buy-up is currently being purchased by another subscriber. Please try again in a moment.” This is retryable — the subscriber can attempt the purchase again immediately and will usually succeed on the next try. Uncapped buy-ups do not use the advisory lock and are not affected by this error.