Choose a version:

subscriptionBillingAttempt

query

Returns a SubscriptionBillingAttempt resource by ID.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the SubscriptionBillingAttempt to return.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to SubscriptionBillingAttemptSubscriptionBillingAttempt

•SubscriptionBillingAttempt

A record of an execution of the subscription billing process. Billing attempts use idempotency keys to avoid duplicate order creation.

When a billing attempt completes successfully, it creates an Order. The attempt includes associated payment transactions and any errors that occur during billing. If 3D Secure authentication is required, the nextActionUrl field provides the redirect URL for customer verification.

Anchor to completedAtcompletedAt

•DateTime

The date and time when the billing attempt was completed.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time when the billing attempt was created.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to idempotencyKeyidempotencyKey

•String!

non-null

A unique key generated by the client to avoid duplicate payments.

Anchor to nextActionUrlnextActionUrl

•URL

The URL where the customer needs to be redirected so they can complete the 3D Secure payment flow.

Anchor to orderorder

•Order

The result of this billing attempt if completed successfully.

Anchor to originTimeoriginTime

•DateTime

The date and time used to calculate fulfillment intervals for a billing attempt that successfully completed after the current anchor date. To prevent fulfillment from being pushed to the next anchor date, this field can override the billing attempt date.

Anchor to paymentGroupIdpaymentGroupId

•String

The reference shared between retried payment attempts.

Anchor to paymentSessionIdpaymentSessionId

•String

The reference shared between payment attempts with similar payment details.

Anchor to processingErrorprocessingError

•SubscriptionBillingAttemptProcessingError

Error information from processing the billing attempt.

Anchor to readyready

•Boolean!

non-null

Whether the billing attempt is still processing.

Anchor to respectInventoryPolicyrespectInventoryPolicy

•Boolean!

non-null

Whether the billing attempt respects the merchant's inventory policy.

Anchor to subscriptionContractsubscriptionContract

•SubscriptionContract!

non-null

The subscription contract.

Anchor to transactionstransactions

•OrderTransactionConnection!

non-null

The transactions created by the billing attempt.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to errorCodeerrorCode

•SubscriptionBillingAttemptErrorCode

Deprecated

Anchor to errorMessageerrorMessage

•String

Deprecated

Was this section helpful?

Examples

Query for a billing attempt with a processing error

Description

Shows how to query for error details.

Query

query findBillingAttempt($subscriptionBillingAttempt: ID!) {
  subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
    id
    nextActionUrl
    idempotencyKey
    ready
    order {
      id
    }
    subscriptionContract {
      id
    }
    processingError {
      __typename
      code
      message
      ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
        insufficientStockProductVariants(first: 3) {
          edges {
            node {
              id
              title
            }
          }
        }
      }
    }
  }
}

Variables

{
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
}

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": "query findBillingAttempt($subscriptionBillingAttempt: ID!) { subscriptionBillingAttempt(id: $subscriptionBillingAttempt) { id nextActionUrl idempotencyKey ready order { id } subscriptionContract { id } processingError { __typename code message ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError { insufficientStockProductVariants(first: 3) { edges { node { id title } } } } } } }",
 "variables": {
    "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      processingError {
        __typename
        code
        message
        ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
          insufficientStockProductVariants(first: 3) {
            edges {
              node {
                id
                title
              }
            }
          }
        }
      }
    }
  }`,
  {
    variables: {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
    },
  },
  );
  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
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      processingError {
        __typename
        code
        message
        ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
          insufficientStockProductVariants(first: 3) {
            edges {
              node {
                id
                title
              }
            }
          }
        }
      }
    }
  }
QUERY

variables = {
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query findBillingAttempt($subscriptionBillingAttempt: ID!) {
      subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
        id
        nextActionUrl
        idempotencyKey
        ready
        order {
          id
        }
        subscriptionContract {
          id
        }
        processingError {
          __typename
          code
          message
          ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
            insufficientStockProductVariants(first: 3) {
              edges {
                node {
                  id
                  title
                }
              }
            }
          }
        }
      }
    }`,
    "variables": {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
    },
  },
});

Response

{
  "subscriptionBillingAttempt": {
    "id": "gid://shopify/SubscriptionBillingAttempt/693432113",
    "nextActionUrl": null,
    "idempotencyKey": "unique-token",
    "ready": true,
    "order": {
      "id": "gid://shopify/Order/148977776"
    },
    "subscriptionContract": {
      "id": "gid://shopify/SubscriptionContract/593791907"
    },
    "processingError": {
      "__typename": "SubscriptionBillingAttemptInsufficientStockProductVariantsError",
      "code": "INSUFFICIENT_INVENTORY",
      "message": "Insufficient inventory.",
      "insufficientStockProductVariants": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ProductVariant/43729076",
              "title": "151cm"
            }
          }
        ]
      }
    }
  }
}

