Subscriptions

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

Object

{
  "id": "sub_…",
  "object": "subscription",
  "customer_id": "cus_…",
  "plan_code": "pro-monthly-usd",
  "status": "active",
  "current_period_start": "2026-05-06T00:00:00Z",
  "current_period_end":   "2026-06-06T00:00:00Z",
  "billing_cycle_anchor": "2026-05-06T00:00:00Z",
  "trial_start": null,
  "trial_end":   null,
  "paused_until": null,
  "cancel_at":   null,
  "cancel_at_period_end": false,
  "default_payment_method_id": "pm_…",
  "quantities": { "active_seats": 7 },
  "discounts":  [ { "id": "dsc_…", "coupon_code": "SUMMER25", "remaining_cycles": 2 } ],
  "commitment": null,
  "dunning":    null,
  "latest_invoice_id": "inv_…",
  "metadata":   {},
  "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.
PATCH	/v1/subscriptions/{id}	Change plan, quantities, metadata.
GET	/v1/subscriptions	List + filter.
POST	/v1/subscriptions/{id}/pause	Pause.
POST	/v1/subscriptions/{id}/resume	Resume.
POST	/v1/subscriptions/{id}/cancel	Cancel (at: now or period_end).
POST	/v1/subscriptions/{id}/reactivate	Undo a cancel_at_period_end.
POST	/v1/subscriptions/{id}/extend-trial	Push the trial end out.
POST	/v1/subscriptions/{id}/quantities	Update a metered quantity.
POST	/v1/subscriptions/{id}/discounts	Apply a coupon.
DELETE	/v1/subscriptions/{id}/discounts/{id}	Remove a discount.
POST	/v1/subscriptions/{id}/retry-payment	Force a dunning retry now.
POST	/v1/subscriptions/{id}/dunning/pause	Pause dunning.
GET	/v1/subscriptions/{id}/usage	Read current / closed period usage totals.
GET	/v1/subscriptions/{id}/upcoming-invoice	Preview the next invoice.

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.

commitment

Null for month-to-month. For committed subscriptions:

{
  "months": 12,
  "billing": "monthly",
  "early_cancel": "forbid",
  "auto_renew": true,
  "started_at": "2026-04-01T00:00:00Z",
  "ends_at":    "2027-04-01T00:00:00Z"
}

See Trials & commitments.

dunning

Null when not in dunning. Otherwise:

{
  "policy": "default",
  "attempts": 2,
  "next_attempt_at": "2026-05-09T00:00:00Z",
  "started_at": "2026-05-04T12:00:00Z",
  "exhausts_at": "2026-05-25T12:00:00Z"
}

Webhook events

The full set is in the Event catalog.