Choose a version:

subscriptionBillingCycleCharge

mutation

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

Creates a new subscription billing attempt for a specified billing cycle. This is the alternative mutation for subscriptionBillingAttemptCreate. For more information, refer to Create a subscription contract.

Arguments

Anchor to billingCycleSelectorbillingCycleSelector •SubscriptionBillingCycleSelector!required: Select the specific billing cycle to be billed. If the selected billing cycle's billingAttemptExpectedDate is in the past, the originTime of the billing attempt will be set to this date. However, if the billingAttemptExpectedDate is in the future, the originTime will be the current time.
Anchor to inventoryPolicyinventoryPolicy •SubscriptionBillingAttemptInventoryPolicyDefault:PRODUCT_VARIANT_INVENTORY_POLICY: The behaviour to use when updating inventory.
Anchor to subscriptionContractIdsubscriptionContractId •ID!required: The ID of the subscription contract.

Was this section helpful?

Anchor to SubscriptionBillingCycleChargePayload returnsSubscriptionBillingCycleChargePayload returns

Anchor to subscriptionBillingAttemptsubscriptionBillingAttempt •SubscriptionBillingAttempt: The subscription billing attempt.
Anchor to userErrorsuserErrors •[BillingAttemptUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Create a billing attempt on a specific billing cycle
subscriptionBillingCycleCharge reference

Examples

Open in GraphiQL

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

const response = await admin.graphql(

`#graphql

mutation subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) {

subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) {

subscriptionBillingAttempt {

ready

}

userErrors {

field

message

}

}`,

{

variables: {

"contractId": "gid://shopify/SubscriptionContract/593791907",

"billingCycleSelector": {

"date": "2023-01-05T12:00:00Z"

}

);

const data = await response.json();

mutation subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) {
  subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) {
    subscriptionBillingAttempt {
      id
      ready
    }
    userErrors {
      field
      message
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) { subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) { subscriptionBillingAttempt { id ready } userErrors { field message } } }",
 "variables": {
    "contractId": "gid://shopify/SubscriptionContract/593791907",
    "billingCycleSelector": {
      "date": "2023-01-05T12:00:00Z"
    }
  }
}'

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

const response = await admin.graphql(
  `#graphql
  mutation subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) {
    subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
      "contractId": "gid://shopify/SubscriptionContract/593791907",
      "billingCycleSelector": {
        "date": "2023-01-05T12:00:00Z"
      }
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) {
      subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) {
        subscriptionBillingAttempt {
          id
          ready
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
      "contractId": "gid://shopify/SubscriptionContract/593791907",
      "billingCycleSelector": {
        "date": "2023-01-05T12:00:00Z"
      }
    },
  },
});

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 subscriptionBillingCycleCharge($contractId: ID!, $billingCycleSelector: SubscriptionBillingCycleSelector!) {
    subscriptionBillingCycleCharge(subscriptionContractId: $contractId, billingCycleSelector: $billingCycleSelector) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "billingCycleSelector": {
    "date": "2023-01-05T12:00:00Z"
  }
}

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

Input variables

JSON

{

"contractId": "gid://shopify/SubscriptionContract/593791907",

"billingCycleSelector": {

"date": "2023-01-05T12:00:00Z"

}

Response

JSON

{

"subscriptionBillingCycleCharge": {

"subscriptionBillingAttempt": {

"id": "gid://shopify/SubscriptionBillingAttempt/528177098",

"ready": false

"userErrors": []

}