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 `quantity` overrides against the plan template (`[{ priceId, quantity }]`).
`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.
`customerDepartmentId` / `departmentContactOverrideId`	no	Route invoice delivery to a customer department / contact.

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 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.

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.

Last modified on July 30, 2026

Overview Data model

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" }'

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

A fixed end date; the subscription expires then.

billingCycleAnchor

The date the billing cycle aligns to. Defaults to startDate.

prorationBehavior

How the partial period from startDate to the anchor is handled. Default none — see Proration.

trialDays

Trial length (0–365). The subscription is trial until it elapses.

billingDirection

advance (charge at the start of the period) or arrears (at the end). Default advance. See Billing & cadence.

productOverrides

Per-product quantity overrides against the plan template ([{ priceId, quantity }]).

automaticBilling

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.

customerDepartmentId / departmentContactOverrideId

Route invoice delivery to a customer department / contact.

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 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.

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.

Last modified on July 30, 2026