> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Checkout API

Lesson 5 of 26 · 30 min

## What is Checkout API?

Checkout API allows for a checkout to be created from an existing cart using BigCommerce checkout logic. The existing BigCommerce front-end cart/checkout can be bypassed.

### Why is it important?

The Checkout API makes it possible to purchase products from a BigCommerce store programmatically. You also have the option to use the GraphQL Storefront API to build an external checkout in your CMS or app.

### When to Use the Checkout API:

* Headless Commerce - manage various operations in a custom checkout on a headless storefront.
* Take a checkout in progress on the storefront and validate its address details externally, then post back a corrected address.
* Fill out a checkout object so that the user only has to enter their credit card details.

## GET a Checkout

You can retrieve a checkout by sending a **GET** request to the `/checkouts` endpoint and including the `checkout_id`.

```http showLineNumbers={false}
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}
```

> **Info**
>
> `Cart_id` and `checkout_id` are the same Id.

## Add Checkout Billing Address

You can add a billing address to an existing checkout by sending a **POST** request to `/checkouts/{checkout_id}/billing-address`

```http showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/billing-address
```

**Required Fields:**

* `email`
* `country_code`

**Body Example**

```json showLineNumbers={false}
{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@email.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"
}
```

![Example Response](/_fern-files/bigcommerce.docs.buildwithfern.com/1fe631dcc9f6b3572c99fda5ddccab0034a56c26c22d54cca3cf64836f6659a2/assets/learn/checkout-orders-rest-api/AddAddress_Response.png)

### Update Checkout Billing Address

Update an existing billing address with a **PUT** request to `/checkouts/{checkout_id}/billing-address/{address_id}`

```http showLineNumbers={false}
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/billing-address/5d51b12389ea8
```

**Body Example**

```json showLineNumbers={false}
{
  "email": "jenny@email.com",
  "phone": "5128675309"
}
```

![Example Response](/_fern-files/bigcommerce.docs.buildwithfern.com/b8d6f291b5ea56d103117df48ae212650a37b318f2d6de1e761b18de2ee341f5/assets/learn/checkout-orders-rest-api/UpdateBilling_Response.png)

## Add Consignment to Checkout

A consignment is a list of physical products that will travel together to the purchaser, and it specifies how those items can and will ship. It is an object that includes at least one product line item and one shipping address.

Add a new Consignment to Checkout by sending a **POST** request to `/checkouts/{checkout_id}/consignments`

```http showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/consignments
```

**Required Query:**

* `consignments.available_shipping_options`

**Required Fields:**

* `shipping_address`
* `line_items`

### Update Checkout Consignment

```http showLineNumbers={false}
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/consignments/{consignment_id}
```

Updates an existing consignment. Shipping address, line item IDs or the shipping option ID can be updated using this endpoint.

Required Fields:

* `shipping_option_id`

There are two steps to add a new shipping address and shipping options with line items.

1. Add a new Consignment to Checkout
   * Send a **POST** to Consignments with each shipping address and line items IDs. Each address can have its own line item IDs.
   * As part of the request URL make sure to add `include=consignments.available_shipping_options` to return the available shipping options based on line items and shipping locations. This will return `available_shipping_options` in the response.
2. Update the Consignment with Shipping Options
   * Update each Consignment `shipping_option_id` (shipping address and line items) with the `available_shipping_option` id from Step One.

![Example Response](/_fern-files/bigcommerce.docs.buildwithfern.com/4513dfea019eeeb2a32fa77a766eec8fc4e5f8a5a7b2f66627dff926e73a2ccd/assets/learn/checkout-orders-rest-api/updateConsignment_Response.png)

### Delete Checkout Consignment

```http showLineNumbers={false}
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/consignments/{consignment_id}
```

Removes an existing consignment from checkout.

## Add a Coupon to Checkout

Add a Coupon Code to a checkout with a **POST** request to `/checkouts/{checkout_id}/coupons`

Required Fields

* `coupon_code`

### Delete a Checkout Coupon

```http showLineNumbers={false}
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/coupons/{coupon_code}
```

Deletes a Coupon Code from Checkout.

### Add Discount to Checkout

To add a discount to an existing checkout, send a **POST** request to `/checkouts/{checkout_id}/coupons`

In the request body, you need to include the following information:

* `couponCode`: The code of the discount that you want to add.
* `couponType`: The type of discount that you want to add. Valid values are percentage\_discount and amount\_discount.
* `discountedAmount`: The amount of the discount. For a percentage discount, this is the percentage of the checkout total that will be discounted. For an amount discount, this is the amount of money that will be discounted.

For example, the following request would add a 10% discount to a checkout with the ID 12345:

```http showLineNumbers={false}
POST https://api.bigcommerce.com/stores/mystore/v3/checkouts/12345/coupons
Content-Type: application/json

{
  "couponCode": "10OFF",
  "couponType": "percentage_discount",
  "discounted_Amount": 10
}
```

Here are some additional things to keep in mind about adding discounts to checkouts:

* You can only add one discount to a checkout at a time.
* If you add a discount that conflicts with an existing discount, the most recently added discount will take precedence.
* Discounts are applied to the checkout total before taxes and shipping costs.

![Image](/_fern-files/bigcommerce.docs.buildwithfern.com/560bf128567f6ffa2b11d53b3f5ac9157107d108add581702e33ac953ac920a8/assets/learn/checkout-orders-rest-api/createOrder.png)

## Create an Order

Create an order by sending a **POST** request to  `/checkouts/{checkout_id}/orders`

```http showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{checkout_id}/orders
```

* Orders created will be set to incomplete order status
* You can create as many orders from the same order (cart) as you want
* Order duplication creates the same order with a new order number and an incomplete status
* Once the order is paid, then the cart is deleted. Cart deletion occurs if you are using BigCommerce to accept payments on orders

## Resources:

* [Carts API](/developer/api-reference/rest/admin/management/carts)
* [Checkout V3 API](/developer/api-reference/rest/admin/management/checkouts)
* [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes)
* [Tools and Resources](/developer/docs/overview/tools-and-sdks)