Thanks for being patient while we implement your feedback to improve the developer experience.
API Docs
Building Headless Storefronts
Guide
Handling Orders

Handling Orders

This section explains how to create and manage orders for headless storefronts.

Creating an order from a cart

To successfully complete this section, you must first create a cart with a redirect URL. For instructions on how to create a cart, see the Carts section of this tutorial.

Adding a billing address

You can change a cart to a checkout by adding a billing address. To add a checkout billing address, send a POST request to the Add Checkout Billing Address endpoint. Your checkoutId will correspond with the cart id returned in response to Create a Cart.

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": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "address1": "123 Main Street",
  "address2": "",
  "city": "Austin",
  "state_or_province": "Texas",
  "state_or_province_code": "TX",
  "country_code": "US",
  "postal_code": "78751",
  "phone": "1234567890"
}

Adding a consignment

Now that you have transformed your headless cart into a checkout, you need to add a consignment with a shipping address, line items, and a shipping option. You can do so following this two-step process:

Step 1: Add a new consignment to the checkout

Send a POST request to the Add Consignment to Checkout endpoint. Append the include=consignments.available_shipping_options query parameter to your POST request to return available_shipping_options (required for step two).

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": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "address1": "123 Main Street",
      "address2": "",
      "city": "Austin",
      "state_or_province": "Texas",
      "state_or_province_code": "TX",
      "country_code": "US",
      "postal_code": "78751",
      "phone": "1234567890"
    },
    "line_items": [
      {
        "item_id": "7e2f9b22-a16e-4056-9e2d-8fc919bcf653",
        "quantity": 1
      }
    ]
  }
]

The response will contain an array of available_shipping_options. You will use one of the available shipping options to update the consignment in the next step.

Example response: Add Consignment to checkout
"available_shipping_options": [
  {
    "id": "80ad65f7946c23bd4ee9a531d85c5e21",
    "type": "shipping_pickupinstore",
    "description": "Pickup In Store",
    "image_url": "",
    "cost": 0,
    "transit_time": "",
    "additional_description": ""
  },
  {
    "id": "4dcbf24f457dd67d5f89bcf374e0bc9b",
    "type": "freeshipping",
    "description": "Free Shipping",
    "image_url": "",
    "cost": 0,
    "transit_time": "",
    "additional_description": ""
  },
  {
    "id": "85dfaf5f834d7e594f0bd7cf67d5b200",
    "type": "shipping_flatrate",
    "description": "Flat Rate",
    "image_url": "",
    "cost": 5,
    "transit_time": "",
    "additional_description": ""
  },
  {
    "id": "8809b0bbcc8bdc2d5cad2a4fcbd6cf09",
    "type": "shipping_byweight",
    "description": "Ship by Weight",
    "image_url": "",
    "cost": 10,
    "transit_time": "",
    "additional_description": ""
  }
]

Step 2: Update the consignment

Use one of the available shipping options to update the consignment you created in Step 1. Send a PUT 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": "4dcbf24f457dd67d5f89bcf374e0bc9b"
}

Creating an order

Now that you have added a billing address and a consignment to your checkout, you can create an order by sending a POST request to the Create an Order endpoint. The order status will be set to 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}}

Processing payments

Depending on the shopper's card-on-file authorization, you can use one of the following methods to process the payment.

  • Stored Card – A shopper has authorized a merchant to store their payment details.
  • Credit Card – A shopper has not authorized a merchant to store their payment details.

Using the Stored Card method

  1. Start by retrieving the available payment methods. Send a GET request to the Get Accepted Payment Methods endpoint.
Example request: Get accepted payment methods
GET https://api.bigcommerce.com/stores/{store_hash}/v3/payments/methods
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
  1. To process a payment for an order, you will need to make a call to the Payments API which requires an access token. To generate an access token, send a POST request to the Create Payment Access Token endpoint.
Example request: Create payment access token
POST https://api.bigcommerce.com/stores/{store_hash}/v3/payments/access_tokens
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "order": {
    "id": 125,
    "is_recurring": false
  }
}

Make a note of the access token id. This token is required in subsequent payment request to the Process Payment endpoint.

  1. Send a POST request to the Process Payment endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The authorization token is the ID returned in Create Payment Access Token (step two). To learn more, see Stored cards.
Example request: Process payment
POST https://api.bigcommerce.com/stores/{store_hash}/payments
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
 
{
  "payment": {
    "instrument": {
      "type": "stored_card",
      "token": "8cdf7b6ea1b27119463bf9e5106639618cc77a9adc49f0069ca8b756cc15caee",
      "verification_value": "1142"
    },
    "payment_method_id": "adyenv2.scheme",
    "save_instrument": true
  }
}

Using the Credit Card method

If a shopper does not have a payment method saved on file, you can process a payment using a credit card. There are two steps to this method:

  1. Send a POST request to the Create Payment Access Token endpoint to get the authorization token that needs to be passed in the header when processing the payment.

  2. Send a POST request to the Process Payment endpoint. The headers to process a payment are different than the headers you normally send with a BigCommerce API. The Authorization token is the ID returned in Create Payment Access Token (step one). To learn more, see Credit cards.

Example response: Process payment
{
  "data": {
    "id": "693bb4cd-3f20-444a-8315-6369f582c68a",
    "status": "success",
    "transaction_type": "purchase"
  }
}

A successful transaction will return a status of success. The order is then automatically moved to an Awaiting Fulfillment status. If you get a different response, see Error Codes for troubleshooting.

Next steps

Resources