About the Draft Subscription Contracts API

The Draft Subscription Contracts API lets you change an existing subscription contract. You make the changes in a draft subscription contract, review the recalculated totals, and then commit the draft subscription contract to apply the changes from the next billing cycle onward.

A subscription contract holds the terms of a buyer's subscription, such as the subscribed items, prices, and billing schedule. To retrieve a subscription contract, call Get Subscription Contract or Query Subscription Contracts. In an order created for a subscription, each subscription line item's subscriptionInfo.id holds the subscription contract ID.

With the Draft Subscription Contracts API, you can:

• Check whether a subscription contract can be edited.
• Create a draft subscription contract from an existing subscription contract.
• Add catalog line items and custom line items.
• Update line item quantities, prices, and catalog reference options, and remove or restore line items.
• Review the recalculated price summary and tax after each change.
• Commit the draft subscription contract to apply the changes to the subscription contract.
• Delete a draft subscription contract without changing the subscription contract.

A draft subscription contract changes future billing cycles. It doesn't change orders that were already created. You can't edit those orders with the Draft Orders API either, because it doesn't support orders with subscription items.

To learn how a draft subscription contract moves from creation to commit, including draftability checks, change tracking, line item limits, recalculated totals, and what a commit applies, see Draft Lifecycle.

Before you begin

It's important to note the following points before starting to code:

• A subscription contract can have 1 draft subscription contract with the DRAFT status at a time, whoever created it.
• Only the identity that created a draft subscription contract can retrieve, update, commit, or delete it. The identity is returned in createdBy.
• Committed changes apply from the next billing cycle onward. The current billing cycle isn't affected.
• A site member can edit only a subscription contract they bought. A site member can't set line item prices or add custom line items.
• A draft subscription contract can have up to 100 line items, including removed line items.

Use cases

• Add a product to a subscription before the next billing cycle
• Change the quantity of a subscription item
• Change the price of a subscription item
• Add a one-off extra to a subscription
• Let a buyer change the variant of a subscription item
• Resume or replace an existing draft
• Discard a subscription edit

Terminology

• Subscription contract: The terms of a buyer's subscription: the items, prices, billing schedule, and buyer, billing, and shipping details. Each billing cycle's order is created from it.
• Draft subscription contract: A temporary, editable copy of a subscription contract. Committing it applies its changes to the subscription contract from the next billing cycle onward.
• Billing cycle: One recurring charge period of a subscription. Billing cycles are numbered from 1. For example, with a monthly subscription, each month is a billing cycle. When a subscription starts with a free trial, the order created at checkout is for cycle 0.
• Draftability: Whether you can create a draft subscription contract for a subscription contract.
• Catalog line item: A line item whose details come from a catalog through the Catalog service plugin.
• Custom line item: A line item whose details you specify yourself.