A subscription contract holds the terms of a buyer's subscription: the items, prices, billing frequency, and buyer, billing, and shipping details agreed on at checkout, or as later changed through draft subscription contracts.
When a buyer checks out with subscription items, a subscription contract is created for each group of items that are billed together. Physical items from the same catalog with identical subscriptionInfo.subscriptionSettings share a subscription contract. Every other subscription item gets its own subscription contract. Each billing cycle, an order is created from the contract's current content. The order's lineItems.subscriptionInfo.id holds the contract ID, and lineItems.subscriptionInfo.cycleNumber holds the billing cycle the order is for.
To change a subscription contract, create a draft subscription contract, edit it, and commit it.
Additional fees applied to the subscription contract.
Discounts applied to the subscription contract.
Billing address and contact details.
Buyer information.
Language for communication with the buyer. For a site that supports multiple languages, this is the language the buyer selected.
Default: Site language
Information about the sales channel the subscription was purchased through.
Date and time the subscription contract was created.
Currency used for the subscription contract's pricing, as a three-letter currency code in ISO-4217 alphabetic format.
Multi-currency details for a subscription paid in a currency other than the site's currency.
Custom fields.
Subscription option description. For example, "1kg of selected coffee, once a month".
Custom field data for the subscription contract object.
Extended fields must be configured in the app dashboard before they can be accessed with API calls.
Subscription contract ID.
Subscription line items. The order for each billing cycle is created with these line items.
In a subscription contract:
lineItems.subscriptionInfo.id is the subscription contract's own ID.lineItems.subscriptionInfo.cycleNumber is always 0. The billing cycle is set on the line items of each cycle's order.subscriptionInfo.title and subscriptionInfo.description hold the subscription contract's title and description, not the line item's own subscription option.refundQuantity, restockQuantity, and depositAmount aren't updated after the line item is added. Refunds, restocks, and fulfillment are recorded on each billing cycle's order.extendedFields and decimalQuantity aren't returned.price is the price before coupons, and the coupons are in appliedDiscounts.Summary of platform fees calculated at checkout, including totals by charge type and a breakdown of individual fees.
Not updated when draft changes are committed. Each billing cycle's order holds the platform fees for that cycle.
Price summary of a single billing cycle.
Recipient address and contact details.
This field may differ from the address in shippingInfo.logistics when:
Revision number, which increments by 1 each time the subscription contract is updated.
Shipping information and selected shipping option details.
Subscription description, in the site's default language and translated into the buyer's language. For example, "1kg of selected coffee, once a month".
For a subscription contract with more than one line item, holds a general name for the subscription.
Subscription terms, such as the billing frequency, the number of billing cycles, and whether the subscription renews automatically.
Subscription title, in the site's default language and translated into the buyer's language. For example, "Monthly coffee subscription".
For a subscription contract with more than one line item, holds a general name for the subscription.
Whether tax is included in line item prices.
Default: false
Subscription option title. For example, "Monthly coffee Subscription".
Date and time the subscription contract was last updated.
Weight measurement unit.
Default: Site's weight unit