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

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.

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.

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.