Skip to main content

Subscriptions API

Recurring billing on saved cards: plans, subscriptions, invoices, coupons and hosted checkout sessions. Concepts (trials, proration, dunning, entitlements) are explained in the Subscriptions guide.

All objects use typed string ids (plan_…, sub_…, in_…, cpn_…, promo_…) and an object discriminator. Amounts are integer minor units with a lowercase 3-letter currency.

Create a plan​

The reusable pricing template subscriptions are created from. Price fields are immutable after creation — existing subscribers keep their grandfathered price; create a new plan to change pricing.

Parameters​

namestring

Display name, e.g. "Pro Monthly".

amountinteger

Price per billing cycle in cents. E.g. $5.00 is 500.

currencystring

A 3 letter ISO currency, e.g. USD.

intervalstring

Billing cadence: daily, weekly, monthly or yearly.

interval_countoptional, integer

Bill every N intervals (default 1). E.g. weekly + 2 bills every two weeks.

descriptionoptional, string

Shown on the hosted subscribe page.

trial_daysoptional, integer

Fixed-duration trial length in days. With no trial_amount the trial is free: the card is saved with no charge. With trial_amount, the intro price is charged at signup. Either way the subscription is trialing until the trial ends, then bills the full price. Cannot be combined with trial_cycles.

trial_amountoptional, integer

Intro price in cents. Requires trial_days or trial_cycles. It can be lower or higher than amount. Omit for a free trial.

trial_cyclesoptional, integer

Cycle-based trial: the first N billing cycles are charged at trial_amount. Cannot be combined with trial_days.

grace_period_daysoptional, integer

Days a past_due subscription keeps its entitlements (default 7).

dunning_scheduleoptional, array

Days after a failed charge to retry, e.g. [1, 3, 7] (the default). When exhausted the subscription is canceled.

featuresoptional, object

Entitlements granted by the plan: boolean flags or numeric limits, e.g. {"api_access": true, "seats": 5}. Queried via the entitlement endpoints.

webhooksoptional, array

Up to 5 endpoints for subscription.* and invoice.* events. Each is an object with url, an optional secret sent in the Orchestrapay-Webhook-Secret header, and an optional events list naming the event types it receives (omit it, or pass ["*"], for all). Every subscription created from the plan inherits them unless it brings its own.

customer_emailsoptional, array

The emails we send the customer, by name: welcome, receipt, trial_ending, payment_failed, payment_confirmation, cancellation_scheduled, canceled. Omit it to send them all. Leave a name out to send that email yourself, or pass [] to send none.

POST /v202609/plans
const plan = await orchestrapay.plans.create({
name: 'Pro Monthly',
amount: 500,
currency: 'usd',
interval: 'monthly',
trial_days: 14,
features: { api_access: true, seats: 5 },
});
RESPONSE
{
"id": "plan_eu1_1f0e9d8c7b6a5f4e3d2c1b0a99887766",
"object": "plan",
"name": "Pro Monthly",
"description": null,
"amount": 500,
"currency": "usd",
"interval": "monthly",
"interval_count": 1,
"trial_days": 14,
"trial_amount": null,
"trial_cycles": 0,
"grace_period_days": 7,
"dunning_schedule": [1, 3, 7],
"features": { "api_access": true, "seats": 5 },
"subscribe_url": "https://pay.orchestrapay.com/subscribe/ten_eu1_9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40/plan_eu1_1f0e9d8c7b6a5f4e3d2c1b0a99887766",
"webhooks": null,
"customer_emails": ["welcome", "receipt", "trial_ending", "payment_failed", "payment_confirmation", "cancellation_scheduled", "canceled"],
"is_active": true,
"created_at": "2026-07-18T00:00:00.000Z"
}

Create a subscription​

Subscribes a card that is already saved to a plan. With no trial the first cycle is charged immediately; renewals charge automatically on schedule. To take the first payment from a customer who is entering their card, create a subscription intent instead.

Parameters​

plan_uuidstring

