Checkout flow

Given the amount of endpoints at your disposal, it can be difficult to understand how to string the right API calls together to perform a full checkout flow. This document explains how to perform a full checkout flow.

1. Create an order

The first step is to create an order via POST /orders. You should save the number of the order that is created as well as the guest token, in case you are not authenticating with an API key.

2. Fill the cart

Once you have an order, you can begin filling your cart. Here are some endpoints you can use for that:

• POST /checkouts/:order_number/line_items
• PATCH /checkouts/:order_number/line_items/:id
• DELETE /checkouts/:order_number/line_items/:id
• PUT /orders/:order_number/empty

3. (Optional) Apply a coupon code

You can also apply a coupon code on the order via POST /orders/:order_number/coupon_codes.

4. Start the checkout flow

When you are ready to start the checkout flow, you can call PUT /checkouts/:order_number/next to transition the order from the cart to the address state.

5. Enter billing and shipping addresses

To enter the billing and shipping addresses, use the PATCH /checkouts/:order_number endpoint.

The checkouts#update endpoint always advance the order to the next state. If the above request is successful, the order should now be in the delivery state.

6. Select a shipping method

You can retrieve the available shipping methods, along with their rates, via GET /orders/:order_number or GET /orders/current. This allows you to let your user choose the shipping method they prefer.

When you want to select a shipping method, call PUT /checkouts/:order_number:

  {
    "order": {
      "shipments_attributes": {
        "0": {
          "selected_shipping_rate_id": :shipping_rate_id,
          "id": :shipment_id
        }
      }
    }
  }

If the above request is successful, the order should now be in the payment state.

7. Enter payment details

To create a payment, call POST /orders/:order_number/payments.

Now call PUT /checkouts/:order_number/next to transition the order from the payment to the confirm state.

8. Complete the order

At this point, you should show the user a summary of their cart and ask them to confirm they want to place the order.

When they confirm, call PUT /checkouts/:order_number/complete to complete the checkout flow and place the order!