--- title: Manage billing cycles in bulk description: >- Learn how to manage billing cycles in bulk, including searching for and charging multiple contracts simultaneously. source_url: html: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/billing-cycles/bulk-billing-cycles md: >- https://shopify.dev/docs/apps/build/purchase-options/subscriptions/billing-cycles/bulk-billing-cycles.md api_name: admin --- # 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkCharge) and [`subscriptionBillingCycleBulkSearch`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) query to retrieve the results of these bulk operations. *** ## Requirements **Note:** * Most subscriptions, pre-order and try before you buy apps need to request API access through the [Partner Dashboard](https://partners.shopify.com/current/apps). We give API access to apps that are designed according to our [principles for subscriptions, pre-order and TBYB apps](https://shopify.dev/docs/apps/build/purchase-options#shopifys-principles). * Public apps that use subscriptions, pre-order or TBYB need to meet [specific requirements](https://shopify.dev/docs/apps/launch/shopify-app-store/app-store-requirements#purchase-option) to be published on the Shopify App Store. * Custom apps [created in the Shopify admin](https://shopify.dev/docs/apps/build/authentication-authorization/legacy/admin-custom-apps) 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 [create your custom app in the Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/create-apps-using-dev-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#authenticated-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/productVariantsBulkCreate) in your development store. * You've created an active [subscription contract](https://shopify.dev/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](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/billing-cycles). *** ## Create an order in bulk for multiple contracts The [`subscriptionBillingCycleBulkCharge`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 successful 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. ### Example 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`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) to [query all the billing cycles selected with this mutation](#query-the-results), using the returned `jobId`. ## POST https://{shop}.myshopify.com/admin/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { subscriptionBillingCycleBulkCharge( billingAttemptExpectedDateRange:{ startDate: "2024-06-01T00:00:00Z", endDate: "2024-06-02T00:00:00Z", } filters:{ contractStatus: [ACTIVE], billingCycleStatus: [UNBILLED], billingAttemptStatus: NO_ATTEMPT } ) { job { id } userErrors { message } } } ``` ## JSON response ```json { "data": { "subscriptionBillingCycleBulkCharge": { "job": { "id": "gid://shopify/Job/0f910294-5bfd-414a-a337-0c075b42793c" }, "userErrors": [] } } } ``` *** ## Search billing cycles using custom filters The [`subscriptionBillingCycleBulkSearch`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkSearch) mutation allows you to search for billing cycles in bulk based on specific criteria. It works similar to [`subscriptionBillingCycleBulkCharge`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkCharge), but doesn't charge or run any operations on the selected cycles. ### Example 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`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) query using the returned job ID. ## POST https://{shop}.myshopify.com/admin/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation { subscriptionBillingCycleBulkSearch( billingAttemptExpectedDateRange:{ startDate: "2024-06-07T00:00:00Z", endDate: "2024-06-14T00:00:00Z", } filters:{ contractStatus: [ACTIVE], } ) { job { id } userErrors { message field } } } ``` ## JSON response ```json { "data": { "subscriptionBillingCycleBulkSearch": { "job": { "id": "gid://shopify/Job/b156f92c-e665-483f-9401-143efbbd9d22" }, "userErrors": [] } } } ``` *** ## Query the results After initiating a bulk operation using [`subscriptionBillingCycleBulkCharge`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkCharge) or [`subscriptionBillingCycleBulkSearch`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkSearch), you can use the [`subscriptionBillingCycleBulkResults`](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) query to retrieve the results of the operation. ### Example ## POST https://{shop}.myshopify.com/admin/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { subscriptionBillingCycleBulkResults( jobId:"gid://shopify/Job/53eb95c8-5cd1-4a25-b6aa-8e0cdbfd3955", first: 10 ) { edges { node { status cycleStartAt cycleEndAt billingAttempts(first: 10) { edges { node { state { __typename ... on SubscriptionBillingAttemptSuccessState { order { id } } ... on SubscriptionBillingAttemptFailedState { error { __typename ... on SubscriptionBillingAttemptPaymentError { code } } } } } } } sourceContract { status lines(first:1) { edges { node { variantId variantTitle } } } } } } } } ``` ## JSON response ```json { "data": { "subscriptionBillingCycleBulkResults": { "edges": [ { "node": { "status": "BILLED", "cycleStartAt": "2024-05-12T16:00:01Z", "cycleEndAt": "2024-06-12T16:00:00Z", "billingAttempts": { "edges": [] }, "sourceContract": { "status": "ACTIVE", "lines": { "edges": [ { "node": { "variantId": null, "variantTitle": "Test Variant" } } ] } } } }, { "node": { "status": "UNBILLED", "cycleStartAt": "2024-05-09T16:00:01Z", "cycleEndAt": "2024-06-09T16:00:00Z", "billingAttempts": { "edges": [] }, "sourceContract": { "status": "ACTIVE", "lines": { "edges": [ { "node": { "variantId": null, "variantTitle": "Test Variant" } } ] } } } } ] } } } ``` *** ## Next steps Learn how to [combine contracts together](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/combine-subscription-contracts) in a subscription billing cycle for a customer that has multiple subscriptions. ***