The plan to subscribe to (plan_…).

payment_methodstring

The saved card to charge (pm_…), returned by a save-on-file payment or card setup.

customer_uuidoptional, string

The customer (cus_…). Enables receipts, the customer portal and entitlement lookups by customer.

quantityoptional, integer

Seats or units, a positive integer (default 1). Multiplies the price on per_unit plans and walks the tier ladder on tiered plans. Ignored by flat plans; metered plans bill reported usage instead.

currencyoptional, string

Bill in an alternate currency. Must be the plan currency or a key of the plan currency_options; the matching amount snapshots onto the subscription. Not available on plans with a trial_amount. Defaults to the plan currency.

promotion_codeoptional, string

A customer-facing promotion code, e.g. "WELCOME20". The discount snapshots onto the subscription.

tax_rate_uuidoptional, string

Manual tax rate to apply to every invoice.

external_idoptional, string

Your own reference. Can be passed as customer to the entitlement endpoints.

feature_overridesoptional, object

Per-subscription entitlement overrides layered over the plan features (enterprise/custom deals).

webhooksoptional, array

Up to 5 endpoints for subscription.* and invoice.* events. Each is an object with url, an optional secret sent in the Orchestrapay-Webhook-Secret header, and an optional events list naming the event types it receives (omit it, or pass ["*"], for all). Omit it to inherit the plan webhooks. See Webhooks below.

webhook_urlsoptional, array

A flat list of urls, read as endpoints with no secret and no events list. Ignored when webhooks is sent.

Statuses​

trialing → active ⇄ past_due (dunning) → canceled, plus paused. Entitlements: active and trialing allow; past_due allows during the grace period; paused and canceled deny.

When the first charge is declined the subscription is still created. It comes back past_due with a failed invoice, and the charge is retried on the plan's dunning schedule like any failed renewal.

Response fields worth knowing​

webhooksarray | null

Where this subscription sends its events: its own endpoints, or the ones inherited from the plan. Each entry has url and events (null means all). The secret you set on an endpoint is never returned. Only returned to you, never to the customer portal.

webhook_urlsarray | null

The urls of webhooks.

metadataobject | null

The metadata of the subscription intent that started the subscription, or null.

pending_planobject | null

The plan a queued period-end switch (pending_plan_uuid) will move to at the next renewal, or null when no switch is queued. Filled in when you retrieve a single subscription.

POST /v202609/subscriptions
const sub = await orchestrapay.subscriptions.create({
plan_uuid: 'plan_eu1_...',
payment_method: 'pm_eu1_...',
customer_uuid: 'cus_eu1_...',
promotion_code: 'WELCOME20',
});
RESPONSE
{
"id": "sub_eu1_265ec4c71e314901a7b01885d05ecc96",
"object": "subscription",
"status": "active",
"amount": 500,
"currency": "usd",
"interval": "monthly",
"interval_count": 1,
"quantity": 1,
"discount": {
  "coupon_uuid": "…",
  "name": "20% off 3 months",
  "percent_off": 20,
  "remaining_cycles": 2
},
"current_period_start": "2026-07-18T00:00:00.000Z",
"current_period_end": "2026-08-18T00:00:00.000Z",
"next_billing_at": "2026-08-18T00:00:00.000Z",
"cancel_at_period_end": false,
"metadata": null,
"webhooks": [
  { "url": "https://example.com/webhooks/orchestrapay", "events": null }
],
"webhook_urls": ["https://example.com/webhooks/orchestrapay"],
"plan": { "id": "plan_eu1_…", "object": "plan", "name": "Pro Monthly" },
"pending_plan": null,
"customer": { "id": "cus_eu1_…", "object": "customer", "email": "[email protected]" }
}

Update a subscription​

Change the card, apply an immediate prorated plan or quantity change, queue a period-end switch, or adjust overrides and webhooks. The billing currency is fixed at creation and cannot be updated.

Parameters​

plan_uuidoptional, string

