API reference

Subscriptions

A subscription is a customer's repeating purchase. Nobody's wallet is ever charged automatically: crypto has no pull payment, and the platform never asks for one. Each period creates exactly one order and the customer is reminded to pay it. The cycle, for a period ending at E:

At E minus the first entry of reminder_days (default 7 days) the renewal order is created, expiring at E plus grace_days, and, if they last paid with the Orrerie app and agreed, the customer is sent a push that opens a one-tap renewal (Orrerie emails no customer yet: send the checkout link yourself). Event: subscription.renewal_due. The later entries (default 3 days and 1 day before) are reminders for the same order.
At E unpaid: past_due. The merchant's service should still work during grace (default 3 days).
At E plus grace unpaid: unpaid (subscription.unpaid: this is when to withdraw access) and the order expires. After 30 days unpaid: ended.
When a period order is paid: active, the period advances, subscription.renewed.
The renewal checkout may offer to pay several periods at once (prepaid_periods_allowed, default 1, 3, 6, 12).

The states, in the order an object moves through them. Where a step lists several, the object takes one of them.

incompleteFirst order not yet paid
active
past_due
unpaid
ended

Outside that order:

incomplete_expiredThe first order expired unpaid; final
paused
cancelled

The `subscription` object

JSON

{
  "id": "sub_9q5v9rq2naessbxsrec2tsw0",
  "object": "subscription",
  "livemode": true,
  "created": "2026-10-01T08:05:00.000Z",
  "updated": "2026-10-01T08:09:00.000Z",
  "status": "active",
  "customer": "cus_8ea07c40qsvv19f7rgmeb8ha",
  "items": [
    {
      "price": "price_s5n6hhtmyv5erqb81efqgjy6",
      "quantity": 1
    }
  ],
  "amount": "18.00",
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "reminder_days": [
    7,
    3,
    1
  ],
  "grace_days": 3,
  "prepaid_periods_allowed": [
    1,
    3,
    6,
    12
  ],
  "proration": "none",
  "current_period_start": "2026-10-01T08:09:00.000Z",
  "current_period_end": "2026-11-01T08:09:00.000Z",
  "prepaid_until": "2026-11-01T08:09:00.000Z",
  "latest_order": "ord_ayyh1f26ajmj807xjy6ezyfd",
  "renewal": {
    "order": null,
    "checkout_url": null,
    "opens_at": "2026-10-25T08:09:00.000Z",
    "due_at": "2026-11-01T08:09:00.000Z",
    "grace_ends_at": "2026-11-04T08:09:00.000Z"
  },
  "cancel_at_period_end": false,
  "cancelled_at": null,
  "paused_at": null,
  "ended_at": null,
  "cancellation_reason": null,
  "metadata": {}
}

Table: The subscription object
Field	Meaning
`status`	One of `incomplete`, `incomplete_expired`, `active`, `past_due`, `unpaid`, `paused`, `cancelled`, `ended`.
`interval`	One of `day`, `week`, `month`, `year`.
`proration`	One of `none`, `proportional`.

Every field

Fields of the `subscription` object

Fields of the subscription object
Field	Type	Meaning
`ended_reason`	string or null	Why an ended subscription ended. One of `unpaid_30_days`, `periods_complete`, `null`.
`max_periods`	integer or null	A fixed number of periods after which the subscription ends; `null` for open-ended.
`id`	string	Unique identifier: the object prefix, an underscore, 24 lower-case Crockford base32 characters.
`object`	string	The type of this object.
`livemode`	boolean	`true` for live mode (real money); `false` for test mode (simulated payments).
`created`	string (date-time)	When the object was created. RFC 3339, UTC, milliseconds.
`updated`	string (date-time)	When the object last changed.
`status`	string	One of `incomplete`, `incomplete_expired`, `active`, `past_due`, `unpaid`, `paused`, `cancelled`, `ended`.
`customer`	object	The `cus_` id subscribed, or the customer object when expanded.
`items`	array of objects	What each period charges.
`items[].price`	string	The `price_` id of a recurring price.
`items[].quantity`	integer	How many of it.
`amount`	string	What each period costs, a decimal string.
`currency`	string	The currency of `amount`.
`interval`	string	One of `day`, `week`, `month`, `year`.
`interval_count`	integer	How many intervals make one period.
`reminder_days`	array of integers	Days before a period ends that the renewal is opened and the customer reminded.
`grace_days`	integer	Days after a period ends that its renewal may still be paid.
`prepaid_periods_allowed`	array of integers	How many periods the customer may pay at once at renewal.
`proration`	string	One of `none`, `proportional`.
`current_period_start`	string (date-time) or null	When the period being paid for started; `null` before the first one.
`current_period_end`	string (date-time) or null	When it ends; `null` before the first period.
`prepaid_until`	string (date-time) or null	When the periods already paid for run out; `null` before the first payment.
`latest_order`	object	`null` for a subscription in its trial (no order yet).
`renewal`	object	The next renewal.
`renewal.order`	string or null	The `ord_` id of the renewal order; `null` until the renewal opens.
`renewal.checkout_url`	string or null	The page where the customer pays the renewal; `null` until it opens.
`renewal.opens_at`	string (date-time)	When the renewal order is made and the customer reminded.
`renewal.due_at`	string (date-time)	When the period ends.
`renewal.grace_ends_at`	string (date-time)	When an unpaid renewal makes the subscription `unpaid`.
`cancel_at_period_end`	boolean	`true` when the subscription ends when the current period does.
`cancelled_at`	string or null	When it was cancelled; `null` unless it was.
`paused_at`	string or null	When it was paused; `null` unless it is paused.
`ended_at`	string or null	When it ended; `null` unless it has.
`cancellation_reason`	string or null	The reason given when it was cancelled; `null` for none.
`metadata`	object	Up to 50 keys of your own data. Key up to 40 characters, value a string up to 500 characters. Never used by Orrerie; never put secrets or personal data here.

Endpoints

Events

Webhook events whose data.object is an object of this page.