Subscriptions

A subscription is the recurring relationship between a customer and one of your products. It’s created when a customer completes a checkout for a product that has a recurring price, and it keeps generating invoices and charges on every renewal until you or the customer end it.

Subscriptions currently bill USD cards only. Recurring billing on other rails and currencies is rolling out; the API and objects below don’t change when it does.

How subscriptions work

A customer subscribes

When a customer completes a checkout for a product that has a billing_cycle, Bachs creates a subscription and bills the first cycle. There is no “create subscription” call; subscriptions always start from a checkout. See Creating a subscription.

Bachs renews it automatically

At the end of each billing period, Bachs advances the subscription to the next cycle, opens an invoice, and charges the customer’s saved card off-session. You don’t schedule anything.

A failed charge starts recovery

If a renewal charge fails, the subscription moves to past_due and Bachs runs an automated payment recovery flow of retries plus a customer email with a hosted link to update their card.

You react to webhooks

Every state change emits a webhook: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, and the invoice.* events. Grant and revoke access off these, not off the redirect. See Subscription webhook events.

Recurring pricing

A subscription is driven entirely by how you price the underlying product. Recurring pricing is set when you create a product:

Billing interval: day, week, month, or year.
Interval count (frequency), the number of intervals per cycle. { "interval": "month", "frequency": 3 } bills every three months.
Currency: a subscription keeps the currency it was created in at checkout and bills every renewal in that currency. Today that is USD. NGN subscriptions are available only on accounts where they have been enabled.

A product with a billing_cycle is a recurring product; a product without one is one-time.

The billing interval is fixed once a product is created. To offer a different cadence (say, a yearly plan next to a monthly one), create a separate product and show both at checkout.

Statuses

A subscription is always in exactly one status.

Status	Meaning
`trialing`	In a free trial. No charge has been taken yet; the first charge happens when the trial ends.
`active`	Billing normally. The card is charged at the end of each cycle.
`past_due`	A renewal charge failed and Bachs is retrying. The customer has been emailed a link to update their card.
`unpaid`	Recovery was exhausted and your account is set to keep unpaid subscriptions. A later successful payment reactivates it.
`canceled`	Terminal. Either you/the customer canceled, or recovery was exhausted and your account is set to cancel. No further charges.

Transitions you’ll observe: trialing → active (trial ends), active → past_due (charge fails), past_due → active (a retry or card update succeeds), past_due → unpaid | canceled (recovery exhausted, configurable), active → canceled (cancellation). canceled is terminal; a later payment can’t revive it. unpaid and past_due are both recoverable.

Creating a subscription

Subscriptions are created through checkout; there is no POST /v1/subscriptions. Any checkout session for a recurring product becomes a subscription checkout automatically.

POST /v1/checkout-sessions

{
  "product_cart": [{ "product_id": "prod_abc123", "quantity": 1 }],
  "customer": { "email": "customer@example.com" },
  "billing_currency": "USD",
  "success_url": "https://example.com/thanks"
}

If prod_abc123 has a billing_cycle, completing this checkout creates the subscription and bills cycle one. Bachs collects the card during checkout and reuses it for every renewal. See Checkout Sessions. You can click through this flow right now: the Pro and Team plans on the live demo start real sandbox subscriptions through the overlay checkout.

Managing subscriptions

Change the plan, move a trial, or cancel, using the API.

The subscription object

{
  "id": "sub_1a2b3c4d5e6f",
  "customer": {
    "customer_id": "cust_xyz789",
    "email": "customer@example.com",
    "name": "Jane Doe"
  },
  "payment_method_id": "pm_7h8i9j0k",
  "status": "active",
  "collection_method": "charge_automatically",
  "currency": "USD",
  "amount": "10.00",
  "billing_cycle": { "interval": "month", "frequency": 1 },
  "quantity": 1,
  "current_period_start": "2026-07-13T12:00:00Z",
  "current_period_end": "2026-08-13T12:00:00Z",
  "previously_billed_at": "2026-07-13T12:00:00Z",
  "next_billed_at": "2026-08-13T12:00:00Z",
  "trial_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "created_at": "2026-07-13T12:00:00Z",
  "product": { "id": "prod_abc123", "name": "Pro plan", "billing_cycle": { "interval": "month", "frequency": 1 } },
  "items": [
    {
      "id": "il_11aa22bb",
      "status": "active",
      "quantity": 1,
      "recurring": true,
      "price_type": "fixed",
      "unit_amount": "10.00",
      "currency": "USD",
      "previously_billed_at": "2026-07-13T12:00:00Z",
      "next_billed_at": "2026-08-13T12:00:00Z"
    }
  ],
  "metadata": { "plan": "pro" }
}

Money is a string at the currency’s precision ("10.00"), always paired with currency.
Dates are ISO-8601 UTC.
previously_billed_at is the start of the period that was last billed; next_billed_at is the next scheduled charge.
IDs are prefixed: sub_ (subscription), inv_ (invoice), il_ (line item), pm_ (payment method), cust_ (customer), prod_/price_ (catalog).

Next steps

Managing subscriptions

Change plans, move a trial, or cancel, using the API.

Proration

How the price difference is settled when a subscription changes mid-cycle.

Payment recovery

How Bachs retries failed renewals and what happens when retries run out.

Trials

Offer a free period before the first charge. In beta.

Customer portal

A hosted page where customers cancel, switch plans, and update their card themselves.

FAQ

What's the difference between a subscription and a product?

A product is the thing you sell: name, pricing, currency. A subscription is one specific customer’s ongoing relationship with that product. Bachs treats one-time and recurring purchases as the same kind of object (both are products); the only difference is whether the price has a billing_cycle.

When is a customer actually charged?

The first charge happens at checkout, or when the trial ends if one is configured. After that, the card is charged at the end of every billing cycle. If a renewal charge fails, the subscription moves to past_due and enters payment recovery.

Can I change the price of an existing subscription?

A subscription locks in the amount it was created with, so existing subscribers aren’t surprised by catalog changes. Editing a product’s price only affects new subscriptions. To move an existing subscriber to different pricing, change the plan on their subscription.

How do I know when something changes?

Every change emits a webhook. Treat webhooks as the source of truth for granting and revoking access; redirects can be lost if the customer closes the tab.

Get Started

Payouts

Virtual accounts

Products & pricing

Subscriptions

Customer portal

Payments

Dashboard

Developer Portal

CLI

For You and Your Customers

Subscriptions

How subscriptions work

Recurring pricing

Statuses

Creating a subscription

Managing subscriptions

The subscription object

Next steps

Managing subscriptions

Proration

Payment recovery

Trials

Customer portal

FAQ

​How subscriptions work

​Recurring pricing

​Statuses

​Creating a subscription

Managing subscriptions

​The subscription object

​Next steps

Managing subscriptions

Proration

Payment recovery

Trials

Customer portal

​FAQ

How subscriptions work

Recurring pricing

Statuses

Creating a subscription

The subscription object

Next steps

FAQ