Skip to main content

Manage billing cycle contracts

Billing cycle contracts inherit the contract lines, pricing policy, and delivery policy from the billing cycle's source subscription contract. You might want to edit the contract information on a single billing cycle to make a temporary change, such as replacing an out-of-stock product for one cycle.

This guide shows you how to submit a single-cycle edit to subscriptionBillingCycleContractEditCalculate, review Shopify's calculated result, and commit it to the targeted cycle. Fields that you omit remain unchanged.

Available in the 2026-10 release candidate

The SubscriptionContractCalculation API is available in the GraphQL Admin API 2026-10 release candidate. If your app uses the SubscriptionDraft API, refer to the legacy billing cycle edit guide.

Combining contracts stays on the SubscriptionDraft API

The Calculation API has no calculate concatenate mutation, and subscriptionBillingCycleContractEditCalculate rejects a cycle that's already part of a concatenation with an INVALID user error explaining that the cycle is concatenated. To combine subscription contracts, continue using the SubscriptionDraft API.

Anchor to RequirementsRequirements

Note
  • Most subscriptions, pre-order and try before you buy apps need to request API access through the Partner Dashboard. We give API access to apps that are designed according to our principles for subscriptions, pre-order and TBYB apps.
  • Public apps that use subscriptions, pre-order or TBYB need to meet specific requirements to be published on the Shopify App Store.
  • Custom apps created in the Shopify admin can't use subscriptions, pre-order or TBYB because these apps can't use extensions or request access to protected scopes. If you're building a solution for a single store, then build your custom app in the Partner Dashboard.
  • Use the GraphQL Admin API version 2026-10 or later.
  • Create an active subscription contract with a recurring billing and delivery policy.
  • Familiarize yourself with billing cycles.

Anchor to How billing cycle calculation worksHow billing cycle calculation works

A single-cycle edit uses the same asynchronous calculate and commit flow as a contract update, scoped to one billing cycle:

  1. Query the billing cycle and its current contract state.
  2. Submit the fields that you want to change for the targeted cycle.
  3. Poll the calculation or wait for a webhook. Shopify emits subscription_contract_calculations/succeed when a calculation succeeds and subscription_contract_calculations/fail when it fails or is voided.
  4. Review the calculated contract, projected totals, warnings, or errors.
  5. Commit a successful calculation.

Committing applies the edit to the targeted cycle only. It doesn't change the source contract or other cycles, and it doesn't modify orders that have already been created.

Note

You can only edit a current or future cycle on a non-prepaid contract that isn't part of a concatenation. subscriptionBillingCycleContractEditCalculate rejects prepaid contracts, past cycles, and concatenated cycles with a user error.

Anchor to Step 1: Query the billing cycleStep 1: Query the billing cycle

Query the billing cycle before calculating an edit so you have its current line IDs. A cycle that's already been edited exposes its current lines on editedContract; a cycle that hasn't returns null for editedContract, so read the lines from sourceContract instead. The calculation compounds on the edited contract when one exists, and otherwise on the source contract. When you rebuild the lines array, a line's variantId is the value that you pass as productVariantId in the input. Select the cycle by index or date:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL query

query {
subscriptionBillingCycle(
billingCycleInput: {
contractId: "gid://shopify/SubscriptionContract/123"
selector: { date: "2026-01-10T00:00:00Z" }
}
) {
subscriptionBillingCycle {
cycleIndex
edited
sourceContract {
lines(first: 50) {
nodes {
id
quantity
variantId
currentPrice {
amount
currencyCode
}
}
}
}
editedContract {
lines(first: 50) {
nodes {
id
quantity
variantId
currentPrice {
amount
currencyCode
}
}
}
}
}
userErrors {
field
message
}
}
}

Anchor to Step 2: Calculate the editStep 2: Calculate the edit

Call subscriptionBillingCycleContractEditCalculate with the contract ID, a billingCycleSelector, and the fields to change for that cycle in billingCycleEditInput. Contract-level attributes such as the billing policy, delivery policy, and payment method can't be changed by a billing cycle edit. The following example updates an existing line's quantity and adds a new line:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL mutation