Change plan NOW. Prorated per proration_behavior; the billing anchor does not move. Requires the same currency and interval as the current plan.

proration_behavioroptional, string

"create_prorations" (default): an upgrade charges the prorated difference immediately, a downgrade credits the customer balance. "none": swap with no settlement. "always_invoice" is an alias of create_prorations.

quantityoptional, integer

Change the seats or units NOW. Prorated per proration_behavior exactly like a plan change, and can be sent together with plan_uuid. The subscription must be active or trialing; a change made during a trial is not prorated.

pending_plan_uuidoptional, string

Queue a plan change for the next renewal instead (no proration).

payment_methodoptional, string

Point the subscription at a different saved card (pm_…).

feature_overridesoptional, object

Replace the per-subscription entitlement overrides.

webhooksoptional, array

Replace the endpoints, in the same shape as on create.

webhook_urlsoptional, array

Replace the endpoints with a flat list of urls. Ignored when webhooks is sent.

Other subscription endpoints​

  • GET /v202609/subscriptions: list, newest first (filter with ?plan=plan_…). See Paginating the list
  • GET /v202609/subscriptions/:id: retrieve (includes plan, customer, invoices and pending_plan)
  • GET /v202609/subscriptions/:id/upcoming — preview the next renewal, or a plan change's proration with ?plan=plan_…
  • POST /v202609/subscriptions/:id/cancel: body { "immediately": false, "reason": "…" }; default cancels at period end. A paused subscription is always canceled immediately
  • POST /v202609/subscriptions/:id/pause / …/resume: pause billing, or resume it. Resuming does not charge: billing picks up at the end of the period already paid for, or right away only if that period has already ended
  • POST /v202609/subscriptions/:id/reactivate: undo a scheduled cancel-at-period-end

Paginating the list​

limitoptional, integer

Page size, 1 to 100 (default 100). Anything else is rejected with a 400.

starting_afteroptional, string

A subscription id (sub_…). Returns the page that follows it. An id that names none of your subscriptions is rejected with a 400.

planoptional, string

Only subscriptions on this plan (plan_…).

The response is { "data": [...], "has_more": true }. While has_more is true, pass the id of the last subscription in data as starting_after to get the next page.

When the charge for a change does not go through​

An immediate plan or quantity change, and attaching an add-on, can charge the card right away. When that charge does not succeed the change is refused and the subscription stays exactly as it was.

payment_declinedHTTP 402

The card was declined. The subscription is unchanged and a failed invoice records the attempt. Nothing is retried for you: send the request again once the customer has a working card.

payment_unresolvedHTTP 503

The payment processor did not answer. The subscription is unchanged. Send the same request again: it repeats the same charge, never a second one.

The code is in the error field of the response body, next to statusCode and a message.

PATCH /v202609/subscriptions/:id
// Preview, then apply an immediate prorated upgrade
const preview = await orchestrapay.subscriptions.upcoming(
'sub_eu1_...',
{ plan: 'plan_eu1_...' },
);
// preview.amount_due_now -> 1500

await orchestrapay.subscriptions.update('sub_eu1_...', {
plan_uuid: 'plan_eu1_...',
proration_behavior: 'create_prorations',
});
RESPONSE
// GET /v202609/subscriptions/:id/upcoming?plan=plan_…
{
"object": "upcoming_invoice",
"preview_type": "plan_change",
"currency": "usd",
"credit_unused": 500,
"charge_remaining": 2000,
"amount_due_now": 1500,
"credit_to_balance": 0,
"period_end": "2026-08-18T00:00:00.000Z"
}

// GET /v202609/subscriptions?limit=2&starting_after=sub_eu1_…
{
"data": [
  { "id": "sub_eu1_…", "object": "subscription", "status": "active" },
  { "id": "sub_eu1_…", "object": "subscription", "status": "trialing" }
],
"has_more": true
}

// PATCH /v202609/subscriptions/:id, card declined (HTTP 402)
{
"statusCode": 402,
"error": "payment_declined",
"message": "The payment for this change was declined, so the subscription was not changed."
}

