Choose a version:

Anchor to subscriptionBillingAttemptCreate

subscriptionBillingAttemptCreate

mutation

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

Creates a billing attempt to charge for a SubscriptionContract. The mutation processes either the payment for the current billing cycle or for a specific cycle, if selected.

The mutation creates an Order when successful. Failed billing attempts include a processingError field with error details.

Tip

Use the idempotencyKey to ensure the billing attempt executes only once, preventing duplicate charges if the request is retried.

You can target a specific billing cycle using the billingCycleSelector to bill past or future cycles. The originTime parameter adjusts fulfillment scheduling for attempts completed after the expected billing date.

Learn more about creating billing attempts.

Anchor to Arguments

Arguments

Anchor to subscriptionBillingAttemptInputsubscriptionBillingAttemptInput

•SubscriptionBillingAttemptInput!

required

The information to apply as a billing attempt.

Anchor to subscriptionContractIdsubscriptionContractId

•ID!

required

The ID of the subscription contract.

Was this section helpful?

Anchor to SubscriptionBillingAttemptCreatePayload returnsSubscriptionBillingAttemptCreatePayload 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?

Examples

Create a billing attempt on a specific billing cycle

Description

Creates a billing attempt on the billing cycle with cycle index `1`.

Query

mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
  subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
    subscriptionBillingAttempt {
      id
      ready
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "index": 1
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) { subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: \"aaa-bbb-ccc\", originTime: \"2020-10-01T10:00:00Z\"}) { subscriptionBillingAttempt { id ready } userErrors { field message } } }",
 "variables": {
    "contractId": "gid://shopify/SubscriptionContract/593791907",
    "index": 1
  }
}'

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 subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
    subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "contractId": "gid://shopify/SubscriptionContract/593791907",
        "index": 1
    },
  },
  );
  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 subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
    subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "index": 1
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
      subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
        subscriptionBillingAttempt {
          id
          ready
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "contractId": "gid://shopify/SubscriptionContract/593791907",
        "index": 1
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
  subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
    subscriptionBillingAttempt {
      id
      ready
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "index": 1
}'

Response

{
  "subscriptionBillingAttemptCreate": {
    "subscriptionBillingAttempt": {
      "id": "gid://shopify/SubscriptionBillingAttempt/528177097",
      "ready": false
    },
    "userErrors": []
  }
}

subscriptionBillingAttemptCreate reference

Examples

Open in GraphiQL

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

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

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

const response = await admin.graphql(

`#graphql

mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {

subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {

subscriptionBillingAttempt {

ready

}

userErrors {

field

message

}

}`,

{

variables: {

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

"index": 1

);

const json = await response.json();

return json.data;

}

GQL

mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
  subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
    subscriptionBillingAttempt {
      id
      ready
    }
    userErrors {
      field
      message
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) { subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: \"aaa-bbb-ccc\", originTime: \"2020-10-01T10:00:00Z\"}) { subscriptionBillingAttempt { id ready } userErrors { field message } } }",
 "variables": {
    "contractId": "gid://shopify/SubscriptionContract/593791907",
    "index": 1
  }
}'

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 subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
    subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "contractId": "gid://shopify/SubscriptionContract/593791907",
        "index": 1
    },
  },
  );
  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 subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
      subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
        subscriptionBillingAttempt {
          id
          ready
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "contractId": "gid://shopify/SubscriptionContract/593791907",
        "index": 1
    },
  },
});

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 subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
    subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
      subscriptionBillingAttempt {
        id
        ready
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "index": 1
}

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

Shopify CLI

shopify app execute \
--query \
'mutation subscriptionBillingAttemptCreate($contractId: ID!, $index: Int!) {
  subscriptionBillingAttemptCreate(subscriptionContractId: $contractId, subscriptionBillingAttemptInput: {billingCycleSelector: {index: $index}, idempotencyKey: "aaa-bbb-ccc", originTime: "2020-10-01T10:00:00Z"}) {
    subscriptionBillingAttempt {
      id
      ready
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "contractId": "gid://shopify/SubscriptionContract/593791907",
  "index": 1
}'

Input variables

JSON

{

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

"index": 1

}

Response

JSON

{

"subscriptionBillingAttemptCreate": {

"subscriptionBillingAttempt": {

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

"ready": false

"userErrors": []

}