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 }]`).
`paymentMethodId`	no	Payment method to charge for automatic billing.
`automaticBilling`	no	Whether to charge the payment method automatically.
`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.

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 June 14, 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 }]).

paymentMethodId

Payment method to charge for automatic billing.

automaticBilling

Whether to charge the payment method automatically.

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.

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 June 14, 2026