Skip to main content

Subscriptions

Charge a saved card on a schedule: plans, trials, coupons, proration, dunning and a hosted customer portal, all handled by Orchestrapay. This page explains every option; the Subscriptions API page has the endpoint reference.

How it works​

Plan (pricing template) Subscription (customer instance)
amount / interval / trial price snapshot (grandfathered)
dunning / entitlements ──► card on file (payment method)
billing cycle + invoices
  1. You create a plan: the price, billing cadence, optional trial, dunning policy and entitlements.
  2. A customer subscribes with a card. The first cycle is paid on-session; every renewal is charged automatically off-session (a merchant-initiated transaction on the saved card).
  3. Each billing attempt writes an invoice (paid or failed, with the full subtotal / discount / tax / credit breakdown), sends the customer a receipt, and emits webhooks.

There are three ways to start a subscription:

  • Hosted subscribe page (zero integration): share the plan's subscribe_url, or create a checkout session to prefill a promotion code. The customer picks up the plan, enters their card and the subscription auto-creates. The page offers card payment only: a renewal can only charge a saved card, so a bank transfer or a wallet could never be renewed.
  • Your own page: create a subscription intent on your server and hand its payment intent to the PaymentForm. The subscription is created when the payment succeeds.
  • A card that is already saved: orchestrapay.subscriptions.create({ plan_uuid, payment_method }) subscribes it directly, with no customer present.
  • Dashboard: create plans and subscriptions manually under Subscriptions.

Take the first payment in your own page​

Create a subscription intent on your server. It prices the signup from the plan, the quantity and any promotion code, and returns a payment intent together with the id the subscription will have:

const intent = await orchestrapay.subscriptionIntents.create({
plan: plan.id,
customer: { reference: 'user_42', email: '[email protected]' },
external_id: 'user_42',
metadata: { order: '42' },
});
// intent.payment_intent -> 'pi_eu1_...'
// intent.subscription -> 'sub_eu1_...'
// intent.mode -> 'payment' or 'setup'
// intent.terms -> what the customer is agreeing to

Pass payment_intent to the PaymentForm in your page, and show the customer the returned terms next to it: amount_due is what they pay now, and terms says what each period costs afterwards and how long any introductory price lasts.

<PaymentForm paymentIntent={intent.payment_intent} />

The subscription id is reserved and returned before anything is paid, so you can store it with your own order right away. The subscription itself is created when the payment succeeds, with no second call from you. Until then GET /subscriptions/:id answers 404, and a declined or abandoned attempt creates nothing. Listen for subscription.created to know it exists: the webhooks you set on the intent receive the payment events of the first payment and then every event of the subscription.

When nothing is due at signup (a free trial, a fully discounted or a usage-billed first period) the intent comes back with mode setup: the PaymentForm saves the card with no charge, and the subscription starts when the card is saved.

The intent takes the same customer, metadata, webhooks, idempotency_key, return_url, timeout and routing pins as a payment intent. It does not take an amount, which the plan decides. See the API reference.

A customer can subscribe more than once, to the same plan included. To stop that, turn on Limit customers to one subscription in the tenant's settings in the dashboard. A customer who already holds a subscription that is not canceled, on any plan, is then refused with 409, and the hosted subscribe page asks them to manage it in the portal instead. Customers are matched by email.

Subscriptions on card gateways other than Stripe direct are not supported yet for renewals that need a recurring agreement.

Subscribe a card that is already saved​

When the customer is not present and you already hold a saved card for them (a pm_... from an earlier payment that saved it), create the subscription directly. The first cycle is charged on that card at once, as a merchant-initiated payment:

const sub = await orchestrapay.subscriptions.create({
plan_uuid: plan.id,
payment_method: 'pm_...',
customer_uuid: 'cus_...',
});

Use this for migrations and for customers you bill without a checkout. To take a first payment from a customer who is entering their card, use a subscription intent instead.

Pricing options​

  • Amount and currency — integer minor units (cents) with a lowercase 3-letter currency. A $5.00 monthly plan is amount: 500, currency: "usd".
  • Interval — daily, weekly, monthly or yearly, times interval_count (e.g. interval: "weekly", interval_count: 2 bills every two weeks).
  • Grandfathering — the subscription snapshots the plan's price at creation. Editing or archiving a plan never changes what existing subscribers pay; only an explicit plan change does.

Pricing models​

Every plan has a pricing_model that decides how amount and quantity combine into the cycle price:

ModelCycle priceUse case
flat (default)amountone price, quantity ignored
per_unitamount × quantityper-seat pricing (the hosted page shows a seat picker)
tieredtier ladder over quantityvolume discounts
meteredtier/unit price over reported usagepay-as-you-go