Query for a subscription billing attempt

Description

Finds a subscription billing attempt by id.

Query

query findBillingAttempt($subscriptionBillingAttempt: ID!) {
  subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
    id
    nextActionUrl
    idempotencyKey
    ready
    order {
      id
    }
    subscriptionContract {
      id
    }
    errorMessage
    errorCode
  }
}

Variables

{
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
}

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": "query findBillingAttempt($subscriptionBillingAttempt: ID!) { subscriptionBillingAttempt(id: $subscriptionBillingAttempt) { id nextActionUrl idempotencyKey ready order { id } subscriptionContract { id } errorMessage errorCode } }",
 "variables": {
    "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      errorMessage
      errorCode
    }
  }`,
  {
    variables: {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
    },
  },
  );
  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
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      errorMessage
      errorCode
    }
  }
QUERY

variables = {
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query findBillingAttempt($subscriptionBillingAttempt: ID!) {
      subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
        id
        nextActionUrl
        idempotencyKey
        ready
        order {
          id
        }
        subscriptionContract {
          id
        }
        errorMessage
        errorCode
      }
    }`,
    "variables": {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
    },
  },
});

Response

{
  "subscriptionBillingAttempt": {
    "id": "gid://shopify/SubscriptionBillingAttempt/693432112",
    "nextActionUrl": null,
    "idempotencyKey": "unique-token",
    "ready": true,
    "order": {
      "id": "gid://shopify/Order/148977776"
    },
    "subscriptionContract": {
      "id": "gid://shopify/SubscriptionContract/593791907"
    },
    "errorMessage": null,
    "errorCode": null
  }
}

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

query findBillingAttempt($subscriptionBillingAttempt: ID!) {

subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {

nextActionUrl

idempotencyKey

ready

order {

}

subscriptionContract {

}

processingError {

__typename

code

message

... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {

insufficientStockProductVariants(first: 3) {

edges {

node {

title

}

}`,

{

variables: {

"subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"

);

const json = await response.json();

return json.data;

}

GQL

query findBillingAttempt($subscriptionBillingAttempt: ID!) {
  subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
    id
    nextActionUrl
    idempotencyKey
    ready
    order {
      id
    }
    subscriptionContract {
      id
    }
    processingError {
      __typename
      code
      message
      ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
        insufficientStockProductVariants(first: 3) {
          edges {
            node {
              id
              title
            }
          }
        }
      }
    }
  }
}

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": "query findBillingAttempt($subscriptionBillingAttempt: ID!) { subscriptionBillingAttempt(id: $subscriptionBillingAttempt) { id nextActionUrl idempotencyKey ready order { id } subscriptionContract { id } processingError { __typename code message ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError { insufficientStockProductVariants(first: 3) { edges { node { id title } } } } } } }",
 "variables": {
    "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      processingError {
        __typename
        code
        message
        ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
          insufficientStockProductVariants(first: 3) {
            edges {
              node {
                id
                title
              }
            }
          }
        }
      }
    }
  }`,
  {
    variables: {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query findBillingAttempt($subscriptionBillingAttempt: ID!) {
      subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
        id
        nextActionUrl
        idempotencyKey
        ready
        order {
          id
        }
        subscriptionContract {
          id
        }
        processingError {
          __typename
          code
          message
          ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
            insufficientStockProductVariants(first: 3) {
              edges {
                node {
                  id
                  title
                }
              }
            }
          }
        }
      }
    }`,
    "variables": {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
    },
  },
});

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
  query findBillingAttempt($subscriptionBillingAttempt: ID!) {
    subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
      id
      nextActionUrl
      idempotencyKey
      ready
      order {
        id
      }
      subscriptionContract {
        id
      }
      processingError {
        __typename
        code
        message
        ... on SubscriptionBillingAttemptInsufficientStockProductVariantsError {
          insufficientStockProductVariants(first: 3) {
            edges {
              node {
                id
                title
              }
            }
          }
        }
      }
    }
  }
QUERY

variables = {
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"
}

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

Input variables

JSON

{

"subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113"

}

Response

JSON

{

"subscriptionBillingAttempt": {

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

"nextActionUrl": null,

"idempotencyKey": "unique-token",

"ready": true,

"order": {

"id": "gid://shopify/Order/148977776"

"subscriptionContract": {

"id": "gid://shopify/SubscriptionContract/593791907"

"processingError": {

"__typename": "SubscriptionBillingAttemptInsufficientStockProductVariantsError",

"code": "INSUFFICIENT_INVENTORY",

"message": "Insufficient inventory.",

"insufficientStockProductVariants": {

"edges": [

{

"node": {

"id": "gid://shopify/ProductVariant/43729076",

"title": "151cm"

}

]

}