Docs
Storefront
Custom headless storefronts
End-to-end guides
REST Management API: Headless checkout flow

End-to-End Guide: Headless checkout flow with the REST Management API

This tutorial walks you through creating a cart, checkout, an order, and processing a payment using the Carts and Checkout REST Management APIs to build a headless storefront.

This article assumes you are familiar with the following:

  • Creating a channel and a site.
  • Retrieving product data using REST Management API calls

Prerequisites

  • A store-level or app-level API account with the following permissions:
UI NamePermissionParameter
Cartsmodifystore_cart
Checkoutsmodifystore_checkouts
Ordersmodifystore_v2_orders
Productsread-onlystore_v2_products_read_only

For more information, see OAuth Scopes.

Creating a cart

Step 1: Generate the cart ID

To generate a cart ID, send a request to the Create a cart endpoint. The response contains an id, which is the cart_id or cartId in subsequent calls.

Example request: Create a cart
  POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts
  Accept: application/json
  Content-Type: application/json
  X-Auth-Token: {{ACCESS_TOKEN}}
  {
    "customer_id": 0,
    "line_items": [
        {
        "quantity": 2,
        "product_id": 120,
        "list_price": 15,
        "name": "mug"
        }
    ],
    "channel_id": 1,
    "currency": {
        "code": "USD"
    },
    "locale": "en-US"
  }

Step 2: Generate the redirect URLs

After you generate the cart ID, generate URLs to redirect customers to the BigCommerce-hosted cart and checkout pages.

To generate the redirect URLs, send a request to the Create a cart redirect URL endpoint. You use the cart ID generated in Step 1. The response contains the cart_url and the checkout_url.

Example request: Create cart redirect URLs
  POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts/{{cartId}}/redirect_urls
  Accept: application/json
  Content-Type: application/json
  X-Auth-Token: {{ACCESS_TOKEN}}
  {}

Creating a checkout

After you create a cart, transform it into a checkout by adding a billing address. You must have a checkoutId, which is the same as the cart_id you generated in Step 1 of creating a cart. To add a billing address, send a request to the Add Checkout Billing Address endpoint.

Example request: Add Checkout Billing Address
  POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/billing-address
  Accept: application/json
  Content-Type: application/json
  X-Auth-Token: {{ACCESS_TOKEN}}
  {
    "first_name": "Test",
    "last_name": "User",
    "email": "Test.User@email.com",
    "company": "BigCommerce",
    "address1": "555 Main Street",
    "address2": "",
    "city": "Austin",
    "state_or_province": "TX",
    "state_or_province_code": "TX",
    "country_code": "US",
    "postal_code": "78701",
    "phone": "555-555-5555"
  }

After you transform your headless cart into a proper checkout with a billing address, you can add a consignment with a shipping address, line items, and a shipping option. You can do so using the following two-step process:

Step 1: Add a new consignment to the checkout

Send a request to the Add Consignment to Checkout endpoint. Append the include=consignments.available_shipping_options query parameter to your request to return available shipping options. Use one of the available shipping options to update the consignment in step 2.

Example request: Add Consignment to checkout
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/consignments?include=consignments.available_shipping_options
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
[
  {
    "shipping_address": {
      "first_name": "Test",
      "last_name": "User",
      "email": "Test.User@example.com",
      "company": "BigCommerce",
      "address1": "555 Main Street",
      "address2": "",
      "city": "Austin",
      "state_or_province": "Texas",
      "state_or_province_code": "TX",
      "country_code": "US",
      "postal_code": "78701",
      "phone": "555-555-5555"
    },
    "line_items": [
      {
        "item_id": "ca9ef0d1-1da9-48e5-a505-7051eb575432",
        "quantity": 2
      }
    ]
  }
]

The response contains an array of available_shipping_options. In the next step, use one of the available shipping options to update the consignment.

available shipping options
  "available_shipping_options": [
    {
      "id": "6ded13392879983ee32a3563f5fa6a7b",
      "type": "shipping_pickupinstore",
      "description": "Pickup In Store",
      "image_url": "",
      "cost": 0,
      "transit_time": "",
      "additional_description": ""
    },
    {
      "id": "26fb2db4ad77b0f039328d22d2869617",
      "type": "shipping_flatrate",
      "description": "Flat Rate",
      "image_url": "",
      "cost": 5,
      "transit_time": "",
      "additional_description": ""
    },
    {
      "id": "508540c73074d5ffa2cc3dced0adc552",
      "type": "shipping_byweight",
      "description": "Ship by Weight",
      "image_url": "",
      "cost": 8,
      "transit_time": "",
      "additional_description": ""
    }
  ]

Step 2: Update the consignment with a shipping option

After you create the consignment, update it with one of the available shipping options the previous request returned. Send a request to the Update Checkout Consignment endpoint.

Example request: Update checkout consignment
  PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/consignments/{{consignmentId}}
  Accept: application/json
  Content-Type: application/json
  X-Auth-Token: {{ACCESS_TOKEN}}
  {
    "shipping_option_id": "6ded13392879983ee32a3563f5fa6a7b"
  }

Creating an order

After you add a billing address and a consignment to your checkout, you can create an order by sending a request to the Create an Order endpoint. The initial order status is incomplete.

Example request: Create an order
  POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkoutId}}/orders
  Accept: application/json
  Content-Type: application/json
  X-Auth-Token: {{ACCESS_TOKEN}}

Resources

API Reference: REST Management

Did you find what you were looking for?
Introduction to headless commerceGraphQL Storefront API: Headless checkout flow