Combine subscription contracts

When a customer has several subscription contracts whose billing cycles fall on the same date, you can concatenate those cycles so that they bill as one order. One billing attempt on any cycle in the group creates one order that's linked to every contract in the group. The recurring contracts don't change. For the complete input model and reference tables, refer to Concatenate billing cycles in the migration guide.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the read_own_subscription_contracts and write_own_subscription_contracts access scopes. Learn how to configure your access scopes using Shopify CLI.
• You've created products and product variants in your development store.

• Ask Shopify to enable your app for the early access subscriptionBillingCycleContractConcatenateCalculate mutation.
• Use the unstable GraphQL Admin API version.
• Create at least two active subscription contracts for the same customer. Each contract must have recurring billing and delivery policies.
• Familiarize yourself with billing cycles and managing billing cycle contracts.

Anchor to What you can createWhat you can create

The following diagram shows a preview of how combining contracts works.

In this example, the customer has two contracts, one weekly and one bi-weekly, for coffee and tea. Both contracts have billing cycles on 01/01, 01/15, and 01/29. You can combine the subscription orders to consolidate fulfillment and shipping costs into one order.

Anchor to How concatenation worksHow concatenation works

The contract that you pass as contractId is the anchor. The order bills on the anchor's cycle and uses its payment method and policies. The cycles in concatenatedBillingCycles are members. Committing attaches each member cycle to the anchor's edited contract, so one billing attempt bills the whole group. The recurring contracts don't change.

The calculate API doesn't merge content from the contracts. The lines, manualDiscounts, and discountCodes fields describe the complete order. A line that you leave out isn't billed. You must also provide the delivery method for the combined order.

Concatenation uses an asynchronous flow that's scoped to the selected cycles:

1. Query each cycle and its current contract state.
2. Submit the anchor, the members, and the complete order.
3. Poll the calculation or wait for a webhook.
4. Review the calculated result.
5. Commit a successful calculation.

The cycles must meet the following requirements:

• No cycle in the group has ended, is skipped, has a billing attempt that hasn't failed, or is already part of a concatenation.
• Every contract in the group is active and isn't prepaid.
• Every member contract belongs to the same customer, uses the same currency, and is owned by the same app as the anchor.
• Include between one and 50 member cycles. Exclude the anchor, and name each contract only once.

Refer to the migration guide for the complete requirements on the cycles.

Anchor to Step 1: Read the lines on each cycleStep 1: Read the lines on each cycle

Query each participating billing cycle to collect the line IDs and values that you'll restate in the combined order. If editedContract is set, then read its lines. If editedContract is null, then read the lines from sourceContract. Don't use edited to select the contract, because a schedule-only edit also sets edited to true. The variantId value is the productVariantId value that you pass in Step 2.

Anchor lines keep their id. Member lines use their ID as originLineId in Step 2. Each line input in Step 2 is a complete restatement of the line, so read every value that you want to keep. A field that you leave out is cleared or recalculated, even when you include id or originLineId. If a line has line-scoped discounts, read them too and restate them in discounts. Refer to the migration guide's line fields for the mapping from SubscriptionLine to the line input, and to Preserve a line's state when you change it for the rule.

Anchor to Step 2: Calculate the concatenationStep 2: Calculate the concatenation

Call subscriptionBillingCycleContractConcatenateCalculate with the anchor, the member cycles, and the complete order. Map currentPrice to priceOverride, sellingPlanId to originSellingPlanId, and pricingPolicy to appManagedPricingPolicy. discounts is required; pass [] when the line has no line-scoped discounts. The following example restates the values that Step 1 returned for two lines without a pricing policy:

The lines array is the complete order. Use id for an anchor line and originLineId for a member line. originLineId must identify a line on a member contract and can't be combined with id. Omit both fields to add a new line.

Anchor to Step 3: Poll for the calculation resultStep 3: Poll for the calculation result

The calculate mutation returns a pending calculation. Poll for the result and review it before committing. The SubscriptionContractCalculationSuccess result contains projectedOrderTotals for the combined order.

Contract calculations run asynchronously. Most calculations finish in less than three seconds, but Functions and external services can increase processing time. Use the calculation ID returned by the calculate mutation to query subscriptionContractCalculation:

The query returns one of the following types:

Wait two seconds before the first poll, poll every second, and stop after 30 seconds. If the calculation is still pending, then retry later or wait for a webhook instead of increasing the polling frequency.

Anchor to Review the calculated contractReview the calculated contract

Before committing, inspect the following fields on SubscriptionContractCalculationSuccess:

• calculatedContract: The complete contract snapshot that the commit applies.
• projectedOrderTotals: The projected merchandise, delivery, discount, tax, and total amounts.
• warnings: Existing-data or compatibility problems that don't prevent the calculation from succeeding.

A successful calculation is immutable. If you need to change the input, then start a new calculation and commit only the result that you want to make active.

Anchor to Use webhooks instead of pollingUse webhooks instead of polling

For event-driven processing, subscribe to the following webhook topics:

Create a webhook subscription with webhookSubscriptionCreate:

Use admin_graphql_api_id to query the completed calculation. Webhook delivery doesn't commit the result automatically.

Anchor to Step 4: Commit the calculationStep 4: Commit the calculation

Commit the successful calculation with subscriptionContractCalculationCommit. For a concatenation, the returned SubscriptionBillingCycleEditedContract lists every cycle in the group:

Shopify checks the requirements on the cycles again when you commit.

Anchor to Step 5: Fetch the combined contractStep 5: Fetch the combined contract

After the commit, query any cycle in the group to read the shared edited contract and confirm the group membership. Every member returns the same editedContract with edited: true. The billingCycles connection lists the whole group:

Anchor to Step 6: Create an orderStep 6: Create an order

When the billing date comes, call subscriptionBillingCycleCharge on any contract in the group to create one linked order:

A billing attempt on a concatenated cycle can return BILLING_CYCLE_GROUP_ALREADY_ATTEMPTED, BILLING_CYCLE_GROUP_CYCLE_SKIPPED, or BILLING_CYCLE_GROUP_CONTENDED in addition to the usual BillingAttemptUserError codes. Refer to Bill the concatenated cycles for details.

Anchor to Remove a concatenationRemove a concatenation

To dissolve a group before it bills, call subscriptionBillingCycleEditDelete on any cycle in the group. Shopify removes the shared edit from every cycle in the group, and each cycle returns to its own recurring contract:

Anchor to Next stepsNext steps

• Learn how to manage orders and fulfillments for prepaid subscriptions.
• Learn how to bulk charge multiple contracts at the same time.
• Refer to the migration guide's Concatenate billing cycles section for the complete input reference.
• Use the legacy SubscriptionDraft combine guide while maintaining an older integration.