# Subscriptions

A subscription is the recurring billing relationship between one of your
customers and a plan. Every subscription carries a **stable id** that survives
plan changes; use it to read, update, and cancel the subscription, and to cancel
a single scheduled change.

Every request authenticates with an API key or OAuth access token (see
[Authentication](/guides/authentication)). Reads require the `subscriptions-read`
scope; writes require `subscriptions-write`. Manage scopes under
**Marketplace → API Keys** / **OAuth Clients** in the LedgerBee app. Full schemas
live under the **Subscriptions** tag in the **[API Reference](/api)**.

Your company must also hold the Subscription license. Without it, every
subscription endpoint returns `403` with `code: "LICENSE.REQUIRED"` and
`details.licenseKey: "Subscription"`, regardless of the key's scopes — see
[Errors](/guides/errors).

## What the public API does — and doesn't

The public API is a deliberately thin slice over a rich billing engine. It can
**assign, read, list, update, and cancel** subscriptions, and **read or cancel**
a queued change — but it does not *create* change flows (replace-plan, direction,
cadence, products, pause/resume): those are queued from the LedgerBee operator
app and the customer portal UI today (a public "queue a change" API is planned).
Billing mechanics (schedules, proration) are computed by the engine and surface
as predictable *behavior*, not as endpoints you call.

## Which page do I need?

| I want to… | Page |
|---|---|
| Create a subscription for a customer | [Assign a subscription](/guides/subscriptions/assign) |
| Understand the id, versions, and timeline | [Data model](/guides/subscriptions/data-model) |
| Know what a status means and when it changes | [Lifecycle & statuses](/guides/subscriptions/lifecycle) |
| Predict *when* and *what* gets billed | [Billing & cadence](/guides/subscriptions/billing-schedules) |
| Know what a mid-cycle change charges | [Proration](/guides/subscriptions/proration) |
| Change a subscription (plan, direction, cancel…) | [Change flows](/guides/subscriptions/changes) |
| Bill a parent plan with child subscriptions | [Parent & child](/guides/subscriptions/parent-child) |
| React to subscription events / reconcile | [Webhooks & reconciliation](/guides/subscriptions/webhooks) |