mutation EditBillingCycleContract {
subscriptionBillingCycleContractEditCalculate(
contractId: "gid://shopify/SubscriptionContract/123"
billingCycleSelector: { date: "2026-01-10T00:00:00Z" }
billingCycleEditInput: {
withMerchandiseCustomizations: true
lines: [
{
productVariantLine: {
id: "gid://shopify/SubscriptionLine/existing-line-uuid"
productVariantId: "gid://shopify/ProductVariant/111"
quantity: 2
customAttributes: []
discounts: []
}
}
{
productVariantLine: {
productVariantId: "gid://shopify/ProductVariant/222"
quantity: 1
customAttributes: []
discounts: []
}
}
]
}
) {
subscriptionContractCalculation {
... on SubscriptionContractCalculationPending {
id
}
}
userErrors {
field
message
code
}
}
}

JSON response

{
"data": {
"subscriptionBillingCycleContractEditCalculate": {
"subscriptionContractCalculation": {
"id": "gid://shopify/SubscriptionContractCalculation/789"
},
"userErrors": []
}
}
}

If the mutation returns a user error, then correct the input before polling. Shopify doesn't create an asynchronous calculation when input validation fails.

Collections replace existing values

When you provide lines or manualDiscounts, the array replaces the complete existing collection for the targeted cycle. Include the IDs and values for every existing item that you want to keep. Omit an existing item to remove it, and omit id from a new item.

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.

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:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL query

query PollSubscriptionContractCalculation($id: ID!) {
subscriptionContractCalculation(id: $id) {
__typename
... on SubscriptionContractCalculationPending {
id
}
... on SubscriptionContractCalculationSuccess {
id
calculatedContract {
id
lines(first: 10) {
nodes {
id
quantity
title
variantId
}
}
}
warnings {
code
message
}
projectedOrderTotals {
subtotal {
amount
currencyCode
}
totalDelivery {
amount
currencyCode
}
totalTax {
amount
currencyCode
}
totalMerchandiseDiscounts {
amount
currencyCode
}
totalDeliveryDiscounts {
amount
currencyCode
}
total {
amount
currencyCode
}
}
}
... on SubscriptionContractCalculationFailure {
id
errors {
code
message
}
}
}
}

Variables

{
"id": "gid://shopify/SubscriptionContractCalculation/789"
}

Pending response

{
"data": {
"subscriptionContractCalculation": {
"__typename": "SubscriptionContractCalculationPending",
"id": "gid://shopify/SubscriptionContractCalculation/789"
}
}
}

The query returns one of the following types:

TypeMeaningAction
SubscriptionContractCalculationPendingShopify initiated or is processing the calculation.Continue polling.
SubscriptionContractCalculationSuccessThe calculated contract is ready to review and commit.Review the result before committing.
SubscriptionContractCalculationFailureThe calculation failed (processed with errors) or Shopify voided it (never processed, for example, because of an infrastructure issue).If it failed, read errors and correct the input before calculating again. If it was voided, errors is empty and there's nothing to fix in the input, so retry the calculation.

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.

Review warnings

A successful calculation can contain warnings. Review them before committing because they can identify disabled currencies, delivery configuration problems, or other existing contract data that Shopify preserved instead of blocking the update.

Anchor to Use webhooks instead of pollingUse webhooks instead of polling

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

TopicDescription
subscription_contract_calculations/succeedThe calculation succeeded and is ready to review and commit.
subscription_contract_calculations/failThe calculation failed or Shopify voided it. A failed calculation has errors to query; a voided one has empty errors, so retry it.

Create a webhook subscription with webhookSubscriptionCreate:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL mutation

mutation CreateCalculationWebhook {
webhookSubscriptionCreate(
topic: SUBSCRIPTION_CONTRACT_CALCULATIONS_SUCCEED
webhookSubscription: {
callbackUrl: "https://example.com/webhooks/calculation-success"
format: JSON
}
) {
webhookSubscription {
id
}
userErrors {
field
message
}
}
}

Webhook payload

{
"id": 789,
"admin_graphql_api_id": "gid://shopify/SubscriptionContractCalculation/789",
"state": "succeeded"
}

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

