Manage billing cycles in bulk

When dealing with a large number of subscriptions contracts, performing operations in bulk can save significant time and effort. The subscriptionBillingCycleBulkCharge and subscriptionBillingCycleBulkSearch mutations are designed for such bulk operations. These mutations allow you to run multiple billing cycles by the billingAttemptExpectedDate and either charge them or retrieve their information. Additionally, you can use the subscriptionBillingCycleBulkResults query to retrieve the results of these bulk operations.

Anchor to RequirementsRequirements

• 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. Learn how to configure your access scopes using Shopify CLI.
• 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.
• You've familiarized yourself with the concept of billing cycles.

Anchor to Create an order in bulk for multiple contractsCreate an order in bulk for multiple contracts

The subscriptionBillingCycleBulkCharge mutation allows you to create charges for multiple billing cycles in bulk. This can be particularly useful when you need to process charges for a large number of subscriptions at once. 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.

Anchor to ExampleExample

The following example shows how to create a regular billing schedule for all unbilled cycles within a 24-hour period.

You can later use the subscriptionBillingCycleBulkResults to query all the billing cycles selected with this mutation, using the returned jobId.

Anchor to Search billing cycles using custom filtersSearch billing cycles using custom filters

The subscriptionBillingCycleBulkSearch mutation allows you to search for billing cycles in bulk based on specific criteria. It works similar to subscriptionBillingCycleBulkCharge, but doesn't charge or run any operations on the selected cycles.

Anchor to ExampleExample

In the following example, a list of all billing cycles that need to be billed next week is compiled.

To get the result of your search, you need to run the subscriptionBillingCycleBulkResults query using the returned job ID.

Anchor to Query the resultsQuery the results

After initiating a bulk operation using subscriptionBillingCycleBulkCharge or subscriptionBillingCycleBulkSearch, you can use the subscriptionBillingCycleBulkResults query to retrieve the results of the operation.

Anchor to ExampleExample

Anchor to Next stepsNext steps

Learn how to combine contracts together in a subscription billing cycle for a customer that has multiple subscriptions.