Draft Subscription Contracts API: Draft Lifecycle

This article explains how a draft subscription contract works from creation to commit: its statuses and expiry, the checks that decide whether a subscription contract can be edited, how changes are tracked and recalculated, and what a commit applies to the subscription contract.

Statuses

A draft subscription contract has 2 statuses:

Status	Meaning
DRAFT	You can update the draft subscription contract and commit it.
COMMITTED	The changes were applied to the subscription contract. You can't update or delete the draft subscription contract anymore.

Typical flow

A typical flow looks like this:

1. Call Get Subscription Contract Draftability to check that the subscription contract can be edited.
2. Call Create Draft Subscription Contract.
3. Call Add Line Items and Update Line Items as many times as you need.
4. Call Commit Draft Subscription Contract, or call Delete Draft Subscription Contract to discard the changes.

After you commit or delete a draft subscription contract, you can create another draft subscription contract for the same subscription contract.

Expiry

A draft subscription contract with the DRAFT status expires 24 hours after its last change, or when the billing cycle in its target.contractTarget.nextCycleNumber starts. When anyone then creates a draft subscription contract for the same subscription contract, the expired draft subscription contract is deleted and replaced.

Draftability

Not every subscription contract can be edited. Get Subscription Contract Draftability returns draftable and, when it's false, a list of nonDraftableReasons. For example, a subscription contract can't be edited when its items come from more than 1 catalog, or when another identity already has a draft subscription contract for it. When a site member checks a subscription contract they didn't buy, the only reason returned is NOT_SUBSCRIPTION_CONTRACT_BUYER.

The response also returns currentCycleNumber, the billing cycle the subscription is in now. When you create the draft subscription contract, set target.contractTarget.nextCycleNumber to currentCycleNumber + 1. Any other value fails with INVALID_NEXT_CYCLE_NUMBER.

The same checks run again when you commit. If the subscription contract can no longer be edited, the commit fails with SUBSCRIPTION_CONTRACT_NOT_DRAFTABLE.

Create a draft subscription contract

A new draft subscription contract starts as a copy of the subscription contract's line items, discounts, additional fees, buyer info, and billing, shipping, and recipient details. Discounts and additional fees that end before the next billing cycle aren't copied.

If you call Create Draft Subscription Contract again for the same subscription contract with the same target, it returns your existing draft subscription contract instead of creating another one, and preexistingDraftSubscriptionContract is true.

Change tracking

A draft subscription contract shows how each value differs from the subscription contract:

• Each line item has a changeType: UNCHANGED, ADDED, CHANGED, or REMOVED. For a CHANGED line item, changedDetails holds the values before the change.
• Buyer, shipping, billing, recipient, and business location details also have a changeType field. You can't change these details with this API yet, so their changeType is UNCHANGED. The shipping price can still change when totals are recalculated.
• Each discount and additional fee has a source and an applied flag. Removing a line item sets applied to false for the discounts and additional fees linked to it. Restoring the line item's original quantity sets applied back to true. When settings.specificItemsCouponBehavior is ITEM_SUBTOTAL_INCLUDES_DISCOUNT, a GLOBAL discount stays applied while it's still linked to another line item.

Removed line items stay in the draft subscription contract with changeType set to REMOVED, so you can restore them. A line item that you added and then removed is deleted from the draft subscription contract.

Line items

You can add 2 types of line items with Add Line Items:

• Catalog line items: The item details come from the catalog through the Catalog service plugin. All catalog line items in a draft subscription contract must come from the same catalog.
• Custom line items: You specify all the item details. Custom line items don't call the Catalog service plugin. Site members can't add custom line items.

Added line items get the billing schedule in subscriptionSettings.

Update Line Items has some limits:

• You can't change the quantity of a line item linked to a discount, except to remove it or restore its original quantity. Changing its price or catalog reference options sets applied to false for the linked discounts. Exception: when settings.specificItemsCouponBehavior is ITEM_SUBTOTAL_INCLUDES_DISCOUNT, a GLOBAL discount stays applied and is recalculated.
• You can't change the quantity, price, or catalog reference options of a line item linked to an additional fee. You can remove it or restore its original quantity.
• You can't change the quantity or catalog reference options of a line item stocked at more than 1 location. You can remove it or update its price.
• You can't change the catalog reference options of a custom line item.

Recalculated totals

Create, retrieve, add, and update calls return a calculatedDraftSubscriptionContract object. It holds the draft subscription contract with totals recalculated for the next billing cycle, and any calculationErrors. For example, tax can't be calculated without a required address.

The draft subscription contract is saved even when the recalculation returns errors. Fix the errors before you commit, because the commit recalculates the totals again and fails on any calculation error except a tax calculation error for a missing address subdivision.

Commit

Commit Draft Subscription Contract applies the changes to the subscription contract from the next billing cycle onward, sets the draft subscription contract's status to COMMITTED, and returns it. The commit triggers the Subscription Contract Committed event, which holds every change that was applied, and the Subscription Contract Updated event.

The commit also adds to the subscription contract every additional fee with source set to AUTOMATIC and applied set to true. The totals recalculation adds these fees as a result of your changes. The commit removes from the subscription contract every discount and additional fee whose applied is false.

By default, the buyer gets a notification that the subscription was updated. To skip it, set settings.sendNotificationsToBuyer to false.

The commit fails when:

• The draft subscription contract has no changes.
• All line items are removed.
• A line item has an undetermined price.
• The recalculation returns an error, such as a missing billing or shipping address for tax calculation.