Invoices​

One invoice per billing attempt (paid or failed) with the full amount breakdown: amount = subtotal - discount + tax - credit_applied.

Endpoints​

  • GET /v202609/invoices: list (filter with ?subscription=sub_…)
  • GET /v202609/invoices/:id: retrieve

Billing reasons​

  • subscription_create: the first cycle
  • subscription_cycle: a scheduled renewal
  • subscription_update: a proration charge from an immediate upgrade

Payment and document fields​

transaction_intentstring | null

The payment behind the invoice (ti_…). On a failed first charge or renewal it is the declined attempt, so you can look up why it failed. Null when no charge was attempted.

amount_refundedinteger

How much of the payment has been refunded so far, in minor units. 0 when nothing was refunded.

dispute_statusstring | null

The status of a dispute raised against the payment: inquiry, needs_response, under_review, won, lost or closed. Null when the payment was never disputed.

hosted_urlstring | null

The hosted invoice page you can send to the customer. No login needed: the link itself authorizes it.

pdf_urlstring | null

A direct link to the invoice PDF, usable by the customer without your API key.

RESPONSE
{
"id": "in_eu1_b201396b19db40e8b46a6cfb42958c34",
"object": "invoice",
"amount": 400,
"subtotal": 500,
"discount": 100,
"tax": 0,
"credit_applied": 0,
"currency": "usd",
"status": "paid",
"billing_reason": "subscription_create",
"period_start": "2026-07-18T00:00:00.000Z",
"period_end": "2026-08-18T00:00:00.000Z",
"transaction_intent": "ti_eu1_…",
"amount_refunded": 0,
"dispute_status": null,
"hosted_url": "https://…/invoice/…",
"pdf_url": "https://api-{region}.orchestrapay.com/portal/invoices/…/pdf",
"is_trial": false,
"attempt_count": 1,
"paid_at": "2026-07-18T00:00:00.000Z",
"subscription": "sub_eu1_…"
}

Coupons and promotion codes​

Coupon parameters​

namestring

Shown to the customer, e.g. "20% off 3 months".

percent_offoptional, number

Percentage discount. Exactly one of percent_off / amount_off is required.

amount_offoptional, integer

Fixed discount in cents. Requires currency, and only applies to prices in that currency: a subscription billed in another currency rejects the promotion code.

durationstring

"once" (first invoice), "repeating" (every invoice for duration_in_months months) or "forever".

duration_in_monthsoptional, integer

Required when duration is "repeating". Converted into billing cycles of the plan interval when the code is redeemed: 3 months is 3 invoices on a monthly plan, about 13 on a weekly plan and 1 on a yearly plan. Always at least one invoice.

max_redemptionsoptional, integer

Cap on total redemptions.

redeem_byoptional, string

ISO date after which the coupon can no longer be redeemed.

Endpoints​

  • POST /v202609/coupons, GET /v202609/coupons, DELETE /v202609/coupons/:id
  • POST /v202609/promotion-codes — body { "coupon_uuid": "cpn_…", "code": "WELCOME20" }
  • GET /v202609/promotion-codes, DELETE /v202609/promotion-codes/:id
  • POST /v202609/tax-rates, GET /v202609/tax-rates
POST /v202609/coupons
const coupon = await orchestrapay.coupons.create({
name: '20% off 3 months',
percent_off: 20,
duration: 'repeating',
duration_in_months: 3,
});

await orchestrapay.promotionCodes.create({
coupon_uuid: coupon.id,
code: 'WELCOME20',
});

Products, items, usage and schedules​

Products​

Group the price variants of one offering; pass product_uuid when creating plans.

  • POST /v202609/products — body { "name": "…", "description": "…" }
  • GET /v202609/products, GET /v202609/products/:id, PATCH /v202609/products/:id

Pricing models on plans​

Plans accept pricing_model (flat / per_unit / tiered / metered), tiers + tiers_mode (graduated / volume), and currency_options (alternate currencies for the hosted page). See the guide for the math.

