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.

Show fields

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 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 respectInventoryPolicyrespectInventoryPolicy

•Boolean!

non-null

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

Anchor to subscriptionContractsubscriptionContract

•SubscriptionContract!

non-null

The subscription contract.

Show fields

Anchor to transactionstransactions

•OrderTransactionConnection!

non-null

The transactions created by the billing attempt.

Show fields

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

Anchor to errorCodeerrorCode

•SubscriptionBillingAttemptErrorCode

Deprecated

Show enum values

Anchor to errorMessageerrorMessage

•String

Deprecated

Anchor to nextActionUrlnextActionUrl

•URL

Deprecated

Anchor to orderorder

•Order

Deprecated

Show fields

Anchor to processingErrorprocessingError

•SubscriptionBillingAttemptProcessingError

Deprecated

Show fields

Anchor to readyready

•Boolean!

non-nullDeprecated

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"
    },
  },
});

Shopify CLI

shopify app execute \
--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"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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"
    },
  }),
});

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

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"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query findBillingAttempt($subscriptionBillingAttempt: ID!) {
  subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
    id
    nextActionUrl
    idempotencyKey
    ready
    order {
      id
    }
    subscriptionContract {
      id
    }
    errorMessage
    errorCode
  }
}' \
--variables \
'{
  "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query findBillingAttempt($subscriptionBillingAttempt: ID!) {
        subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {
          id
          nextActionUrl
          idempotencyKey
          ready
          order {
            id
          }
          subscriptionContract {
            id
          }
          errorMessage
          errorCode
        }
      }
    `,
    variables: {
        "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112"
    },
  }),
});

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

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

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)

Shopify CLI

shopify app execute \
--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"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    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"
    },
  }),
});

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

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"

}

]

}