Payment Recovery

When a payment fails after an order has been created or for a renewing subscription, the order or subscription enters the PAYMENT_PROBLEM / FAILED_PAYMENT state. These mutations let the customer drop straight back into checkout to retry payment without rebuilding the basket.

All four mutations return a CheckoutStartResponse with the same error, token and checkoutUrl fields as the original checkout mutation — redirect the customer to checkoutUrl exactly as you would for a fresh checkout. The CheckoutStartError values relevant to recovery are NO_SUCH_ORDER, NO_SUCH_SUBSCRIPTION, NO_PAYMENT_PROBLEM, INVALID_TOKEN and EXPIRED_TOKEN.

Retrying payment for an order (authenticated)

Used from the account section when the customer comes back to fix a failed order. Requires authentication; the order must belong to the current customer and must actually have a payment problem.

mutation ResolveOrderPaymentProblem {
  resolveOrderPaymentProblem(orderNumber: "ORD-12345") {
    error
    checkoutUrl
  }
}

Retrying payment for an order from an email link

Payment failure emails carry a one-time token so the customer can resolve the problem without logging in. The token authorises the operation in place of authentication. Surface INVALID_TOKEN and EXPIRED_TOKEN errors with a prompt to log in and use the authenticated path instead.

mutation ResolveOrderPaymentProblemByToken {
  resolveOrderPaymentProblemByToken(
    orderNumber: "ORD-12345"
    token: "pay_token_abc123..."
  ) {
    error
    checkoutUrl
  }
}

Retrying payment for a subscription

For a subscription in FAILED_PAYMENT state. Requires authentication and the SUBSCRIPTIONS feature.

mutation ResolveSubscriptionPaymentProblem {
  resolveSubscriptionPaymentProblem(subscriptionId: "sub_12345") {
    error
    checkoutUrl
  }
}

Updating the payment method on a subscription

Lets the customer change the saved card used for future subscription orders. The customer is sent to a checkout-style flow to capture the new card; once they return, subsequent renewals use it.

mutation UpdateSubscriptionPaymentMethod {
  updateSubscriptionPaymentMethod(subscriptionId: "sub_12345") {
    error
    checkoutUrl
  }
}