Add-on items​

  • POST /v202609/subscriptions/:id/items — body { "plan": "plan_…", "quantity": 1, "proration_behavior": "create_prorations" }
  • GET /v202609/subscriptions/:id/items
  • DELETE /v202609/subscriptions/:id/items/:item: unused time credits the balance

Attaching an add-on charges the prorated remainder now. A declined or unanswered charge refuses it with the same errors as a plan change.

Metered usage​

  • POST /v202609/subscriptions/:id/usage-records — body { "quantity": 120, "action": "increment" } (set overrides the period total; subscription_item targets an add-on)
  • GET /v202609/subscriptions/:id/usage — current-period total

Scheduled changes​

  • POST /v202609/subscriptions/:id/schedules — body { "effective_at": "2027-01-01T00:00:00Z", "plan": "plan_…", "quantity": 10 }
  • GET /v202609/subscriptions/:id/schedules
  • DELETE /v202609/subscriptions/:id/schedules/:schedule (not-yet-applied only)

Credit notes​

  • POST /v202609/credit-notes: body { "invoice": "in_…", "amount": 200, "reason": "…" }; the amount credits the customer balance. The invoice must be paid, and the amount cannot exceed what is left of it after earlier credit notes and refunds
  • GET /v202609/credit-notes?invoice=in_…

Invoice PDF​

  • GET /v202609/invoices/:id/pdf — renders the invoice as a PDF

Billing portal sessions​

  • POST /v202609/billing-portal/sessions — body { "customer": "[email protected]" }; returns a 15-minute login-free portal url
RESPONSE
// A tiered per-seat plan
{
"id": "plan_eu1_…",
"object": "plan",
"pricing_model": "tiered",
"tiers_mode": "graduated",
"tiers": [
  { "up_to": 10, "unit_amount": 500 },
  { "up_to": null, "unit_amount": 300 }
],
"currency_options": { "eur": 450 },
"amount": 500,
"currency": "usd",
"interval": "monthly"
}

// An invoice with the per-line breakdown
{
"id": "in_eu1_…",
"object": "invoice",
"amount": 6100,
"lines": [
  { "description": "Team plan", "quantity": 12, "unit_amount": 500, "amount": 5600 },
  { "description": "Priority support", "quantity": 1, "unit_amount": 500, "amount": 500 }
],
"status": "paid"
}

Subscription intents​

Take the first payment of a subscription in your own page. A subscription intent prices the signup and returns a payment intent to hand to the PaymentForm, together with the id the subscription will have. That id is reserved when the intent is created: every payment attempt made on the intent is linked to it from the start, and GET /subscriptions/:id answers 404 until the intent is paid. When the payment succeeds, or the card is saved for a free start, the subscription is created under that id with no second call from you, and subscription.created is sent.

The intent takes what a payment intent takes, with the same shapes, except amount, which the plan decides, and save_card, because a subscription always saves the card it renews on. The payment form offers the card form, and Apple Pay or Google Pay where your form has them, whatever form or connector you pin: a renewal can only charge a saved card.

Parameters​

planstring

The plan to subscribe to (plan_…). It must be active.

customerstring | object

Who subscribes, as on a payment intent: a cus_… id of an existing customer, or an object with reference, email, first_name, last_name, phone_number and address. An object with a reference is found by it and updated, or created. The customer needs an email: it is the identity they sign in to the customer portal with.

quantityoptional, integer

Seats or units, 1 to 100000 (default 1).

promotion_codeoptional, string

A customer-facing promotion code. The discount is priced into amount_due and snapshots onto the subscription.

currencyoptional, string

Bill in an alternate currency: a key of the plan currency_options. Not available on plans with a trial_amount. Defaults to the plan currency.

external_idoptional, string

Your own reference, set on the subscription. Can be passed as customer to the entitlement endpoints.

metadataoptional, object

Key-value pairs. Echoed in the payment webhooks of the intent, copied onto the subscription and included in its subscription.* events.

