# Assign a subscription

`POST /v1/subscriptions` assigns a plan to a customer and returns the new
subscription, whose `id` is the [stable id](/guides/subscriptions/data-model) you
keep for every later call.

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

```json
{ "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](/guides/subscriptions/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](/guides/subscriptions/billing-schedules). |
| `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](/guides/subscriptions/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](/guides/subscriptions/lifecycle).