Tiered plans define a tiers ladder ([{ up_to: 10, unit_amount: 500 }, { up_to: null, unit_amount: 300 }]) with tiers_mode:

  • graduated — each tier bills its own units (first 10 at $5, the rest at $3)
  • volume — the tier the total quantity lands in prices ALL units

Metered billing: report usage as it happens (subscriptions.recordUsage); at each renewal the billed quantity is the period total (increments summed, a set overrides). Metered plans collect nothing at subscribe time — the card is saved with a no-charge setup.

Quantities: pass quantity (a positive integer, default 1) when creating the subscription. It multiplies the price on per_unit plans and walks the ladder on tiered plans; flat plans ignore it and metered plans bill reported usage instead. Change it later with subscriptions.update(sub, { quantity }): the change applies now and is prorated with the same rules as a plan change (see proration).

Multi-currency: give a plan currency_options ({ "eur": 450 }) and the hosted subscribe page offers a currency picker. Through the API, pass currency when creating the subscription: it must be the plan currency or a key of currency_options, and the matching amount snapshots onto the subscription. A plan with a trial_amount is only offered in its default currency. The currency is fixed once the subscription exists.

Products group the price variants of one offering (a product with many plans): create with orchestrapay.products.create, then pass product_uuid when creating plans.

Add-ons (multiple line items)​

Attach extra plans to a live subscription as add-on lines billed on the same cycle: subscriptions.addItem(sub, { plan, quantity }). Attaching charges the prorated remainder of the period; removing credits the unused time to the customer balance. Invoices carry the full per-line breakdown in lines.

Scheduled changes​

Queue future-dated plan/quantity changes with subscriptions.schedule(sub, { effective_at, plan, quantity }) — they land at the first billing run at or after the date, with no proration.

Apple Pay and Google Pay​

A customer can start a subscription with Apple Pay or Google Pay on the hosted subscribe page, and update its card the same way. The wallet button appears when both of these are true:

  • your payment form includes Apple Pay or Google Pay
  • the charge goes through a Stripe connector on the direct card surface

The wallet sheet states the plan, what is due today, any trial, and the regular price and interval. A free trial saves the wallet card with no charge, exactly as a typed card does.

A card saved from a wallet is tied to the device it came from. It renews the subscription, and the customer portal lists it as Apple Pay or Google Pay, but it is not offered as a saved card at a later checkout.

Other card gateways, MPGS for example, are card-only for subscriptions for now: on those the subscribe page shows the card form alone.

Trials​

Three trial shapes, configured on the plan:

ConfigurationBehavior
trial_days: 1414 days free. The card is saved at signup with no charge (a setup, not a payment), and the full price is billed when the trial ends.
trial_days: 14, trial_amount: 100The $1.00 intro price is charged at signup. The subscription stays trialing for 14 days, then bills the full price.
trial_cycles: 3, trial_amount: 100The first 3 billing cycles are charged at $1.00, then the full price.

During a trial the subscription is trialing and gets full entitlements.

A plan is rejected when:

  • trial_amount is set without trial_days or trial_cycles
  • trial_days and trial_cycles are both set

Coupons and promotion codes​

A coupon is the discount (percent_off or amount_off) with a duration:

  • once: first invoice only
  • repeating + duration_in_months: every invoice for that many months
  • forever: every invoice

A repeating coupon is defined in months, but a subscription bills in cycles of its plan's interval. When the code is redeemed, duration_in_months is converted into billing cycles: 3 months is 3 invoices on a monthly plan, about 13 on a weekly plan, and 1 on a yearly plan. It always covers at least one invoice. The result is the remaining_cycles on the subscription's discount.

An amount_off coupon is a fixed amount in one currency, so it only applies to prices in that currency. Redeeming it on a subscription billed in another currency is rejected. A percent_off coupon works in every currency.

A promotion code is the customer-facing string (e.g. WELCOME20) that redeems a coupon, with optional expiry and redemption caps. Customers enter it on the hosted subscribe page; the discount is snapshotted onto the subscription and burns down cycle by cycle.

Taxes​

Attach a manual tax rate (percentage, inclusive or exclusive, a display label like "VAT") when creating a subscription. Exclusive tax is added on top of each invoice; inclusive tax is informational. Tax appears as its own line on invoices and receipts.

Upgrades, downgrades and proration​