webhooksoptional, array

Endpoints, each with url, an optional secret and an optional events list. They receive the payment events of the first payment (payment.success, payment.attempt_failed, payment.canceled) and then the subscription.* and invoice.* events of the subscription for its whole life, each endpoint with its own secret and its own events list. When omitted, the subscription inherits the plan webhooks.

idempotency_keyoptional, string

Up to 255 characters, unique within your tenant. Sending it again returns the same subscription intent, with the same reserved subscription id, and status 200.

return_urloptional, string

Where a hosted payment page returns the customer after it finishes.

timeoutoptional, number

Seconds until the payment intent cancels itself if unpaid (default 1800).

payment_formoptional, string

Pin a payment form (pf_…) of your tenant. Only its Apple Pay and Google Pay entries are kept beside the card form.

orchestratoroptional, string

Pin a live orchestrator (orc_…) of your tenant to route the card payment.

connectoroptional, string

Pin a live connector (con_…) of your tenant to take the card payment.

Response fields​

payment_intentstring

The payment intent to pass to the PaymentForm (pi_…).

subscriptionstring

The id the subscription will have once the intent is paid (sub_…).

modestring

"payment": amount_due is charged and the card is saved. "setup": nothing is due now (a free trial, a fully discounted or a usage-billed first period), so the card is saved with no charge.

amount_dueinteger

What the customer pays now, in minor units. 0 in setup mode.

currencystring

The billing currency.

customerstring

The customer (cus_…).

metadataobject | null

The metadata you sent.

planobject

The plan.

termsobject

What to show the customer before they pay: plan_name, interval, interval_count, regular_amount (each period once any introductory price has run out, null when billed by usage) and intro (null, or amount with either days or cycles: the introductory price and how long it lasts).

resource_createdboolean

false when an idempotency_key replayed an earlier intent.

Errors​

  • 400: a parameter is invalid, the plan is not active or not offered in that currency, the promotion code does not apply, the customer has no email, a pinned form, orchestrator or connector is not a live one of your tenant, or amount or save_card was sent.
  • 404: the plan or the customer does not exist in your tenant.
  • 409: the tenant limits customers to one subscription and this customer already has one that is not canceled, or the idempotency_key was already used for something else.
POST /v202609/subscription-intents
const intent = await orchestrapay.subscriptionIntents.create({
plan: 'plan_eu1_...',
customer: {
  reference: 'user_42',
  email: '[email protected]',
  address: { country: 'FR' },
},
metadata: { order: '42' },
webhooks: [
  {
    url: 'https://example.com/webhooks/orchestrapay',
    secret: process.env.ORCHESTRAPAY_WEBHOOK_SECRET,
  },
],
idempotency_key: 'signup-user_42-pro',
});
// pass intent.payment_intent to the PaymentForm
RESPONSE
{
"object": "subscription_intent",
"payment_intent": "pi_eu1_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
"subscription": "sub_eu1_265ec4c71e314901a7b01885d05ecc96",
"mode": "payment",
"amount_due": 500,
"currency": "usd",
"customer": "cus_eu1_9a8b7c6d5e4f40312213f4e5d6c7b8a9",
"metadata": { "order": "42" },
"plan": { "id": "plan_eu1_…", "object": "plan", "name": "Pro Monthly" },
"terms": {
  "plan_name": "Pro Monthly",
  "interval": "monthly",
  "interval_count": 1,
  "regular_amount": 500,
  "intro": null
},
"resource_created": true
}

Checkout sessions​

The zero-integration path: mint a hosted subscribe URL for a plan and share it. The customer enters their card on the hosted page (branded per tenant) and the subscription auto-creates. A free trial uses a no-charge card setup, a trial with an intro price charges that price, and a plan with no trial charges the first cycle on the spot. Every plan also carries this link as subscribe_url, so you only need a session to prefill a promotion code. The hosted page offers card payment only, because a renewal can only charge a saved card.

Parameters​

