Subscriptions

See Subscriptions concept for the lifecycle. This page is the field reference.

Object

{
  "id": "8e7c2f4a-…",
  "customer_id": "d1a94b3c-…",
  "plan_id": "6b0f81de-…",
  "payment_method_id": "9c2e57aa-…",
  "status": "active",
  "currency": "USD",
  "current_period_start": "2026-05-06T00:00:00Z",
  "current_period_end":   "2026-06-06T00:00:00Z",
  "billing_anchor_day": 6,
  "trial_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "ended_at": null,
  "next_billing_at": "2026-06-06T00:00:00Z",
  "last_invoiced_period_end": "2026-05-06T00:00:00Z",
  "paused_until": null,
  "previous_plan_id": null,
  "plan_change_at": null,
  "scheduled_plan_id": null,
  "version": 3,
  "created_at": "2026-04-06T12:00:00Z",
  "updated_at": "2026-05-06T00:00:00Z"
}

Endpoints

Method	Path	What
POST	/v1/subscriptions	Create.
GET	/v1/subscriptions/{id}	Retrieve.
GET	/v1/subscriptions?customer_id=…	List, optionally scoped to one customer.
POST	/v1/subscriptions/{id}/change-plan?version=…	Change plan (immediate, prorated).
POST	/v1/subscriptions/{id}/cancel?version=…	Cancel immediately (prorated).
POST	/v1/subscriptions/{id}/cancel-at-period-end?version=…	Schedule cancellation for the period boundary.
POST	/v1/subscriptions/{id}/pause?version=…	Pause (optionally until a timestamp).
POST	/v1/subscriptions/{id}/resume?version=…	Resume from paused.

All mutations are versioned: pass the current version as a query parameter and send an Idempotency-Key header. A stale version returns 409 — re-fetch and retry.

Status values

pending_activation, trialing, active, past_due, paused, canceled, ended, incomplete_expired. See Status reference for the transition table.

current_period_*

The period the subscription is currently in. Updates atomically at the period boundary, alongside the new invoice’s creation.

previous_plan_id / plan_change_at

Set when the plan was changed inside the current period: the immediately-prior plan id and the timestamp of the most recent applied change. Both reset to null at the next period roll. Immediate changes can repeat within a period; each settles its own prorated charge at change time.

scheduled_plan_id

Non-null when a downgrade or shorter-cycle switch is queued: the plan the subscription moves to when the current period ends. The swap is applied by the billing engine at the period roll, which clears this field and emits subscription.plan_changed. Revert it by calling change-plan with the current plan_id.

version

Optimistic-lock counter. Every successful mutation increments it; pass the value you last read on the next mutation.

Webhook events

The full set is in the Event catalog.