Changing plans mid-cycle uses a standard proration model. The billing date never moves; the remaining time is settled fairly:

  • Upgrade (proration_behavior: "create_prorations", the default) — the unused time on the old price becomes a credit, the remaining time on the new price is charged, and the difference is collected now. Access changes immediately.
  • Downgrade — the difference becomes a customer balance credit, automatically consumed by future invoices (an invoice fully covered by credit charges the card nothing).
  • proration_behavior: "none" — swap the price with no settlement.
  • Period-end switch (pending_plan_uuid) — no proration; the new plan starts at the next renewal.

Preview any change first with the upcoming invoice endpoint: it returns the exact charge-now amount or balance credit.

A period-end switch shows up on the subscription as pending_plan, the plan it will move to at the next renewal. It is null when nothing is queued.

When the charge for a change fails​

An immediate upgrade, a quantity increase or a new add-on charges the card before anything changes. If that charge does not succeed, the change is refused and the subscription stays exactly as it was. Nothing goes past_due, because there is nothing to recover.

ResponseMeaningWhat to do
HTTP 402, error: "payment_declined"The card was declined. A failed invoice records the attempt.Ask the customer for a working card, then send the change again.
HTTP 503, error: "payment_unresolved"The payment processor did not answer.Send the same request again. It repeats the same charge, never a second one.

Billing dates​

A renewal continues from where the paid period ended, not from the moment the charge went through. A subscription due on the 1st that is collected on the 4th, after a few days of dunning, is still due on the 1st of the next cycle. The one exception is a renewal collected more than a full cycle late: that time was never served, so the new period starts on the day of the payment.

Failed payments and dunning​

When a renewal charge fails the subscription goes past_due and the plan's dunning schedule takes over (default [1, 3, 7]: retry after 1, 3 and 7 days). A declined first charge is treated the same way: the subscription is created past_due and retried on the same schedule, rather than being rejected.

  1. The customer gets a payment-failed email with a link to the hosted invoice page, where they can pay immediately or enter a new card (no login needed — the link itself authorizes it).
  2. Each scheduled retry charges the card again automatically. Any successful payment (retry, hosted page, or card update) resets the subscription to active.
  3. During the plan's grace_period_days (default 7) entitlements stay on; past it they turn off while the subscription remains past_due.
  4. When every retry is exhausted the subscription is canceled and the customer is notified.

Each failed attempt writes a failed invoice whose transaction_intent is the declined payment, so you can look up why it was declined.

Bank authentication (SCA / 3DS) on renewals​