planstring

The plan to subscribe to (plan_…).

promotion_codeoptional, string

Prefill a promotion code on the hosted page.

POST /v202609/checkout/sessions
const session = await orchestrapay.checkoutSessions.create({
plan: 'plan_eu1_...',
});
// share session.url with your customer
RESPONSE
{
"id": "cs_eu1_…",
"object": "checkout_session",
"url": "https://pay.orchestrapay.com/subscribe/ten_eu1_9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40/plan_eu1_…",
"plan": "plan_eu1_…"
}

Entitlements​

Ask whether a customer currently has access to a feature. The answer follows the subscription status and the plan features, with the subscription feature_overrides layered on top.

Endpoints​

  • GET /v202609/entitlements/check?customer=…&feature=…: one feature
  • GET /v202609/entitlements?customer=…: every feature the customer has

Identifying the customer​

Both endpoints take the same customer parameter. It is compared against two things at once, with no precedence between them: the id of the customer on the subscription (cus_…), and the subscription's external_id. Canceled subscriptions are skipped. When more than one subscription matches, the most recently created one answers.

Check response​

allowedboolean

Whether to grant access. False when the feature is false, 0, missing from the plan, or the subscription status denies access.

valueboolean | integer | null

The feature value: a flag or a numeric limit. Null when access is denied before the feature is read.

reasonstring

active_subscription, trial_active, grace_period, subscription_past_due, subscription_paused, feature_not_in_plan or no_subscription. A canceled subscription answers no_subscription.

The list endpoint returns features (the merged map, or null when access is denied) with the same reason.

GET /v202609/entitlements/check
const { allowed, value } = await orchestrapay.entitlements.check({
customer: 'user_42',
feature: 'seats',
});

const { features } = await orchestrapay.entitlements.list({
customer: 'cus_eu1_...',
});
RESPONSE
// GET /v202609/entitlements/check
{
"allowed": true,
"value": 5,
"reason": "active_subscription"
}

// GET /v202609/entitlements
{
"features": { "api_access": true, "seats": 5 },
"reason": "active_subscription"
}

Webhooks​

Set webhooks on a plan (inherited by its subscriptions), on a single subscription, or on a subscription intent. Each endpoint has a url, an optional secret and an optional events list. An endpoint with an events list receives only the event types it names, matched exactly; one without a list, or with ["*"], receives all of them. Each event is a POST with a structured envelope; data is the subscription for subscription.* events and the invoice, with a subscription id, for invoice.* events.

Event types​

  • subscription.created: a subscription was created
  • subscription.updated: plan or quantity change, an add-on added or removed, a scheduled change applied, pause, resume, reactivate, or a cancellation scheduled for period end
  • subscription.trial_will_end: 3 days before a trial ends, once per trial
  • subscription.canceled: canceled immediately, at period end, or after the last dunning retry failed
  • invoice.paid: a billing attempt succeeded
  • invoice.payment_failed: a billing attempt failed
  • invoice.payment_action_required: the bank asked the customer to confirm a renewal; the invoice has status requires_action

Verifying​

Subscription webhooks are authenticated the same way payment webhooks are: the secret you set on the endpoint arrives in the Orchestrapay-Webhook-Secret header. Compare it with the value you stored, as described in Webhooks: Authentication. No secret is generated for you: an endpoint created without one receives its events with no secret to check. Deliveries are at-least-once, so deduplicate on the envelope id.

RESPONSE
{
"id": "evt_eu1_5b1c0d6e7f8a4b9c8d7e6f5a4b3c2d1e",
"type": "invoice.paid",
"created_at": "2026-08-18T00:00:04.000Z",
"data": {
  "id": "in_eu1_b201396b19db40e8b46a6cfb42958c34",
  "object": "invoice",
  "amount": 500,
  "currency": "usd",
  "status": "paid",
  "billing_reason": "subscription_cycle",
  "subscription": "sub_eu1_265ec4c71e314901a7b01885d05ecc96"
}
}