Choose a version:

Anchor to subscriptionBillingCycleBulkCharge

subscriptionBillingCycleBulkCharge

mutation

Requires write_own_subscription_contracts access scope. Also: The user must have manage_orders_information permission.

Asynchronously queries and charges all subscription billing cycles whose billingAttemptExpectedDate values fall within a specified date range and meet additional filtering criteria. The results of this action can be retrieved using the subscriptionBillingCycleBulkResults query.

Anchor to Arguments

Arguments

Anchor to actoractor

•SubscriptionActor

The actor who initiated a subscription action.

Show enum values

Anchor to billingAttemptExpectedDateRangebillingAttemptExpectedDateRange

•SubscriptionBillingCyclesDateRangeSelector!

required

Specifies the date range within which the billingAttemptExpectedDate values of the billing cycles should fall.

Show input fields

Anchor to filtersfilters

•SubscriptionBillingCycleBulkFilters

Criteria to filter the billing cycles on which the action is executed.

Show input fields

Anchor to inventoryPolicyinventoryPolicy

•SubscriptionBillingAttemptInventoryPolicy

Default:PRODUCT_VARIANT_INVENTORY_POLICY

The behaviour to use when updating inventory.

Show enum values

Anchor to paymentProcessingPolicypaymentProcessingPolicy

•SubscriptionBillingAttemptPaymentProcessingPolicy

Default:FAIL_UNLESS_VALID_PAYMENT_METHOD

Selected payment processing policy for the billing attempt. Defaults to FAIL_UNLESS_VALID_PAYMENT_METHOD.

Show enum values

Was this section helpful?

Anchor to SubscriptionBillingCycleBulkChargePayload returnsSubscriptionBillingCycleBulkChargePayload returns

Anchor to jobjob •Job: The asynchronous job that performs the action on the targeted billing cycles.

Show fields
Anchor to userErrorsuserErrors •[SubscriptionBillingCycleBulkUserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Create a job to charge all subscription billing cycles in time range

Description

Creates a job to charge all subscription billing cycles between 2023-02-01 and 2023-02-02.

Query

mutation($startDate: DateTime!, $endDate: DateTime!) {
  subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
    job {
      id
    }
  }
}

Variables

{
  "startDate": "2023-02-01T00:00:00-05:00",
  "endDate": "2023-02-02T23:59:59-05:00"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation($startDate: DateTime!, $endDate: DateTime!) { subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) { job { id } } }",
 "variables": {
    "startDate": "2023-02-01T00:00:00-05:00",
    "endDate": "2023-02-02T23:59:59-05:00"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation($startDate: DateTime!, $endDate: DateTime!) {
    subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
      job {
        id
      }
    }
  }`,
  {
    variables: {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation($startDate: DateTime!, $endDate: DateTime!) {
    subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
      job {
        id
      }
    }
  }
QUERY

variables = {
  "startDate": "2023-02-01T00:00:00-05:00",
  "endDate": "2023-02-02T23:59:59-05:00"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation($startDate: DateTime!, $endDate: DateTime!) {
      subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
        job {
          id
        }
      }
    }`,
    "variables": {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation($startDate: DateTime!, $endDate: DateTime!) {
  subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
    job {
      id
    }
  }
}' \
--variables \
'{
  "startDate": "2023-02-01T00:00:00-05:00",
  "endDate": "2023-02-02T23:59:59-05:00"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation($startDate: DateTime!, $endDate: DateTime!) {
        subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
          job {
            id
          }
        }
      }
    `,
    variables: {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "subscriptionBillingCycleBulkCharge": {
    "job": {
      "id": "gid://shopify/Job/99ff28fc-980d-48ef-a190-1a1973fb5ed3"
    }
  }
}

subscriptionBillingCycleBulkCharge reference

Examples

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation($startDate: DateTime!, $endDate: DateTime!) {

subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {

job {

}

}`,

{

variables: {

"startDate": "2023-02-01T00:00:00-05:00",

"endDate": "2023-02-02T23:59:59-05:00"

);

const json = await response.json();

return json.data;

}

GQL

mutation($startDate: DateTime!, $endDate: DateTime!) {
  subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
    job {
      id
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation($startDate: DateTime!, $endDate: DateTime!) { subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) { job { id } } }",
 "variables": {
    "startDate": "2023-02-01T00:00:00-05:00",
    "endDate": "2023-02-02T23:59:59-05:00"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation($startDate: DateTime!, $endDate: DateTime!) {
    subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
      job {
        id
      }
    }
  }`,
  {
    variables: {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation($startDate: DateTime!, $endDate: DateTime!) {
      subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
        job {
          id
        }
      }
    }`,
    "variables": {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation($startDate: DateTime!, $endDate: DateTime!) {
    subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
      job {
        id
      }
    }
  }
QUERY

variables = {
  "startDate": "2023-02-01T00:00:00-05:00",
  "endDate": "2023-02-02T23:59:59-05:00"
}

response = client.query(query: query, variables: variables)

Shopify CLI

shopify app execute \
--query \
'mutation($startDate: DateTime!, $endDate: DateTime!) {
  subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
    job {
      id
    }
  }
}' \
--variables \
'{
  "startDate": "2023-02-01T00:00:00-05:00",
  "endDate": "2023-02-02T23:59:59-05:00"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-07/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation($startDate: DateTime!, $endDate: DateTime!) {
        subscriptionBillingCycleBulkCharge(billingAttemptExpectedDateRange: {startDate: $startDate, endDate: $endDate}) {
          job {
            id
          }
        }
      }
    `,
    variables: {
        "startDate": "2023-02-01T00:00:00-05:00",
        "endDate": "2023-02-02T23:59:59-05:00"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"startDate": "2023-02-01T00:00:00-05:00",

"endDate": "2023-02-02T23:59:59-05:00"

}

Response

JSON

{

"subscriptionBillingCycleBulkCharge": {

"job": {

"id": "gid://shopify/Job/99ff28fc-980d-48ef-a190-1a1973fb5ed3"

}