--- title: SubscriptionBillingAttempt - GraphQL Admin description: |- 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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. api_version: 2025-07 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/2025-07/objects/subscriptionbillingattempt md: https://shopify.dev/docs/api/admin-graphql/2025-07/objects/subscriptionbillingattempt.md --- # Subscription​Billing​Attempt object Requires `read_own_subscription_contracts` access scope. 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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. ## Fields * completed​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/DateTime) The date and time when the billing attempt was completed. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/DateTime) non-null The date and time when the billing attempt was created. * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/ID) non-null A globally-unique ID. * idempotency​Key [String!](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/String) non-null A unique key generated by the client to avoid duplicate payments. * next​Action​Url [URL](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/URL) The URL where the customer needs to be redirected so they can complete the 3D Secure payment flow. * order [Order](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/Order) The result of this billing attempt if completed successfully. * origin​Time [Date​Time](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/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. * payment​Group​Id [String](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/String) The reference shared between retried payment attempts. * payment​Session​Id [String](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/String) The reference shared between payment attempts with similar payment details. * processing​Error [Subscription​Billing​Attempt​Processing​Error](https://shopify.dev/docs/api/admin-graphql/2025-07/interfaces/SubscriptionBillingAttemptProcessingError) Error information from processing the billing attempt. * ready [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/Boolean) non-null Whether the billing attempt is still processing. * respect​Inventory​Policy [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/Boolean) non-null Whether the billing attempt respects the merchant's inventory policy. * subscription​Contract [Subscription​Contract!](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SubscriptionContract) non-null The subscription contract. * transactions [Order​Transaction​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-07/connections/OrderTransactionConnection) non-null The transactions created by the billing attempt. ### Deprecated fields * error​Code [Subscription​Billing​Attempt​Error​Code](https://shopify.dev/docs/api/admin-graphql/2025-07/enums/SubscriptionBillingAttemptErrorCode) Deprecated * error​Message [String](https://shopify.dev/docs/api/admin-graphql/2025-07/scalars/String) Deprecated *** ## Map ### Fields and connections with this object * <->[SubscriptionBillingAttemptConnection.nodes](https://shopify.dev/docs/api/admin-graphql/2025-07/connections/SubscriptionBillingAttemptConnection#returns-nodes) * {}[SubscriptionBillingAttemptEdge.node](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SubscriptionBillingAttemptEdge#field-SubscriptionBillingAttemptEdge.fields.node) * {}[SubscriptionBillingCycle.billingAttempts](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SubscriptionBillingCycle#field-SubscriptionBillingCycle.fields.billingAttempts) * {}[SubscriptionContract.billingAttempts](https://shopify.dev/docs/api/admin-graphql/2025-07/objects/SubscriptionContract#field-SubscriptionContract.fields.billingAttempts) *** ## Queries * [subscription​Billing​Attempt](https://shopify.dev/docs/api/admin-graphql/2025-07/queries/subscriptionBillingAttempt) query Returns a `SubscriptionBillingAttempt` resource by ID. * [subscription​Billing​Attempts](https://shopify.dev/docs/api/admin-graphql/2025-07/queries/subscriptionBillingAttempts) query Returns subscription billing attempts on a store. *** ## \SubscriptionBillingAttempt Queries ### Queried by * \[subscription​Billing​Attempt](https://shopify.dev/docs/api/admin-graphql/2025-07/queries/subscriptionBillingAttempt) * \[subscription​Billing​Attempts](https://shopify.dev/docs/api/admin-graphql/2025-07/queries/subscriptionBillingAttempts) *** ## Mutations * [subscription​Billing​Attempt​Create](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/subscriptionBillingAttemptCreate) mutation Creates a billing attempt to charge for a [`SubscriptionContract`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionContract). The mutation processes either the payment for the current billing cycle or for a specific cycle, if selected. The mutation creates an [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) when successful. Failed billing attempts include a [`processingError`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingAttemptCreate#returns-subscriptionBillingAttempt.fields.processingError) field with error details. *** Tip Use the [`idempotencyKey`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingAttemptCreate#arguments-subscriptionBillingAttemptInput.fields.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`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/SubscriptionBillingCycleSelector) to bill past or future cycles. The [`originTime`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttempt#field-SubscriptionBillingAttempt.fields.originTime) parameter adjusts fulfillment scheduling for attempts completed after the expected billing date. Learn more about [creating billing attempts](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/build-a-subscription-contract#step-4-create-a-billing-attempt). * [subscription​Billing​Cycle​Charge](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/subscriptionBillingCycleCharge) mutation 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). *** ## <\~> SubscriptionBillingAttempt Mutations ### Mutated by * <\~>[subscription​Billing​Attempt​Create](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/subscriptionBillingAttemptCreate) * <\~>[subscription​Billing​Cycle​Charge](https://shopify.dev/docs/api/admin-graphql/2025-07/mutations/subscriptionBillingCycleCharge) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/2025-07/interfaces/Node) interface *** ## ||-SubscriptionBillingAttempt Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/2025-07/interfaces/Node)