Copy page

Subscriptions

Assign a subscription

POST /v1/subscriptions assigns a plan to a customer and returns the new subscription, whose id is the stable id you keep for every later call.

Code
curl -X POST https://api.ledgerbee.com/api/v1/subscriptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "0190…", "planId": "0190…", "startDate": "2026-07-01" }'

Code
{ "id": "0190abcd-…", "customerId": "0190…", "planId": "0190…", "status": "scheduled" }

Request fields

Field	Required	Effect
customerId	yes	The customer to assign the plan to (UUID).
planId	yes	The plan to assign (UUID).
startDate	yes	When the subscription begins (ISO 8601). A future date creates it scheduled.
endDate	no	A fixed end date; the subscription expires then.
billingCycleAnchor	no	The date the billing cycle aligns to. Defaults to startDate.
prorationBehavior	no	How the partial period from startDate to the anchor is handled. Default none — see Proration.
trialDays	no	Trial length (0–365). The subscription is trial until it elapses.
billingDirection	no	advance (charge at the start of the period) or arrears (at the end). Default advance. See Billing & cadence.
productOverrides	no	Per-product overrides against the plan template ([{ priceId, quantity, customPrice, discardPreAssignmentUsage }]). See Product overrides.
automaticBilling	no	Whether to auto-charge the subscription's card each cycle. Takes effect only once a card is attached; cards are attached by the buyer (see below), never on this call.
allowedPaymentProviders	no	The card provider the buyer may pay with, at most one (["STRIPE"]). Required before the buyer can add a card through the card window; see Collecting a card. Empty or omitted means card payment is off.
customerDepartmentId / departmentContactOverrideId	no	Route invoice delivery to a customer department / contact.
joinBillingGroupId	no	Create the subscription straight onto this billing group of the same customer. See below.
formBillingGroupWithSubscriptionId	no	Create the subscription and form a new billing group with this existing subscription of the same customer as the lead. See below.
discountIds	no	Discount records the subscription references, in the order they apply. Each bills on every period that starts before its end; one that lasts a number of periods ends that many periods after the first one billed, after any trial.
addons	no	Up to 19 add-ons created together with the subscription ([{ planId, productOverrides, cadence }]). cadence bills an add-on at another cadence its plan offers, such as year-1; see Cadence. See below.

Product overrides

Each entry in productOverrides names a price on the plan and the values that replace the plan's for it:

• customPrice is a unit price excluding VAT, as a decimal string such as "149.50", billed in place of the list price. A usage-metered price refuses it with SUBSCRIPTION_CANNOT_SET_QUANTITY_FOR_USAGE_BASED, and a tiered or other non-flat-rate price with SUBSCRIPTION_OVERRIDE_CUSTOM_PRICE_REQUIRES_FLAT_RATE. To change the price later, send a product change.
• discardPreAssignmentUsage: true, on a usage-metered price, keeps usage events dated before the assignment off this subscription's invoices. Use it with a backdated startDate whose window already holds recorded usage. Other subscriptions on the same meter still bill those events. On a non-metered price it returns SUBSCRIPTION_DISCARD_USAGE_REQUIRES_USAGE_PRICE.

What you can't set over the API

• currency — a subscription's currency is contractual, resolved from the customer and plan; there is no currency field on assign. Multi-currency is not selectable at assign time.
• Send-offset / prebill days — the lead time for issuing an invoice before the period is operator-configured, not a public field.
• A card / payment method — a subscription's card is attached by the buyer with their consent, through the card window, a card-save link or portal checkout; it is never set on this call. A subscription is created without a card and bills by invoice until the buyer attaches one. paymentMethodId is deprecated and non-functional — any value sent is rejected.

Collecting a card

To have the buyer add a card from your own UI:

1. Create the subscription with "allowedPaymentProviders": ["STRIPE"], or set it later with PATCH /v1/subscriptions/{id}.
2. Call POST /v1/checkout/subscriptions/{id}/card-window (API key scope checkout). It returns a Stripe window the buyer enters the card in, either embedded in your page or hosted on Stripe.
3. The card lands asynchronously, through Stripe. It becomes the subscription's card and automatic charging turns on; GET /v1/subscriptions/{id} then returns it as paymentMethodId. A card new to the customer also fires the card.added webhook.

The window, its uiMode options and its errors are described in Partner-hosted checkout.

Onto a billing group

Two optional fields place the new subscription on a billing group in the same call. Send at most one of them.

• joinBillingGroupId adds it to an existing group of the same customer. The group's billing date replaces billingCycleAnchor; startDate and prorationBehavior still decide how the period up to that date is handled.
• formBillingGroupWithSubscriptionId forms a new group with the named existing subscription as the lead. The lead's next billing date replaces billingCycleAnchor, and the lead's terms are written onto the new subscription.

The assignment and the placement commit together: a refused placement creates no subscription, and the response's billingGroupId already names the group. A dissolved group answers 400 SUBSCRIPTION_BILLING_GROUP_NOT_JOINABLE. A group whose billing date moved while the request ran answers 409 SUBSCRIPTION_BILLING_GROUP_GRID_MOVED_DURING_ASSIGN, and nothing was created; retry the request.

With add-ons

addons creates add-ons together with the subscription: each entry names a plan and optional productOverrides, and becomes a subscription of its own that bills on this subscription's invoice, inside its section.

Code
curl -X POST https://api.ledgerbee.com/api/v1/subscriptions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "0190…",
    "planId": "0190…",
    "startDate": "2026-07-01",
    "addons": [{ "planId": "0190…" }]
  }'

Each add-on names its own plan, product overrides and, optionally, a cadence its plan offers. It takes the customer, dates, proration behavior, billing direction and invoice details from this subscription, and must bill in its currency. The subscription and its add-ons commit together, so a refused add-on creates nothing, and one billing run bills them on one invoice. The response is the subscription, with its add-ons listed under addons.

addons cannot be combined with joinBillingGroupId or formBillingGroupWithSubscriptionId: the request answers 400 SHARED_VALIDATION_FAILED with details.reason: "ADDONS_WITH_BILLING_GROUP_PLACEMENT", and nothing is created. To give an existing subscription an add-on, use POST /v1/subscriptions/{id}/addons.

What the first invoice does

The first charge depends on three inputs:

• Trial — with trialDays, no charge is taken until the trial ends; the subscription sits in trial until then.
• Billing direction — advance charges at the start of the first period; arrears charges at the end.
• Proration — when startDate doesn't equal the billingCycleAnchor, the partial first period is handled per prorationBehavior. The default none gifts it; the other modes charge it (immediately or on the next invoice). See Proration for the worked examples.

A card pay-first subscription (its first charge taken on a card up front) sits in awaiting_payment and grants no access until that charge clears; subscriptions billed by other means activate directly. See Lifecycle & statuses.