Subscription resource - Developer documentation

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

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

status

enum<string>

required

Available options:

active,

paused,

canceled,

failed,

expired,

merged

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.

currentCycle

integer

required

The subscription's billing cycle count. It starts at 0 (before the first billing is completed), changes to 1 (after one billing is completed), and increases by 1 with each subsequent billing.

Required range: x >= 0

currencyCode

string

required

The currency that applies to both item prices and delivery price.

Required string length: 3

deliveryMethod

object

required

Show child attributes

deliveryMethod.type

enum<string>

required

Available options:

shipping,

local-delivery,

pickup

deliveryMethod.title

null | string

required

deliveryMethod.description

null | string

required

items

SubscriptionItem · object[]

required

Minimum array length: 1

Show child attributes

items.id

string<uuid>

required

items.resource

enum<string>

required

Available options:

subscription-item

items.title

string

required

Minimum string length: 1

items.subtitle

null | string

required

Matches the variant title in most cases

Minimum string length: 1

items.quantity

integer

required

Required range: x >= 1

items.totalPrice

number

required

Final item price including all discounts and taxes

Required range: x >= 0

items.recurringCycleLimit

null | integer

required

The number of billing cycles for which this item will be applied. After the recurring cycle limit is met the item will be removed from the subscription.

Required range: x >= 1

items.canceledAt

null | string<date-time>

required

Cancellation date of the item.

items.billingPolicy

BillingPolicy · object

required

Show child attributes

items.billingPolicy.interval

required

Available options:

DAY

items.billingPolicy.intervalCount

integer

required

Required range: 1 <= x <= 365

items.billingPolicy.anchors

object[]

required

Show child attributes

items.billingPolicy.anchors.type

required

Available options:

WEEKDAY

items.billingPolicy.anchors.day

integer

required

Required range: 1 <= x <= 31

items.billingPolicy.anchors.month

null | integer

required

Required range: 1 <= x <= 12

items.billingPolicy.anchors.cutoffDay

null | integer

required

Required range: 1 <= x <= 31

items.billingPolicy.minCycles

null | integer

required

Required range: x >= 1

items.billingPolicy.maxCycles

null | integer

required

Required range: x >= 1

items.deliveryPolicy

DeliveryPolicy · object

required

Show child attributes

items.deliveryPolicy.interval

required

Available options:

DAY

items.deliveryPolicy.intervalCount

integer

required

Required range: 1 <= x <= 365

items.deliveryPolicy.anchors

object[]

required

Show child attributes

items.deliveryPolicy.anchors.type

required

Available options:

WEEKDAY

items.deliveryPolicy.anchors.day

integer

required

Required range: 1 <= x <= 31

items.deliveryPolicy.anchors.month

null | integer

required

Required range: 1 <= x <= 12

items.deliveryPolicy.anchors.cutoffDay

null | integer

required

Required range: 1 <= x <= 31

items.variant

required

This field is expandable.

Minimum string length: 1

discounts

SubscriptionDiscount · object[]

required

Show child attributes

discounts.id

string<uuid>

required

discounts.resource

enum<string>

required

Available options:

subscription-discount

discounts.title

null | string

required

The title of the discount shown to customers, typically displayed as a discount code.

Minimum string length: 1

discounts.target

object

required

Option 1
Option 2

Show child attributes

discounts.target.type

enum<string>

required

Available options:

shipping

discounts.value

object

required

Option 1
Option 2

Show child attributes

discounts.value.amount

number

required

discounts.value.type

enum<string>

required

Available options:

fixed-amount

discounts.value.appliesOnEachItem

boolean

required

When true, the amount will be proportionally split among all the items.

discounts.recurringCycleLimit

null | integer

required

The number of billing cycles for which this discount will be applied. After the recurring cycle limit is met the discount will be removed from the subscription.

Required range: x >= 1

paymentMethod

required

This field is expandable.

deliveryAddress

object

required

Show child attributes

deliveryAddress.firstName

null | string

required

Customer's first name.

Minimum string length: 1

deliveryAddress.lastName

null | string

required

Customer's last name.

Minimum string length: 1

deliveryAddress.address1

null | string

required

Primary street address.

Minimum string length: 1

deliveryAddress.address2

null | string

required

Additional address information (apartment, suite, etc.)

Minimum string length: 1

deliveryAddress.zip

null | string

required

Postal/ZIP code.

Minimum string length: 1

deliveryAddress.city

null | string

required

City name.

Minimum string length: 1

deliveryAddress.country

null | string

required

Full country name.

Minimum string length: 1

deliveryAddress.countryCode

null | string

required

Two-letter country code (ISO 3166-1).

Required string length: 2

deliveryAddress.provinceCode

null | string

required

Province/state code.

Minimum string length: 1

deliveryAddress.province

null | string

required

Full province/state name.

Minimum string length: 1

deliveryAddress.phone

null | string

required

Contact phone number.

Minimum string length: 1

deliveryAddress.company

null | string

required

Company name.

Minimum string length: 1

deliveryPrice

number

required

The base delivery price associated with the selected delivery method.

Required range: x >= 0

Core Resources

​Search query fields

​Reference

Search query fields

Reference