Committing applies the calculated contract to the targeted billing cycle. Call subscriptionContractCalculationCommit. A billing cycle edit commits an ephemeral contract, so the committed contract returns as a SubscriptionBillingCycleEditedContract, not a SubscriptionContract. Select that fragment to read the edited cycle's fields:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL mutation

mutation CommitBillingCycleEditCalculation {
subscriptionContractCalculationCommit(
id: "gid://shopify/SubscriptionContractCalculation/789"
) {
contract {
... on SubscriptionBillingCycleEditedContract {
lines(first: 10) {
nodes {
id
quantity
variantId
}
}
}
}
userErrors {
field
message
code
}
}
}

JSON response

{
"data": {
"subscriptionContractCalculationCommit": {
"contract": {
"lines": {
"nodes": [
{
"id": "gid://shopify/SubscriptionLine/existing-line-uuid",
"quantity": 2,
"variantId": "gid://shopify/ProductVariant/111"
},
{
"id": "gid://shopify/SubscriptionLine/new-line-uuid",
"quantity": 1,
"variantId": "gid://shopify/ProductVariant/222"
}
]
}
},
"userErrors": []
}
}
}

Handle commit user errors by code:

CodeMeaningAction
NOT_READY_TO_COMMITThe calculation hasn't succeeded yet.Continue polling before retrying the commit.
CALCULATION_NOT_FOUNDThe calculation ID doesn't exist or isn't available to the app.Verify the ID and app access.
STALE_CONTRACTThe contract changed after this calculation started.Query the latest contract state and calculate again.
INVALIDShopify can't commit the calculation.Use field and message to correct the request.

You can safely retry polling and commit requests. Retrying a calculate mutation creates a new calculation, so retain the ID for the result that you intend to commit. Retrying a commit for an already committed calculation returns the committed result.

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

After committing, you can fetch the edited contract on the billing cycle with the subscriptionBillingCycle query:

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL query

query {
subscriptionBillingCycle(
billingCycleInput: {
contractId: "gid://shopify/SubscriptionContract/123"
selector: { index: 5 }
}
) {
subscriptionBillingCycle {
cycleIndex
editedContract {
lines(first: 10) {
nodes {
id
quantity
variantId
}
}
}
}
userErrors {
field
message
}
}
}

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

When the billing date comes, use the subscriptionBillingCycleCharge mutation to create an order for the cycle. This mutation allows a single successful charge per billing cycle, and only charges cycles with a billing attempt expected date in the past or within the next 24 hours.

Billing attempts are processed asynchronously, so the resulting order isn't available right away. Fetch the billing attempt and inspect the ready field to find out whether the order has been created (true) or not (false).

POST https://{shop}.myshopify.com/admin/api/2026-10/graphql.json

GraphQL mutation

mutation {
subscriptionBillingCycleCharge(
subscriptionContractId: "gid://shopify/SubscriptionContract/123"
billingCycleSelector: { date: "2026-01-10T00:00:00Z" }
) {
subscriptionBillingAttempt {
id
errorMessage
order {
id
}
ready
}
}
}

Anchor to Billing cycle edit inputBilling cycle edit input

Use the following semantics when preparing billingCycleEditInput:

InputBehavior
withMerchandiseCustomizationsRequired. Set to true to run Shopify Functions that customize merchandise. Set to false to bypass them.
linesReplaces all lines for the cycle. Include an id to keep or update an existing line. Omit id to add a line. Omit the field to leave all lines unchanged. At least one line is required.
manualDiscountsReplaces all manual order and delivery discounts for the cycle. Pass [] to remove all manual discounts.
discountCodesApplies codes during this calculation. Shopify resolves them into manual discounts on the cycle instead of storing the codes.
deliveryMethodReplaces the delivery method for the cycle. Pass none to remove it, or fetchAvailableDeliveryOptions to discover options without changing the committed method.
noteReplaces the note. Pass null to clear it.
customAttributesReplaces all attributes for the cycle. Pass [] to remove them.

Anchor to Next stepsNext steps

Was this page helpful?