Subscription resource - Developer documentation

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "resource": "subscription",
  "serial": "1042",
  "status": "active",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "canceledAt": "2023-11-07T05:31:56Z",
  "nextBillingDate": "2024-02-15T10:00:00.000Z",
  "currentCycle": 1,
  "currencyCode": "USD",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "deliveryMethod": {
    "title": "<string>",
    "description": "<string>"
  },
  "customAttributes": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resource": "subscription-item",
      "title": "Monthly Coffee Blend",
      "subtitle": "250g / Ground",
      "quantity": 1,
      "totalPrice": 24.99,
      "recurringCycleLimit": 3,
      "canceledAt": "2023-11-07T05:31:56Z",
      "billingPolicy": {
        "interval": "DAY",
        "intervalCount": 183,
        "anchors": [
          {
            "type": "WEEKDAY",
            "day": 16,
            "month": 6,
            "cutoffDay": 16
          }
        ],
        "minCycles": 2,
        "maxCycles": 2
      },
      "deliveryPolicy": {
        "interval": "DAY",
        "intervalCount": 183,
        "anchors": [
          {
            "type": "WEEKDAY",
            "day": 16,
            "month": 6,
            "cutoffDay": 16
          }
        ]
      },
      "customAttributes": [
        {
          "key": "<string>",
          "value": "<string>"
        }
      ],
      "variant": "<string>",
      "product": "<string>"
    }
  ],
  "discounts": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "resource": "subscription-discount",
      "title": "<string>",
      "target": {
        "type": "shipping"
      },
      "value": {
        "amount": 123,
        "type": "fixed-amount",
        "appliesOnEachItem": true
      },
      "recurringCycleLimit": 2
    }
  ],
  "paymentMethod": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "deliveryAddress": {
    "firstName": "<string>",
    "lastName": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "zip": "<string>",
    "city": "<string>",
    "country": "<string>",
    "countryCode": "<string>",
    "provinceCode": "<string>",
    "province": "<string>",
    "phone": "<string>",
    "company": "<string>"
  },
  "deliveryPrice": 1
}

The Subscription object stores information and rules defining the contract between a business and a customer. It is created when a customer purchases a subscription-based product.

Search query fields

Field	Description	Type
id	The subscription identifier	string
serial	The incremental subscription number	string
status	The subscription status	string
createdAt	The date subscription was created	date
updatedAt	The last date the subscription was updated	date
nextBillingDate	The upcoming next billing date	date
canceledAt	The date subscription was cancelled	date

Reference

string<uuid>

required

Unique subscription identifier (UUID).

Example:

"550e8400-e29b-41d4-a716-446655440000"

resource

enum<string>

required

Available options:

subscription

serial

string

required

Unique serial number that increments sequentially with each new subscription within a store.

Minimum string length: 1

Example:

"1042"

status

enum<string>

required

Subscription lifecycle status. active: billing runs on schedule; paused: billing suspended until resumed; canceled: permanently stopped (can be reactivated); failed: latest billing attempt failed; expired: reached configured end date; merged: consolidated into another subscription.

Available options:

active,

paused,

canceled,

failed,

expired,

merged

Example:

"active"

createdAt

string<date-time>

required

Purchase date of the subscription.

updatedAt

string<date-time>

required

Last update date of the subscription.

canceledAt

null | string<date-time>

required

Cancellation date of the subscription.

nextBillingDate

null | string<date-time>

required

The next billing date determines when the renewal process begins its billing phase. When billing succeeds, it creates one order—or multiple orders for prepaid subscriptions.

Example:

"2024-02-15T10:00:00.000Z"

currentCycle

integer

required

The subscription's billing cycle count. Starts at 0 before the first billing completes, increments by 1 with each successful billing.

Required range: x >= 0

Example:

1

currencyCode

string

required

ISO 4217 currency code that applies to both item prices and delivery price.

Required string length: 3

Example:

"USD"

billingPolicy

object

required

How often and when the subscription is billed.

Show child attributes

deliveryPolicy

object

required

How often shipments are dispatched. Usually matches the billing policy.

Show child attributes

deliveryMethod

null | object

required

Show child attributes

customAttributes

object[]

required

Arbitrary key-value pairs attached to this subscription. In the Customer API, attributes whose key starts with _ are hidden and excluded.

Show child attributes

items

SubscriptionItem · object[]

required

Minimum array length: 1

Show child attributes

discounts

SubscriptionDiscount · object[]

required

Show child attributes

paymentMethod

required

CustomerPaymentMethod id when not expanded, or the full CustomerPaymentMethod object when the field name is included in the expand query parameter. Can be null.

deliveryAddress

null | object

required

Show child attributes

deliveryPrice

number

required

The base delivery price associated with the selected delivery method.

Required range: x >= 0

List products List subscriptions

⌘I

​Search query fields

​Reference

Search query fields

Reference