Billing cycles

A subscription billing cycle is a scheduled interval in which a subscription contract attempts to bill a customer for a set of items.

Billing cycles are useful for when you want to make temporary changes to a subscription contract over a specific period without overwriting any of the source subscription data. Here are some example scenarios where billing cycles can be used to modify subscriptions:

The customer has an existing subscription, but they want to skip one delivery without cancelling the subscription
The merchant is temporarily out of stock for a subscription product, and wants to ship a replacement product instead
The merchant wants to create cross-sell or upsell offers for existing subscription customers, such as a discount for adding a product to one order
The customer has multiple subscriptions, and the merchant wants to combine their contract information into one order to save on shipping and billing costs

This guide describes what billing cycles are, the workflow for editing a billing cycle, and some considerations before you get started.

Requirements

Anchor link to section titled "Requirements"

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. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
You've created products and product variants in your development store.
You've created an active subscription contract with a recurring billing and delivery policy.

How it works

Anchor link to section titled "How it works"

A billing cycle represents one period of billing and delivery information for a subscription contract. The source subscription contract is the contract to which a billing cycle belongs. Billing cycles inherit their default schedule and contract information from the source subscription contract.

By editing the schedule and contract information on a billing cycle, you can make changes to billing and contract information for an upcoming order without modifying the source subscription contract.

Billing schedule

Anchor link to section titled "Billing schedule"

Each billing cycle is indexed from when the first version of the contract is initialized. This means that the first billing cycle for a new subscription contract has an index of 1, the next billing cycle has an index of 2, and so on. The index doesn't reset when a contract is edited, so the index can be used to uniquely identify a billing cycle on a particular contract.

Each billing cycle has a start date and end date, and the next billing cycle starts on the day following the previous cycle's end date. Each billing cycle also has a billingAttemptExpectedDate, which represents the single date in the cycle on which the app is expected to bill the customer for their contract.

The following diagram shows an example billing schedule for a monthly subscription contract that is created on January 1, and is scheduled to bill and deliver on the fifteenth day of every month. Some schedule and contract changes are made to cycle 2, cycle 3, and cycle 4, but the source subscription contract hasn't changed and continues from cycle 5 onwards.

Contracts

Anchor link to section titled "Contracts"

A billing cycle belongs to a source subscription contract and inherits the contract information from that source contract by default. You can edit the contract information on a specific billing cycle multiple times, but only the most recent change is kept.

Editing a billing cycle

Anchor link to section titled "Editing a billing cycle"

The following diagram shows an example workflow for editing a billing cycle.

A customer requests a temporary change to their subscription on a specific billing cycle.

If it's a billing schedule change, the subscription app updates the customer's billing schedule.
If it's a contract content change, the subscription app edits the contract information for the billing cycle:

a. The subscription app starts by retrieving a draft from the most up-to-date contract information.

b. Shopify returns a draft of the most up-to-date contract information.

c. The subscription app updates the draft with new contract information, and then commits the draft.

The subscription app schedules a billing attempt. This step might be skipped if the customer requested to skip the billing and delivery for a cycle. Shopify receives the billing attempt creation request and then creates the transaction and order according to the updated schedule and contract information.

Learn more about editing the contract information on a billing cycle.

Billing cycle object relationships

Anchor link to section titled "Billing cycle object relationships"

The following diagram shows the relationship between billing cycles, contracts, and policies.

API object	Description
Subscription contract	Represents the agreement for a set of items delivered to a customer, on a specific billing and delivery schedule and at a specific price. A subscription contract is different from an order. An order is a customer's completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process, during which time they provide an email address or phone number, billing address, and payment information.
Contract lines	Represents the price and quantity of items in a subscription contract.
Pricing policy	Represents the future intent to change the price after a given number of billing cycles. When the customer completes a checkout, Shopify creates a contract, and the app developer is notified of which policies the customer chose.
Billing policy	Represents when and how often the subscription contract should bill the customer according to the terms of the agreement.
Delivery policy	Represents when and how often the subscription contract should create orders to be delivered or fulfilled to the customer according to the terms of the agreement.
Billing cycles	Represents one period of billing and delivery information for a subscription contract.
Billing cycle schedule	Represents the schedule information for a billing cycle, including the cycle's start date, end date, index, and expected date for attempting billing. The billing cycle schedule inherits the billing policy information from the source subscription contract by default. However, you can edit the expected date for attempting billing for a single cycle, or skip a cycle without affecting the source subscription contract.
Billing cycle contract	Represents the contract information for a billing cycle, including the source contract and edited contract (if applicable). The billing cycle contract inherits the contract lines, delivery policy, and pricing policy information from the source subscription contract by default. Learn more about managing billing cycle contracts.

Limitations

Anchor link to section titled "Limitations"

You can't edit billing cycles for prepaid subscriptions.
You can't edit billing and delivery policies for billing cycle contracts. Update the billing and delivery policies on the source subscription contract instead.
If the contract has a current or future billing cycle with committed edits, then you can't update the source subscription contract until you delete all of the edits.
Contracts that existed before 2022-10-01 will have billing cycles starting only from 2022-10-01 onwards. You can't query any billing cycles before 2022-10-01.
You can make edits only to the current billing cycle and any billing cycle that's up to ten billing cycles after the current billing cycle.

Next steps

Anchor link to section titled "Next steps"

Learn how to manage billing cycle contracts.