> 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.

# 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 article in this guide](/developer/docs/storefront/headless/cart-and-checkout/carts).

### 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 request to the [Add Checkout Billing Address](/developer/api-reference/rest/admin/management/checkouts/billing-address/add-checkout-billing-address) endpoint. Your `checkoutId` will correspond with the cart ID returned by the [Create a Cart](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) endpoint. For an example request, see the [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/developer/docs/storefront/headless/end-to-end-guides/rest-management).

### 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 by adding and then updating a consignment. For an example request, see the [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/developer/docs/storefront/headless/end-to-end-guides/rest-management).

### 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 request to the [Create an Order](/developer/api-reference/rest/admin/management/checkouts/orders/create-order) endpoint. When a new order is created by API, the order status is set to incomplete.

#### Request

**`Example request: Create an order`**

```http title="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}}
```

#### Response

**`Example response: Create an order`**

```json title="Example response: Create an order"
{
  "data": {
    "id": 125
  },
  "meta": {}
}
```

## 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`**

```http title="Example request: Get accepted payment methods" showLineNumbers={false}
GET https://api.bigcommerce.com/stores/{store_hash}/v3/payments/methods
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
```

2. To process a payment for an order, you must make a call to the Payments API, which requires a Payment Access Token. To generate a payment access token, or *PAT*, send a request to the [Create Payment Access Token](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token) endpoint.

**`Example request: Create payment access token`**

```http title="Example request: Create payment access token" showLineNumbers={false}
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 the subsequent order payment call to the [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) endpoint.

3. Send a request to the [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) endpoint. The headers to process a payment are different from the headers you normally send with a BigCommerce API. The `Authorization` bearer token is the PAT ID returned by the Create Payment Access Token endpoint (step two). To learn more, see [Payments API: Stored Cards](/developer/docs/admin/checkout-and-cart/payments#stored-cards).

#### Request

**`Example request: Process payment`**

```http title="Example request: Process payment"
POST https://payments.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
  }
}
```

#### Response

**`Example response: Process payment`**

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

### 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 request to the [Create Payment Access Token](/developer/api-reference/rest/admin/payments/tokens/create-payment-access-token) endpoint to get the payment access token that must be passed using the `Authorization` header to process the payment.

2. Send a request to the [Process Payment](/developer/api-reference/rest/admin/payments/processing/payments-post) endpoint. The headers to process a payment are different from the headers you normally send with a BigCommerce API. The `Authorization` bearer token is the PAT ID returned by the Create Payment Access Token endpoint (step one). To learn more, see [Payments API: Credit Cards](/developer/docs/admin/checkout-and-cart/payments#credit-cards).

**`Example response: Process payment`**

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

A successful transaction will return a `success` status. The order status is then automatically changed to `Awaiting Fulfillment`. If you get a different response, see [Error Codes](/developer/docs/admin/checkout-and-cart/payments#error-codes) for troubleshooting.

## Next steps

* [Learn more about PCI compliance](/developer/docs/storefront/headless/pci-compliance)

## Resources

* [End-to-End Guide: Headless Checkout Flow with REST Management APIs](/developer/docs/storefront/headless/end-to-end-guides/rest-management)
* [Payments API Overview](/developer/docs/admin/checkout-and-cart/payments)