# SubscriptionBillingAttempt - admin-graphql - OBJECT Version: unstable ## Description A record of an execution of the subscription billing process. Billing attempts use idempotency keys to avoid duplicate order creation. A successful billing attempt will create an order. ### Access Scopes `read_own_subscription_contracts` access scope. ## Fields * [completedAt](/docs/api/admin-graphql/unstable/scalars/DateTime): DateTime - The date and time when the billing attempt was completed. * [createdAt](/docs/api/admin-graphql/unstable/scalars/DateTime): DateTime! - The date and time when the billing attempt was created. * [errorCode](/docs/api/admin-graphql/unstable/enums/SubscriptionBillingAttemptErrorCode): SubscriptionBillingAttemptErrorCode - A code corresponding to a payment error during processing. * [errorMessage](/docs/api/admin-graphql/unstable/scalars/String): String - A message describing a payment error during processing. * [id](/docs/api/admin-graphql/unstable/scalars/ID): ID! - A globally-unique ID. * [idempotencyKey](/docs/api/admin-graphql/unstable/scalars/String): String! - A unique key generated by the client to avoid duplicate payments. * [nextActionUrl](/docs/api/admin-graphql/unstable/scalars/URL): URL - The URL where the customer needs to be redirected so they can complete the 3D Secure payment flow. * [order](/docs/api/admin-graphql/unstable/objects/Order): Order - The result of this billing attempt if completed successfully. * [originTime](/docs/api/admin-graphql/unstable/scalars/DateTime): 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. * [paymentGroupId](/docs/api/admin-graphql/unstable/scalars/String): String - The reference shared between retried payment attempts. * [paymentSessionId](/docs/api/admin-graphql/unstable/scalars/String): String - The reference shared between payment attempts with similar payment details. * [processingError](/docs/api/admin-graphql/unstable/interfaces/SubscriptionBillingAttemptProcessingError): SubscriptionBillingAttemptProcessingError - Error information from processing the billing attempt. * [ready](/docs/api/admin-graphql/unstable/scalars/Boolean): Boolean! - Whether the billing attempt is still processing. * [respectInventoryPolicy](/docs/api/admin-graphql/unstable/scalars/Boolean): Boolean! - Whether the billing attempt respects the merchant's inventory policy. * [subscriptionContract](/docs/api/admin-graphql/unstable/objects/SubscriptionContract): SubscriptionContract! - The subscription contract. ## Connections * [transactions](/docs/api/admin-graphql/unstable/connections/OrderTransactionConnection): OrderTransactionConnection! ## Related queries * [subscriptionBillingAttempt](/docs/api/admin-graphql/unstable/queries/subscriptionBillingAttempt) Returns a SubscriptionBillingAttempt by ID. * [subscriptionBillingAttempts](/docs/api/admin-graphql/unstable/queries/subscriptionBillingAttempts) Returns subscription billing attempts on a store. ## Related mutations * [subscriptionBillingAttemptCreate](/docs/api/admin-graphql/unstable/mutations/subscriptionBillingAttemptCreate) Creates a new subscription billing attempt. For more information, refer to [Create a subscription contract](https://shopify.dev/docs/apps/selling-strategies/subscriptions/contracts/create#step-4-create-a-billing-attempt). * [subscriptionBillingCycleCharge](/docs/api/admin-graphql/unstable/mutations/subscriptionBillingCycleCharge) Creates a new subscription billing attempt for a specified billing cycle. This is the alternative mutation for [subscriptionBillingAttemptCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingAttemptCreate). For more information, refer to [Create a subscription contract](https://shopify.dev/docs/apps/selling-strategies/subscriptions/contracts/create#step-4-create-a-billing-attempt). ## Related Unions ## Examples ### Query for a billing attempt with a processing error Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/unstable/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"query findBillingAttempt($subscriptionBillingAttempt: ID!) { subscriptionBillingAttempt(id: $subscriptionBillingAttempt) { id nextActionUrl idempotencyKey ready order { id } subscriptionContract { id } processingError { __typename code message ... on SubscriptionBillingAttemptOutOfStockProductVariantsError { outOfStockProductVariants(first: 3) { edges { node { id title } } } } } } }\",\n \"variables\": {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432113\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n processingError {\n __typename\n code\n message\n ... on SubscriptionBillingAttemptOutOfStockProductVariantsError {\n outOfStockProductVariants(first: 3) {\n edges {\n node {\n id\n title\n }\n }\n }\n }\n }\n }\n }`,\n \"variables\": {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432113\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n processingError {\n __typename\n code\n message\n ... on SubscriptionBillingAttemptOutOfStockProductVariantsError {\n outOfStockProductVariants(first: 3) {\n edges {\n node {\n id\n title\n }\n }\n }\n }\n }\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432113\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n processingError {\n __typename\n code\n message\n ... on SubscriptionBillingAttemptOutOfStockProductVariantsError {\n outOfStockProductVariants(first: 3) {\n edges {\n node {\n id\n title\n }\n }\n }\n }\n }\n }\n }`,\n {\n variables: {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432113\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n processingError {\n __typename\n code\n message\n ... on SubscriptionBillingAttemptOutOfStockProductVariantsError {\n outOfStockProductVariants(first: 3) {\n edges {\n node {\n id\n title\n }\n }\n }\n }\n }\n }\n}" #### Graphql Input { "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432113" } #### Graphql Response { "data": { "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": "SubscriptionBillingAttemptOutOfStockProductVariantsError", "code": "INSUFFICIENT_INVENTORY", "message": "Insufficient inventory.", "outOfStockProductVariants": { "edges": [ { "node": { "id": "gid://shopify/ProductVariant/43729076", "title": "151cm" } } ] } } } } } ### Query for a subscription billing attempt Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/unstable/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"query findBillingAttempt($subscriptionBillingAttempt: ID!) { subscriptionBillingAttempt(id: $subscriptionBillingAttempt) { id nextActionUrl idempotencyKey ready order { id } subscriptionContract { id } errorMessage errorCode } }\",\n \"variables\": {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432112\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n errorMessage\n errorCode\n }\n }`,\n \"variables\": {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432112\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n errorMessage\n errorCode\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432112\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n errorMessage\n errorCode\n }\n }`,\n {\n variables: {\n \"subscriptionBillingAttempt\": \"gid://shopify/SubscriptionBillingAttempt/693432112\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "query findBillingAttempt($subscriptionBillingAttempt: ID!) {\n subscriptionBillingAttempt(id: $subscriptionBillingAttempt) {\n id\n nextActionUrl\n idempotencyKey\n ready\n order {\n id\n }\n subscriptionContract {\n id\n }\n errorMessage\n errorCode\n }\n}" #### Graphql Input { "subscriptionBillingAttempt": "gid://shopify/SubscriptionBillingAttempt/693432112" } #### Graphql Response { "data": { "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 } } }