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
namestringDisplay name, e.g. "Pro Monthly".
amountintegerPrice per billing cycle in cents. E.g. $5.00 is 500.
currencystringA 3 letter ISO currency, e.g. USD.
intervalstringBilling cadence: daily, weekly, monthly or yearly.
interval_countoptional, integerBill every N intervals (default 1). E.g. weekly + 2 bills every two weeks.
descriptionoptional, stringShown on the hosted subscribe page.
trial_daysoptional, integerFixed-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, integerIntro price in cents. Requires trial_days or trial_cycles. It can be lower or higher than amount. Omit for a free trial.
trial_cyclesoptional, integerCycle-based trial: the first N billing cycles are charged at trial_amount. Cannot be combined with trial_days.
grace_period_daysoptional, integerDays a past_due subscription keeps its entitlements (default 7).
dunning_scheduleoptional, arrayDays after a failed charge to retry, e.g. [1, 3, 7] (the default). When exhausted the subscription is canceled.
featuresoptional, objectEntitlements granted by the plan: boolean flags or numeric limits, e.g. {"api_access": true, "seats": 5}. Queried via the entitlement endpoints.
webhooksoptional, arrayUp 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, arrayThe 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.
const plan = await orchestrapay.plans.create({
name: 'Pro Monthly',
amount: 500,
currency: 'usd',
interval: 'monthly',
trial_days: 14,
features: { api_access: true, seats: 5 },
});{
"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_uuidstringThe plan to subscribe to (plan_…).
payment_methodstringThe saved card to charge (pm_…), returned by a save-on-file payment or card setup.
customer_uuidoptional, stringThe customer (cus_…). Enables receipts, the customer portal and entitlement lookups by customer.
quantityoptional, integerSeats 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, stringBill 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, stringA customer-facing promotion code, e.g. "WELCOME20". The discount snapshots onto the subscription.
tax_rate_uuidoptional, stringManual tax rate to apply to every invoice.
external_idoptional, stringYour own reference. Can be passed as customer to the entitlement endpoints.
feature_overridesoptional, objectPer-subscription entitlement overrides layered over the plan features (enterprise/custom deals).
webhooksoptional, arrayUp 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, arrayA 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 | nullWhere 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 | nullThe urls of webhooks.
metadataobject | nullThe metadata of the subscription intent that started the subscription, or null.
pending_planobject | nullThe 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.
const sub = await orchestrapay.subscriptions.create({
plan_uuid: 'plan_eu1_...',
payment_method: 'pm_eu1_...',
customer_uuid: 'cus_eu1_...',
promotion_code: 'WELCOME20',
});{
"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, stringChange 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, integerChange 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, stringQueue a plan change for the next renewal instead (no proration).
payment_methodoptional, stringPoint the subscription at a different saved card (pm_…).
feature_overridesoptional, objectReplace the per-subscription entitlement overrides.
webhooksoptional, arrayReplace the endpoints, in the same shape as on create.
webhook_urlsoptional, arrayReplace 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 listGET /v202609/subscriptions/:id: retrieve (includes plan, customer, invoices andpending_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 immediatelyPOST /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 endedPOST /v202609/subscriptions/:id/reactivate: undo a scheduled cancel-at-period-end
Paginating the list
limitoptional, integerPage size, 1 to 100 (default 100). Anything else is rejected with a 400.
starting_afteroptional, stringA subscription id (sub_…). Returns the page that follows it. An id that names none of your subscriptions is rejected with a 400.
planoptional, stringOnly 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 402The 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 503The 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.
// 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',
});// 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 cyclesubscription_cycle: a scheduled renewalsubscription_update: a proration charge from an immediate upgrade
Payment and document fields
transaction_intentstring | nullThe 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_refundedintegerHow much of the payment has been refunded so far, in minor units. 0 when nothing was refunded.
dispute_statusstring | nullThe 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 | nullThe hosted invoice page you can send to the customer. No login needed: the link itself authorizes it.
pdf_urlstring | nullA direct link to the invoice PDF, usable by the customer without your API key.
{
"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
namestringShown to the customer, e.g. "20% off 3 months".
percent_offoptional, numberPercentage discount. Exactly one of percent_off / amount_off is required.
amount_offoptional, integerFixed 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, integerRequired 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, integerCap on total redemptions.
redeem_byoptional, stringISO date after which the coupon can no longer be redeemed.
Endpoints
POST /v202609/coupons,GET /v202609/coupons,DELETE /v202609/coupons/:idPOST /v202609/promotion-codes— body{ "coupon_uuid": "cpn_…", "code": "WELCOME20" }GET /v202609/promotion-codes,DELETE /v202609/promotion-codes/:idPOST /v202609/tax-rates,GET /v202609/tax-rates
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/itemsDELETE /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" }(setoverrides the period total;subscription_itemtargets 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/schedulesDELETE /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 refundsGET /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 portalurl
// 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
planstringThe plan to subscribe to (plan_…). It must be active.
customerstring | objectWho 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, integerSeats or units, 1 to 100000 (default 1).
promotion_codeoptional, stringA customer-facing promotion code. The discount is priced into amount_due and snapshots onto the subscription.
currencyoptional, stringBill 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, stringYour own reference, set on the subscription. Can be passed as customer to the entitlement endpoints.
metadataoptional, objectKey-value pairs. Echoed in the payment webhooks of the intent, copied onto the subscription and included in its subscription.* events.
webhooksoptional, arrayEndpoints, 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, stringUp 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, stringWhere a hosted payment page returns the customer after it finishes.
timeoutoptional, numberSeconds until the payment intent cancels itself if unpaid (default 1800).
payment_formoptional, stringPin a payment form (pf_…) of your tenant. Only its Apple Pay and Google Pay entries are kept beside the card form.
orchestratoroptional, stringPin a live orchestrator (orc_…) of your tenant to route the card payment.
connectoroptional, stringPin a live connector (con_…) of your tenant to take the card payment.
Response fields
payment_intentstringThe payment intent to pass to the PaymentForm (pi_…).
subscriptionstringThe 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_dueintegerWhat the customer pays now, in minor units. 0 in setup mode.
currencystringThe billing currency.
customerstringThe customer (cus_…).
metadataobject | nullThe metadata you sent.
planobjectThe plan.
termsobjectWhat 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_createdbooleanfalse 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, oramountorsave_cardwas 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 theidempotency_keywas already used for something else.
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{
"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
planstringThe plan to subscribe to (plan_…).
promotion_codeoptional, stringPrefill a promotion code on the hosted page.
const session = await orchestrapay.checkoutSessions.create({
plan: 'plan_eu1_...',
});
// share session.url with your customer{
"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 featureGET /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
allowedbooleanWhether to grant access. False when the feature is false, 0, missing from the plan, or the subscription status denies access.
valueboolean | integer | nullThe feature value: a flag or a numeric limit. Null when access is denied before the feature is read.
reasonstringactive_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.
const { allowed, value } = await orchestrapay.entitlements.check({
customer: 'user_42',
feature: 'seats',
});
const { features } = await orchestrapay.entitlements.list({
customer: 'cus_eu1_...',
});// 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 createdsubscription.updated: plan or quantity change, an add-on added or removed, a scheduled change applied, pause, resume, reactivate, or a cancellation scheduled for period endsubscription.trial_will_end: 3 days before a trial ends, once per trialsubscription.canceled: canceled immediately, at period end, or after the last dunning retry failedinvoice.paid: a billing attempt succeededinvoice.payment_failed: a billing attempt failedinvoice.payment_action_required: the bank asked the customer to confirm a renewal; the invoice hasstatusrequires_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.
{
"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"
}
}