When an issuer demands authentication for an off-session charge, the invoice parks as requires_action (with the bank's requires_action_url), the customer gets a "confirm your payment" email, and the hosted invoice page walks them through confirming with their bank and completing the payment. The retry ladder keeps running as a fallback.

Cancellation, pause and reactivation​

  • Cancel at period end (default) — access continues until the paid period ends. Until then the customer can reactivate with one click.
  • Cancel immediately: access ends now.
  • Canceling a paused subscription always takes effect immediately, whatever you pass. A paused subscription has no renewal for a period-end cancellation to wait for.
  • Pause / resume: billing stops while paused (entitlements off). Resuming does not charge the card: billing picks up at the end of the period the customer already paid for. Only if that period has already ended is the next cycle billed right away.
  • A cancellation reason can be captured for retention analytics, and the portal offers pause-instead as a retention path.

Entitlements​

Plans carry a features map (boolean flags or numeric limits, e.g. {"api_access": true, "seats": 5}); subscriptions can override per customer (feature_overrides, for enterprise deals). Check them from your server at request time, with your secret key:

GET /v202609/entitlements/check?customer=<identifier>&feature=api_access
GET /v202609/entitlements?customer=<identifier>
const { allowed, value, reason } = await orchestrapay.entitlements.check({
customer: 'user_42',
feature: 'api_access',
});

const { features } = await orchestrapay.entitlements.list({ customer: 'user_42' });

The check returns allowed, the feature's value (the flag or the numeric limit) and a reason; the list returns the customer's whole features map. Both calls take the same customer identifier. It is compared against the id of the customer on the subscription (cus_...) and against the subscription's external_id, the reference you set when creating it, with no precedence between the two. Canceled subscriptions are skipped, and when several subscriptions match, the most recently created one answers.

Status drives access automatically: active and trialing allow, past_due allows during grace only, paused and canceled deny. See the API reference for every reason.

Customer portal​

Every tenant gets a hosted, brand-styled portal at /portal/<tenant> where customers sign in with an email code (no password) and can:

  • see their subscriptions, next billing date and exact upcoming charge
  • switch plans with a proration preview before confirming
  • update their card (saved with no charge; the card-update page offers card payment only)
  • pause, resume, reactivate or cancel
  • browse their full billing history

Credit notes and refunds​

Issue post-invoice adjustments with orchestrapay.creditNotes.create({ invoice, amount, reason }) — the amount is credited to the customer balance and consumed by future invoices (a fully covered renewal charges the card nothing). Card refunds go through the Refunds API against the invoice's transaction_intent.

A credit note can only be issued against a paid invoice, and it cannot exceed what is left of that invoice after earlier credit notes and refunds. An invoice of 500 with a 200 refund and a 100 credit note has 200 left to credit.

Each invoice reports what happened to its payment afterwards: amount_refunded is the total refunded so far, and dispute_status is the state of a dispute raised against it (null when there is none).

Invoice PDFs​

Every invoice renders as a PDF: merchants via GET /v202609/invoices/:id/pdf, customers via the download link on the hosted invoice page.

Each invoice also carries two links you can hand to the customer as they are: hosted_url opens the hosted invoice page and pdf_url downloads the PDF. Neither needs a login or your API key.

orchestrapay.billingPortal.createSession({ customer }) mints a 15-minute login-free portal URL — drop it behind a "Manage subscription" button in your app so customers skip the email code.

Receipts and emails​

Customers automatically receive branded emails. A subscription with no customer email sends none.

Emailcustomer_emails nameWhen
Subscription confirmedwelcomeThe subscription starts, active or trialing. States the trial terms (when it ends, and its price or that it is free) and what is charged at each renewal after it.
Trial ending remindertrial_ending3 days before a trial ends, once per trial. Trials of 3 days or less get none: the confirmation email already said when the charge comes. A trial already set to cancel gets none either.
ReceiptreceiptA payment succeeded, with the full amount breakdown. Not sent for an invoice of 0.
Payment failedpayment_failedA charge failed and dunning is running, with the pay-now link.
Bank confirmation neededpayment_confirmationThe bank asked the customer to authenticate a renewal, with a link to confirm it.
Cancellation scheduledcancellation_scheduledA cancel at period end was requested.
Subscription canceledcanceledThe subscription ended: canceled immediately, or after the last dunning retry failed.

Portal sign-in codes are emailed as well.

Every email carries your logo, or your icon and name when no logo is uploaded, falling back to the organisation's when the tenant has none. Under Tenants > Edit > Emails in the dashboard you can add a support email and phone, shown as "Questions? Contact us at...", and your company's legal name with links to your terms of use and privacy policy, shown in the footer. An empty field is left out.

The emails are sent as "Your name via Orchestrapay" from an orchestrapay.com address, and a reply goes to your support email when you have set one. To send them from your own address instead, add a from address and a Resend API key in the same place. The address must be on a domain verified in your Resend account, and a key with sending access is enough. If Resend refuses an email sent with your key, it is sent from the Orchestrapay address instead, so your customer still receives it.

Sending some or all of them yourself​

A plan chooses which of these emails we send. customer_emails on a plan is the list of names to send: omit it and all of them go out, leave a name out to write that email yourself, or pass [] to send none. The dashboard has the same choice as a list of checkboxes on the plan.

await orchestrapay.plans.update('plan_...', {
customer_emails: ['receipt', 'payment_failed', 'payment_confirmation'],
});

Every email has a webhook event to send your own from: subscription.created for the welcome, invoice.paid for the receipt, invoice.payment_failed for a failed payment and invoice.payment_action_required for a bank confirmation (the invoice's hosted_url is the page where the customer pays, updates the card or confirms), subscription.updated for a scheduled cancellation, subscription.canceled for the end and subscription.trial_will_end for a trial about to end. Portal sign-in codes are always sent, whatever the plan says.

Webhooks​

Set webhooks on the plan and every subscription created from it inherits them, including the ones started on the hosted subscribe page. Each endpoint has a url, an optional secret and an optional events list: an endpoint with a list receives only the event types it names, and one without receives them all. A subscription intent or a subscription that brings its own webhooks uses those instead of the plan's. Endpoints are only returned through the merchant API, never to the customer portal, and a secret is never returned at all, so keep the value you set.

EventWhen
subscription.createdSubscription created
subscription.updatedPlan or quantity change, add-on added or removed, scheduled change applied, pause/resume, reactivate, scheduled cancel
subscription.trial_will_end3 days before a trial ends, once per trial. Not sent for a trial of 3 days or less, or one already set to cancel
subscription.canceledImmediate cancel, period-end cancel executing, or dunning exhausted
invoice.paidA billing attempt succeeded
invoice.payment_failedA billing attempt failed (dunning is running)
invoice.payment_action_requiredThe bank asked the customer to confirm a renewal. The invoice has status requires_action, and its hosted_url is where the customer confirms. Retries follow the dunning schedule, as for a failed payment

Every event is a POST with the same envelope:

{
"id": "evt_eu1_5b1c0d6e7f8a4b9c8d7e6f5a4b3c2d1e",
"type": "subscription.updated",
"created_at": "2026-08-18T00:00:04.000Z",
"data": { "id": "sub_eu1_...", "object": "subscription", "status": "active" }
}

data is the full subscription for subscription.* events. For invoice.* events it is the invoice, with subscription holding the subscription id.

Verifying. Subscription webhooks are authenticated the same way payment webhooks are: the secret of the endpoint is sent in the Orchestrapay-Webhook-Secret header, and you compare it with the value you stored. No secret is generated for you, so an endpoint without one cannot be verified. See Webhooks: Authentication. Deliveries are at-least-once, so deduplicate on the envelope id and answer with a 2xx quickly.

End to end​

The shortest path from nothing to a gated feature.

1. Create a plan, with the features it grants and where to send events:

const plan = await orchestrapay.plans.create({
name: 'Pro Monthly',
amount: 500,
currency: 'usd',
interval: 'monthly',
trial_days: 14,
features: { api_access: true, seats: 5 },
webhooks: [
{
url: 'https://example.com/webhooks/orchestrapay',
secret: process.env.ORCHESTRAPAY_WEBHOOK_SECRET,
},
],
});

2. Start the subscription. Either share the hosted link:

// plan.subscribe_url -> https://pay.orchestrapay.com/subscribe/<tenant>/<plan>

or take the first payment in your own page, tagging the subscription with your own user id:

// Server
const intent = await orchestrapay.subscriptionIntents.create({
plan: plan.id,
customer: { reference: 'user_42', email: '[email protected]' },
external_id: 'user_42',
});

// Browser
<PaymentForm paymentIntent={intent.payment_intent} />

The subscription intent.subscription exists once the customer has paid.

3. Receive webhooks. Check the secret, then react to the event type:

import { verifyWebhookSecret } from '@orchestrapay/sdk';

app.post('/webhooks/orchestrapay', express.json(), (req, res) => {
const received = req.headers['orchestrapay-webhook-secret'];
if (!verifyWebhookSecret(received, process.env.ORCHESTRAPAY_WEBHOOK_SECRET)) {
return res.status(401).end();
}
const event = req.body;
if (event.type === 'invoice.payment_failed') {
// dunning is running, nothing to do yet
}
if (event.type === 'subscription.canceled') {
// access is off from now on
}
res.status(200).end();
});

4. Check entitlements wherever you gate a feature. You do not need to mirror subscription state: the answer already accounts for trials, grace periods, pauses and cancellations.

const { allowed } = await orchestrapay.entitlements.check({
customer: 'user_42',
feature: 'api_access',
});

5. Send the customer to the portal to change plan, update the card or cancel:

const { url } = await orchestrapay.billingPortal.createSession({
customer: '[email protected]',
});
// redirect to url (valid for 15 minutes)

SDK​

import Orchestrapay from '@orchestrapay/sdk';
const orchestrapay = new Orchestrapay('orch_sk_live_...');

const plan = await orchestrapay.plans.create({
name: 'Pro Monthly', amount: 500, currency: 'usd', interval: 'monthly',
});

// Zero-integration: share a hosted subscribe link
const session = await orchestrapay.checkoutSessions.create({ plan: plan.id });
// session.url -> https://pay.orchestrapay.com/subscribe/<tenant>/<plan>

// Or take the first payment in your own page
const intent = await orchestrapay.subscriptionIntents.create({
plan: plan.id,
customer: { reference: 'user_42', email: '[email protected]' },
});
// intent.payment_intent -> PaymentForm, intent.subscription -> the id it will have

// Or subscribe a card that is already saved, with no customer present
const sub = await orchestrapay.subscriptions.create({
plan_uuid: plan.id,
payment_method: 'pm_...',
});

// Every subscription, 100 per page
let page = await orchestrapay.subscriptions.list({ limit: 100 });
while (page.has_more) {
const last = page.data[page.data.length - 1];
page = await orchestrapay.subscriptions.list({ limit: 100, starting_after: last.id });
}

// Prorated upgrade with preview
const preview = await orchestrapay.subscriptions.upcoming(sub.id, { plan: 'plan_...' });
await orchestrapay.subscriptions.update(sub.id, {
plan_uuid: 'plan_...', proration_behavior: 'create_prorations',
});

See the Subscriptions API reference for every endpoint and field.