Choose a version:

SubscriptionBillingAttempt

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

Anchor to FieldsFields

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 nextActionUrlnextActionUrl •URL: The URL where the customer needs to be redirected so they can complete the 3D Secure payment flow.
Anchor to orderorder •Order: The result of this billing attempt if completed successfully.
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 processingErrorprocessingError •SubscriptionBillingAttemptProcessingError: Error information from processing the billing attempt.
Anchor to readyready •Boolean! non-null: Whether the billing attempt is still processing.
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.
Anchor to transactionstransactions •OrderTransactionConnection! non-null: The transactions created by the billing attempt.

Deprecated fields

Anchor to errorCodeerrorCode •SubscriptionBillingAttemptErrorCode Deprecated
Anchor to errorMessageerrorMessage •String Deprecated

Was this section helpful?

Anchor to QueriesQueries

Anchor to subscriptionBillingAttempt subscriptionBillingAttempt •query: Returns a SubscriptionBillingAttempt resource by ID.
Anchor to subscriptionBillingAttempts subscriptionBillingAttempts •query: Returns subscription billing attempts on a store.

Was this section helpful?

Anchor to MutationsMutations

Anchor to subscriptionBillingAttemptCreate subscriptionBillingAttemptCreate •mutation: Creates a billing attempt to charge for a SubscriptionContract. The mutation processes either the payment for the current billing cycle or for a specific cycle, if selected.

The mutation creates an Order when successful. Failed billing attempts include a processingError field with error details.

Tip
Use the 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 to bill past or future cycles. The originTime parameter adjusts fulfillment scheduling for attempts completed after the expected billing date.

Learn more about creating billing attempts.
Anchor to subscriptionBillingCycleCharge subscriptionBillingCycleCharge •mutation: Creates a new subscription billing attempt for a specified billing cycle. This is the alternative mutation for subscriptionBillingAttemptCreate. For more information, refer to Create a subscription contract.

Was this section helpful?

Anchor to InterfacesInterfaces

Anchor to Node Node •interface

Was this section helpful?