--- title: Update a subscription contract description: Learn how to update an existing subscription contract with new information. source_url: html: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract md: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#requirements) * [Step 1: Query the available contracts on the store](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-1-query-the-available-contracts-on-the-store) * [Step 2: Create a draft of an existing contract](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-2-create-a-draft-of-an-existing-contract) * [Step 3: Update the subscription draft](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-3-update-the-subscription-draft) * [Step 4: Commit the subscription draft](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-4-commit-the-subscription-draft) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#next-steps) # Update a subscription contract Subscription contracts often require updates, such as when a customer needs to update their payment method or requests a change to their subscription. This guide shows you how to manage and update your existing subscription contracts by creating and applying a discount code to a contract. *** ## Requirements Note * Most subscriptions, pre-order and try before you buy apps need to request API access through the [Partner Dashboard](https://shopify.dev/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](https://shopify.dev/docs/apps/launch/app-requirements-checklist#purchase-option-apps) to be published on the Shopify App Store. * Custom apps [created in the Shopify admin](https://shopify.dev/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](https://shopify.dev/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](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration). - You've created [products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreate) and [product variants](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantcreate) in your development store. * You've created a [subscription contract](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract). *** ## Step 1: Query the available contracts on the store To view the available contracts on a store, you can query [`subscriptionContracts`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptioncontracts). In the following example, the response body returns the first ten available contracts, including the status of the contract and information about the customer, billing policy, and delivery policy. For a list of possible statuses, refer to [SubscriptionContractSubscriptionStatus](https://shopify.dev/api/admin-graphql/latest/enums/SubscriptionContractSubscriptionStatus). Note Importing past events on a subscription contract isn't supported. ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { subscriptionContracts(first: 10) { edges { node { id createdAt status nextBillingDate customer { firstName lastName } billingPolicy { interval intervalCount } deliveryPolicy { interval intervalCount } } } } } ``` ## JSON response ```json { "data": { "subscriptionContracts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionContract/1", "createdAt": "2022-10-01T19:01:46Z", "status": "ACTIVE", "nextBillingDate": "2020-10-15T00:00:00Z", "customer": { "firstName": "John", "lastName": "Smith" }, "billingPolicy": { "interval": "MONTH", "intervalCount": 3 }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 } } }, { "node": { "id": "gid://shopify/SubscriptionContract/2", "createdAt": "2022-10-01T19:04:15Z", "status": "ACTIVE", "nextBillingDate": "2022-10-15T00:00:00Z", "customer": { "firstName": "Jane", "lastName": "Smith" }, "billingPolicy": { "interval": "MONTH", "intervalCount": 3 }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 } } } ] } }, "extensions": { "cost": { "requestedQueryCost": 32, "actualQueryCost": 8 } } } ``` *** ## Step 2: Create a draft of an existing contract Tip This guide shows you how to update a subscription contract incrementally. However, if you only want to swap out a specific product variant on a subscription contract, then you can use the [`subscriptionContractProductUpdate`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/subscriptioncontractproductchange) mutation. When a customer updates their payment method or makes a change to their subscription, you need to update the appropriate subscription contract. To update a subscription contract, use the [`subscriptionContractUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptioncontractupdate) mutation and supply the subscription contract ID. The call returns a draft with the existing state of the contract. ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql mutation { subscriptionContractUpdate( contractId: "gid://shopify/SubscriptionContract/2" ) { draft { id } userErrors { field message } } } ``` ## JSON response ```json { "data": { "subscriptionContractUpdate": { "draft": { "id": "gid://shopify/SubscriptionDraft/3" }, "userErrors": [] } }, "extensions": { "cost": { "requestedQueryCost": 10, "actualQueryCost": 10, "throttleStatus": { "maximumAvailable": 1000.0, "currentlyAvailable": 990, "restoreRate": 50.0 } } } } ``` *** ## Step 3: Update the subscription draft Tip This step shows you how to create and apply a discount code to a subscription draft. However, you can make other updates to the subscription draft in this step as needed, such as [adding a line item](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionDraftLineAdd) or [updating the delivery policy](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptiondraftupdate). 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-4-commit-the-subscription-draft). ### Create a subscription discount code Use the [`discountCodeBasicCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/discountcodebasiccreate) mutation to create a basic discount code. To specify that the discount can be applied on subscriptions, set the `appliesOnSubscription` field to `true`: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { discountCodeBasicCreate( basicCodeDiscount: { title: "WELCOME_10%" code: "WELCOME_10%" customerGets: { value: { percentage: 0.1 } items: { all: true } appliesOnSubscription: true appliesOnOneTimePurchase: false } customerSelection: { all: true } startsAt: "20200202T020202" } ) { codeDiscountNode { id codeDiscount { __typename ... on DiscountCodeBasic { title } } } userErrors { code field message } } } ``` ## JSON response ```json { "data": { "discountCodeBasicCreate": { "codeDiscountNode": { "id": "gid://shopify/DiscountCodeNode/1", "codeDiscount": { "__typename": "DiscountCodeBasic", "title": "WELCOME_10%" } }, "userErrors": [] } }, "extensions": { "cost": { "requestedQueryCost": 11, "actualQueryCost": 11, "throttleStatus": { "maximumAvailable": 1000.0, "currentlyAvailable": 989, "restoreRate": 50.0 } } } } ``` ### Apply the discount code Use the [`subscriptionDraftDiscountCodeApply`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptiondraftdiscountcodeapply) mutation to apply the discount code to the subscription draft: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { subscriptionDraftDiscountCodeApply( draftId: "gid://shopify/SubscriptionDraft/3" redeemCode: "WELCOME_10%" ) { appliedDiscount { id redeemCode rejectionReason } draft { id } userErrors { field message code } } } ``` ## JSON response ```json { "data": { "subscriptionDraftDiscountCodeApply": { "discountApplied": { "id": "gid://shopify/SubscriptionAppliedCodeDiscount/17598524-27c1-4cd5-8914-9beca81ea4b6", "redeemCode": "WELCOME_10%", "rejectionReason": null, }, "draft": { "id": "gid://shopify/SubscriptionDraft/3" }, "userErrors": [] } } } ``` *** ## Step 4: Commit the subscription draft When you commit the subscription draft, the changes that you've made become active on the subscription contract for which the draft was created. You can call the [`subscriptionDraft`](https://shopify.dev/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 [`subscriptionDraftCommit`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptiondraftcommit) mutation to commit your changes to the contract: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { subscriptionDraftCommit(draftId: "gid://shopify/SubscriptionDraft/3") { contract { id } userErrors { field message } } } ``` ## JSON response ```json { "data": { "subscriptionDraftCommit": { "contract": { "id": "gid://shopify/SubscriptionContract/2" }, "userErrors": [] } }, "extensions": { "cost": { "requestedQueryCost": 10, "actualQueryCost": 10, "throttleStatus": { "maximumAvailable": 1000.0, "currentlyAvailable": 990, "restoreRate": 50.0 } } } } ``` *** ## Next steps * Learn how to [manage and edit billing cycles](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/billing-cycles), including updating the schedule and contract information for a billing cycle, skipping a billing cycle or changing the contract information for one period. *** * [Requirements](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#requirements) * [Step 1: Query the available contracts on the store](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-1-query-the-available-contracts-on-the-store) * [Step 2: Create a draft of an existing contract](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-2-create-a-draft-of-an-existing-contract) * [Step 3: Update the subscription draft](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-3-update-the-subscription-draft) * [Step 4: Commit the subscription draft](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#step-4-commit-the-subscription-draft) * [Next steps](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract.md#next-steps)