When dealing with a large number of subscriptions contracts, performing operations in bulk can save significant time and effort. The [`subscriptionBillingCycleBulkCharge`](/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkCharge) and [`subscriptionBillingCycleBulkSearch`](/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`](/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](/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](/docs/apps/launch/app-requirements-checklist#purchase-option-apps) to be published on the Shopify App Store. > - Custom apps [created in the Shopify admin](/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](/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](/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](/docs/apps/build/cli-for-apps/app-configuration). - You've created [products](/docs/api/admin-graphql/latest/mutations/productcreate) and [product variants](/docs/api/admin-graphql/latest/mutations/productvariantcreate) in your development store. - You've created an active [subscription contract](/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](/docs/apps/build/purchase-options/subscriptions/billing-cycles). ## Create an order in bulk for multiple contracts The [`subscriptionBillingCycleBulkCharge`](/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 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. ### 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`](/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) to [query all the billing cycles selected with this mutation](#query-the-results), using the returned `jobId`. ```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 { "subscriptionBillingCycleBulkCharge": { "job": { "id": "gid://shopify/Job/0f910294-5bfd-414a-a337-0c075b42793c" }, "userErrors": [] } } ``` ## Search billing cycles using custom filters The [`subscriptionBillingCycleBulkSearch`](/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`](/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`](/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) query using the returned job ID. ```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 { "subscriptionBillingCycleBulkSearch": { "job": { "id": "gid://shopify/Job/b156f92c-e665-483f-9401-143efbbd9d22" }, "userErrors": [] } } ``` ## Query the results After initiating a bulk operation using [`subscriptionBillingCycleBulkCharge`](/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkCharge) or [`subscriptionBillingCycleBulkSearch`](/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleBulkSearch), you can use the [`subscriptionBillingCycleBulkResults`](/docs/api/admin-graphql/latest/queries/subscriptionBillingCycleBulkResults) query to retrieve the results of the operation. ### Example ```graphql query { subscriptionBillingCycleBulkResults( jobId:"gid://shopify/Job/53eb95c8-5cd1-4a25-b6aa-8e0cdbfd3955", first: 10 ) { edges { node { status cycleStartAt cycleEndAt billingAttempts(first: 10) { edges { node { order { id } errorMessage } } } sourceContract { status lines(first:1) { edges { node { variantId variantTitle } } } } } } } } ``` ```json { "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](/docs/apps/build/purchase-options/subscriptions/contracts/combine-subscription-contracts) in a subscription billing cycle for a customer that has multiple subscriptions.