Handling a rejected order

Learn how to handle order failures.

On occasion, when you submit an order, the request may be rejected. How you should handle these rejected POST /orders depends on whether you receive a 409 response status code or a non-409 response in the 4xx range.

If your integration is on version 2021-03-23 or higher, you can use a checkout's payment session to determine when a checkout can be successfully converted to an order. By ensuring the payment session is in the correct state, you can greatly minimize order failures.

409 response status code

If you submit a POST /orders, and receive a 409 response status code, you can use the type, code, and message contained in the error to help diagnose the failure. However, once you isolate the problem, you can't simply update the checkout. Instead, you must create a new checkout and send its identifier in the payload of a create order request.

Order failures with a 409 response status code are often due to charge authorization declines that result from insufficient funds or lack of credit. If this is the case, you should obtain new payment method information from the customer, use it to create a source and then attach the source to the new checkout. Alternatively, in the case of registered checkouts, you could authenticate one of the customer's existing payment sources and then attach the source to the checkout.

non-409 response status code in the 4xx range

If you submit a POST /orders, and receive a non-409 response status code in the 4xx range , you can use the type, code, and message contained in the error to help diagnose the failure. Once you isolate the problem, you can modify the existing checkout, send a POST /checkouts/{id}, and then attempt to resubmit the order. In other words, in this scenario, you can send the same checkout identifier in the payload of a create order request.

You cannot however re-use a checkout identifier once it's been sent in the payload of a successful POST /orders request.