Manage billing cycle contracts
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 learnAnchor link to section titled "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
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_own_subscription_contractsaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
You've created an active subscription contract with a recurring billing and delivery policy.
You've familiarized yourself with the concept of billing cycles.
Step 1: Create a subscription draftAnchor link to section titled "Step 1: Create a subscription draft"
You can use the
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 draftAnchor link to section titled "Step 2: Update the subscription draft"
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.
Remove a line itemAnchor link to section titled "Remove a line item"
You can pass the draft ID and line ID to the
subscriptionDraftLineRemove mutation to remove a line item from the subscription draft:
Add a line itemAnchor link to section titled "Add a line item"
You can pass the draft ID and line information to the
subscriptionDraftLineAdd mutation to add a line item to the subscription draft:
Step 3: Commit the subscription draftAnchor link to section titled "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 query to review the information on the subscription draft before committing it.
After you're satisfied with your updates, you can call the
subscriptionBillingCycleContractDraftCommit mutation to commit your changes to the billing cycle:
Step 4: Fetch the edited contractAnchor link to section titled "Step 4: Fetch the edited contract"
After commiting the subscription draft, you might want to fetch the information on your edited contract.
You can do so using
Step 5: Create an orderAnchor link to section titled "Step 5: Create an order"
When the billing date comes, you can use
subscriptionBillingAttemptCreate mutation to create an order.
billingCycleSelector was specified, Shopify will create an order based on the current billing cycle's contract information by default.
If you want to create an order for a certain billing cycle, you must specify
Learn how to combine contracts together in a subscription billing cycle for a customer that has multiple subscriptions to save on shipping and administrative costs.