Billing cycle contracts inherit the contract lines, pricing policy, and delivery policy from the billing cycle's source subscription contract. However, you might want to edit the contract information on a billing cycle when you need to make a temporary change to a customer's subscription contract. For example, you might remove a product that's out of stock and replace it with a similar product for a single billing cycle. This tutorial shows you how to edit the contract information on a billing cycle. ## What you'll learn In this tutorial, you'll learn how to do the following tasks: - Retrieve a draft of the most up-to-date contract information for a subscription billing cycle - Remove a line item from the contract draft - Add a line item to the contract draft - Commit the edited contract information - Fetch the edited contract information on a subscription billing cycle - Create an order for a subscription billing cycle ## Requirements > Note: > > - Most subscriptions, pre-order and try before you buy apps need to request API access through the [Partner Dashboard](/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant#ask-for-permission). We give API access to apps that are designed according to our [principles for subscriptions, pre-order and TBYB apps] (/docs/apps/selling-strategies/purchase-options#shopifys-principles). > - Public apps that use subscriptions, pre-order or TBYB need to meet [specific requirements](/docs/apps/launch/app-requirements-checklist#purchase-option-apps) to be published on the Shopify App Store. > - Custom apps [created in the Shopify admin](/docs/apps/build/authentication-authorization/access-tokens/generate-app-access-tokens-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. - Your app can make [authenticated requests](/docs/api/admin-graphql#authentication) to the GraphQL Admin API. - Your app has the `read_own_subscription_contracts` and `write_own_subscription_contracts` [access scopes](/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](/docs/apps/build/cli-for-apps/app-configuration). - You've created [products](/docs/api/admin-graphql/latest/mutations/productcreate) and [product variants](/docs/api/admin-graphql/latest/mutations/productvariantcreate) in your development store. - You've created an active [subscription contract](/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract) with a recurring billing and delivery policy. - You've familiarized yourself with the concept of [billing cycles](/docs/apps/build/purchase-options/subscriptions/billing-cycles). ## Step 1: Create a subscription draft You can use the [`subscriptionBillingCycleContractEdit`](/docs/api/admin-graphql/latest/mutations/subscriptionbillingcyclecontractedit) mutation to create a subscription draft with the most up-to-date contract information on a specified billing cycle. Pass the contract ID and either the index or a date belonging to the billing cycle to specify the billing cycle. Make note of the subscription contract draft ID and line ID in the response. You'll use it to update the draft data in [the next step](#step-2-update-the-subscription-draft). ```graphql mutation { subscriptionBillingCycleContractEdit( billingCycleInput: { contractId: "gid://shopify/SubscriptionContract/123", selector: { date: "2023-01-10T00:00:00Z" } } ) { draft { # Subscription draft fields id lines(first:10) { edges { node { id } } } billingCycle { cycleIndex } } userErrors { field message } } } ``` ```json { "data": { "draft": { "id": "gid://shopify/SubscriptionDraft/321", "lines": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionLine/1" } } ] }, "billingCycle": { "cycleIndex": 5 } }, "userErrors": [] } } ``` ## Step 2: Update the subscription draft > Tip: > This step shows you how to remove or add a line item to the contract. However, you can make other updates to the subscription draft in this step as needed, such as [adding a discount](/docs/api/admin-graphql/latest/mutations/subscriptionDraftDiscountAdd) or [changing the line quantity](/docs/api/admin-graphql/latest/mutations/subscriptionDraftLineUpdate). After retrieving the draft ID, you can begin making edits to the contract draft. Edits to the contract draft can be made incrementally. Changes to the contract draft aren't made live until [the draft is committed](#step-3-commit-the-subscription-draft). ### Remove a line item You can pass the draft ID and line ID to the [`subscriptionDraftLineRemove`](/docs/api/admin-graphql/latest/mutations/subscriptionDraftLineRemove) mutation to remove a line item from the subscription draft: ```graphql mutation { subscriptionDraftLineRemove( draftId: "gid://shopify/SubscriptionDraft/321" lineId: "gid://shopify/SubscriptionLine/1" ) { draft { # Subscription draft fields id } lineRemoved { # Subscription line fields id } userErrors { field message } } } ``` ```json { "data": { "draft": { "id": "gid://shopify/SubscriptionDraft/321" }, "lineRemoved": { "id": "gid://shopify/SubscriptionLine/1" }, "userErrors": [] } } ``` ### Add a line item You can pass the draft ID and line information to the [`subscriptionDraftLineAdd`](/docs/api/admin-graphql/latest/mutations/subscriptionDraftLineAdd) mutation to add a line item to the subscription draft: ```graphql mutation { subscriptionDraftLineAdd( draftId: "gid://shopify/SubscriptionDraft/321" input: { currentPrice: 12.50 productVariantId: "gid://shopify/ProductVariant/11111" quantity: 1 } ) { draft { # Subscription draft fields id } lineAdded { # Subscription line fields id } userErrors { field message } } } ``` ```json { "data": { "draft": { "id": "gid://shopify/SubscriptionDraft/321" }, "lineAdded": { "id": "gid://shopify/SubscriptionLine/2" }, "userErrors": [] } } ``` ## Step 3: Commit the subscription draft When you commit the subscription draft, the changes that you've made become active on the billing cycle for which the draft was created. You can call the [`subscriptionDraft`](/docs/api/admin-graphql/latest/queries/subscriptionDraft) query to review the information on the subscription draft before committing it. After you're satisfied with your updates, you can call the [`subscriptionBillingCycleContractDraftCommit`](/docs/api/admin-graphql/latest/mutations/subscriptionbillingcyclecontractdraftcommit) mutation to commit your changes to the billing cycle: ```graphql mutation { subscriptionBillingCycleContractDraftCommit( draftId: "gid://shopify/SubscriptionDraft/321" ) { contract { # Subscription billing cycle edited contract fields billingCycles (first:10) { edges { node { cycleIndex } } } } userErrors { field message } } } ``` ```json { "data": { "contract": { "edges": [ { "node": { "cycleIndex": 5 } } ] }, "userErrors": [] } } ``` ## Step 4: Fetch the edited contract After committing the subscription draft, you might want to fetch the information on your edited contract. You can do so using [`subscriptionBillingCycle`](/docs/api/admin-graphql/latest/queries/subscriptionBillingCycle) query. ```graphql subscriptionBillingCycle( billingCycleInput: { contractId: "gid://shopify/SubscriptionContract/123", selector: { index: 5 } } ) { subscriptionBillingCycle { cycleIndex editedContract { # Subscription billing cycle edited contract fields lines(first: 10) { id quantity variantId } } } userErrors { field message } } ``` ```json { "data": { "subscriptionBillingCycle": { "editedContract": { "cycleIndex": 5, "lines": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionLine/2", "variantId": "gid://shopify/ProductVariant/11111", "quantity": 1, } } ] } } }, "userErrors": [] } } ``` ## Step 5: Create an order When the billing date comes, you can use [`subscriptionBillingCycleCharge`](/docs/api/admin-graphql/latest/mutations/subscriptionbillingcyclecharge) mutation to create an order. This mutation only allows a single successfull charge per billing cycle and only allows charging billing cycles with the billing attempt expected date in the past or within the next 24 hours. To use the `subscriptionBillingCycleCharge` mutation, you need to specify the following inputs: - `subscriptionContractId`: The ID of the subscription contract. - `billingCycleSelector`: The billing cycle you want to charge. You can select the billing cycle by passing a date or a [billing cycle index](/docs/apps/build/purchase-options/subscriptions/billing-cycles#billing-schedule). Billing attempts are processed asynchronously, which means the resulting order won't be available right away. You can fetch the billing attempt and inspect the `ready` field to find out whether the order has been created (`true`) or not (`false`). > Note: > You can also [create orders by creating a billing attempt](/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt). ```graphql mutation { subscriptionBillingCycleCharge( subscriptionContractId: "gid://shopify/SubscriptionContract/123", billingCycleSelector: { date: "2024-01-10T00:00:00Z" } ) { subscriptionBillingAttempt { id errorMessage order { id } ready } } } ``` ```json { "data": { "subscriptionBillingCycleCharge": { "subscriptionBillingAttempt": { "id": "gid://shopify/SubscriptionBillingAttempt/1", "errorMessage": null, "order": { "id": "gid://shopify/Order/1" }, "ready": true } }, "userErrors": [] } } ``` ## Next steps Learn how to [bulk charge multiple contracts at the same time](/docs/apps/build/purchase-options/subscriptions/billing-cycles/bulk-billing-cycles).