Skip to main content
A Subscription object represents an ongoing billing relationship where a customer is charged on a recurring basis. Subscriptions are created when a customer purchases a subscription Product and manage the lifecycle of recurring Payments. Subscriptions track billing intervals, status changes, and link to all associated Payments and Orders. You can use the API to manage subscriptions including updating, pausing, and cancelling them.

​
Endpoints

MethodEndpointDescription
GET/v0/subscriptions/listList and filter subscriptions
POST/v0/subscriptions/createCreate a new subscription
GET/v0/subscriptions/{subscriptionIdOrNumber}Retrieve a subscription
PATCH/v0/subscriptions/{subscriptionIdOrNumber}/updateUpdate a subscription
POST/v0/subscriptions/{subscriptionIdOrNumber}/chargeCharge a subscription immediately
PATCH/v0/subscriptions/{subscriptionIdOrNumber}/cancelCancel a subscription
PATCH/v0/subscriptions/{subscriptionIdOrNumber}/pause-collectionPause subscription billing

​
The Subscription object

​
object
string
Object type identifier. Always "subscription" for Subscription objects.
​
id
string
required
Subscription identifier, based on the initial order number.
​
status
string
required
Current subscription status. Possible values: active, past_due, canceled, unpaid, incomplete, incomplete_expired, trialing, paused
​
createdAt
integer | null
Unix timestamp (milliseconds) when the subscription was created.
​
currentIntervalStart
integer | null
Unix timestamp (milliseconds) when the current billing interval started.
​
currentIntervalEnd
integer | null
Unix timestamp (milliseconds) when the current billing interval ends.
​
cancelAtIntervalEnd
boolean
Whether the subscription will cancel at the end of the current interval. Defaults to false.
​
canceledAt
integer | null
Unix timestamp (milliseconds) when the subscription was cancelled, if applicable.
​
userId
string | null
UUID of the subscribed User.
​
user
User | null
Expanded User object with basic subscriber information.
​
orderId
string
required
UUID of the initial Order that created this subscription.
​
orderNumber
string
required
Human-readable number of the initial order.
​
order
Order
required
Expanded Order object for the initial subscription order.
​
lastPaymentId
string | null
UUID of the most recent Payment for this subscription.
​
lastPaymentNumber
string | null
Human-readable number of the most recent payment.
​
lastPayment
Payment | null
Expanded Payment object for the most recent charge.

​
Subscription lifecycle

​
Example response

{
  "status": "success",
  "data": {
    "subscription": {
      "object": "subscription",
      "id": "#SUB123DEF456",
      "status": "active",
      "createdAt": 1705590000000,
      "currentIntervalStart": 1708268400000,
      "currentIntervalEnd": 1710946800000,
      "cancelAtIntervalEnd": false,
      "canceledAt": null,
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "user": {
        "object": "user",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "johndoe"
      },
      "orderId": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "#ABC123DEF456",
      "order": {
        "object": "order",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "number": "#ABC123DEF456",
        "status": "PAID"
      },
      "lastPaymentId": "660e8400-e29b-41d4-a716-446655440001",
      "lastPaymentNumber": "#PAY789GHI012",
      "lastPayment": {
        "object": "payment",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "subscription_interval",
        "number": "#PAY789GHI012",
        "status": "PAID"
      }
    }
  }
}

​
Webhook events

EventTypical use
subscription_createdSubscription exists; first payment may still be processing
payment_successFirst or recurring charge succeeded — fulfill here
subscription_intervalNew billing period charged (renewal)
subscription_updatedPlan change, cancel-at-period-end, trial ended, etc.
subscription_cancelledSubscription ended
See Event types and Webhooks overview for why subscription_created can include PENDING payments and why you should not rely on it alone for access grants.

Payments

Payment transactions for subscriptions

Orders

Initial orders creating subscriptions

Users

Subscribed customers

Events

Subscription webhook events