--- 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-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/subscriptionbillingattempt md: https://shopify.dev/docs/api/admin-graphql/latest/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/latest/scalars/DateTime) The date and time when the billing attempt was completed. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the billing attempt was created. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * idempotency​Key [String!](https://shopify.dev/docs/api/admin-graphql/latest/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/latest/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/latest/objects/Order) The result of this billing attempt if completed successfully. * origin​Time [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/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/latest/scalars/String) The reference shared between retried payment attempts. * payment​Session​Id [String](https://shopify.dev/docs/api/admin-graphql/latest/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/latest/interfaces/SubscriptionBillingAttemptProcessingError) Error information from processing the billing attempt. * ready [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the billing attempt is still processing. * respect​Inventory​Policy [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/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/latest/objects/SubscriptionContract) non-null The subscription contract. * transactions [Order​Transaction​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/OrderTransactionConnection) non-null The transactions created by the billing attempt. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** ### Deprecated fields * error​Code [Subscription​Billing​Attempt​Error​Code](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptErrorCode) Deprecated * error​Message [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) Deprecated *** ## Map ### Fields and connections with this object * <->[SubscriptionBillingAttemptConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/SubscriptionBillingAttemptConnection#returns-nodes) * {}[SubscriptionBillingAttemptEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttemptEdge#field-SubscriptionBillingAttemptEdge.fields.node) * {}[SubscriptionBillingCycle.billingAttempts](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycle#field-SubscriptionBillingCycle.fields.billingAttempts) * {}[SubscriptionContract.billingAttempts](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionContract#field-SubscriptionContract.fields.billingAttempts) *** ## Queries * [subscription​Billing​Attempt](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingAttempt) query Returns a `SubscriptionBillingAttempt` resource by ID. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the `SubscriptionBillingAttempt` to return. *** * [subscription​Billing​Attempts](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingAttempts) query Returns subscription billing attempts on a store. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Subscription​Billing​Attempts​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptsSortKeys) Default:CREATED\_AT Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax). * created\_at time * error\_code string * error\_message string * id id Filter by `id` range. Example: * `id:1234` * `id:>=1234` * `id:<=1234` *** *** ## \SubscriptionBillingAttempt Queries ### Queried by * \[subscription​Billing​Attempt](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingAttempt) * \[subscription​Billing​Attempts](https://shopify.dev/docs/api/admin-graphql/latest/queries/subscriptionBillingAttempts) *** ## Mutations * [subscription​Billing​Attempt​Create](https://shopify.dev/docs/api/admin-graphql/latest/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​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the subscription contract. * subscription​Billing​Attempt​Input [Subscription​Billing​Attempt​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/SubscriptionBillingAttemptInput) required The information to apply as a billing attempt. *** * [subscription​Billing​Cycle​Charge](https://shopify.dev/docs/api/admin-graphql/latest/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). * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the subscription contract. * billing​Cycle​Selector [Subscription​Billing​Cycle​Selector!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/SubscriptionBillingCycleSelector) required Select the specific billing cycle to be billed. If the selected billing cycle's [billingAttemptExpectedDate](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycle#field-subscriptionbillingcycle-billingattemptexpecteddate) is in the past, the [originTime](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingAttempt#field-subscriptionbillingattempt-origintime) of the billing attempt will be set to this date. However, if the [billingAttemptExpectedDate](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycle#field-subscriptionbillingcycle-billingattemptexpecteddate) is in the future, the originTime will be the current time. * inventory​Policy [Subscription​Billing​Attempt​Inventory​Policy](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptInventoryPolicy) Default:PRODUCT\_VARIANT\_INVENTORY\_POLICY The behaviour to use when updating inventory. *** *** ## <\~> SubscriptionBillingAttempt Mutations ### Mutated by * <\~>[subscription​Billing​Attempt​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingAttemptCreate) * <\~>[subscription​Billing​Cycle​Charge](https://shopify.dev/docs/api/admin-graphql/latest/mutations/subscriptionBillingCycleCharge) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## ||-SubscriptionBillingAttempt Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)