--- 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: 2026-10 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 api_name: admin api_type: graphql type: object --- # 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. * 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. * 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. * state [Subscription​Billing​Attempt​State!](https://shopify.dev/docs/api/admin-graphql/latest/unions/SubscriptionBillingAttemptState) non-null The state of the billing attempt with state-specific data. * 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. * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) ### Arguments The elements that come after the specified [cursor](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). * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](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). * 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 * next​Action​Url [URL](https://shopify.dev/docs/api/admin-graphql/latest/scalars/URL) Deprecated * order [Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) Deprecated * processing​Error [Subscription​Billing​Attempt​Processing​Error](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/SubscriptionBillingAttemptProcessingError) Deprecated * ready [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-nullDeprecated *** ## 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. * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) ### Arguments The elements that come after the specified [cursor](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). * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](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). * 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` * 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). *** *** ## 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 \\\idempotency\Key\\\ 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​Attempt​Input [Subscription​Billing​Attempt​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/SubscriptionBillingAttemptInput) required ### Arguments The information to apply as a billing attempt. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required The ID of the subscription contract. *** * [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). * actor [Subscription​Actor](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionActor) ### Arguments The actor who initiated a subscription action. * 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. * payment​Processing​Policy [Subscription​Billing​Attempt​Payment​Processing​Policy](https://shopify.dev/docs/api/admin-graphql/latest/enums/SubscriptionBillingAttemptPaymentProcessingPolicy) Select payment processing policy for the billing attempt. Defaults to FAIL\_UNLESS\_VALID\_PAYMENT\_METHOD. * subscription​Contract​Id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required The ID of the subscription contract. *** *** ## 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)