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

## 4.0 Manage checkout as a shopper

The [Checkout SDK](/developer/docs/admin/checkout-and-cart/checkout-sdk) and [Server-to-Server (S2S) Checkout V3 APIs](/developer/api-reference/rest/admin/management/checkouts) have been updated to support *Buy Online, Pick up in Store* experiences.

When building a *Buy Online, Pick up in Store* solution, you can allow shoppers to find available pickup options and create checkout consignments that are fulfilled by a pickup method.

As a developer, you may wonder which to choose and when to use the SDK vs the API. If you’re developing:

* A native storefront and custom checkout experience, use the Checkout SDK
* An end-to-end headless experience, use the S2S Checkout APIs

If you’re dependent on webhook events, all [existing Cart webhooks](/developer/docs/integrations/webhooks/event-reference) have been updated to support *Buy Online, Pick up in Store*.

### 4.1 Native storefront & custom checkout experience using Checkout SDK

To support *Buy Online, Pick up in Store*, we would be adding a `loadPickupOptions` method to the [CheckoutService](https://github.com/bigcommerce/checkout-sdk-js/blob/master/docs/classes/CheckoutService.md) class, allowing you to load pickup options to your storefront checkout. In order to fetch pickup options using the Checkout SDK, you will need to be on SDK version 1.224.0 or above. This applies to existing custom checkouts, as well as new custom checkouts.

**`Example JavaScript Code`**

```js title="Example JavaScript Code" showLineNumbers={false}
const consignmentId = '123';
const searchArea = {
  radius: {
    value: 1.4,
    unit: 'KM' // Another unit allowed here is 'MI'
  },
  coordinates: {
    latitude: 1.4,
    longitude: 0
  }
};

const query: PickupOptionRequestBody = { consignmentId, searchArea };

const state = await checkoutService.loadPickupOptions(query: PickupOptionRequestBody);

/*
* Pickup options are once fetched and then cached against the consignmentId and
* searchArea. So unless you change either of the parameters the options there won’t
* be an API call to the server and memoized options will be returned to checkout App
*/

// To log and see pickup options
console.log(state.data.getPickupOptions(consignmentId, searchArea));
```

You can show pickup method options to customers on a storefront page, such as the Product Detail Page, before having a consignment. For more information, see [4.2.2 Find available pickup methods with stock available](#422-find-available-pickup-options-with-stock-available).

### 4.2 End-to-end headless experience (S2S APIs)

#### 4.2.1 Create a cart with a product in it

To create a cart, send a request to the [Create a cart](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) endpoint.

#### Request

**`Example request: Create a cart`**

```http title="Example request: Create a cart"
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/carts
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

{
  "line_items": [
    {
      "quantity": 1,
      "product_id": 97
    }
  ]
}
```

#### Response

**`Example response: Create a cart`**

```json title="Example response: Create a cart"
{
  "data": {
    "id": "76f1bfe4-dbbe-4018-8ee6-2e3c36bf1518",
    …
    "line_items": {
      "physical_items": [
        {
          "id": "67642f07-49d1-4501-8b7d-2e589aec34b8",
          …
        }
      ],
      "digital_items": [],
      "gift_certificates": [],
      "custom_items": []
    },
    …
  },
  "meta": {}
}
```

For a successfully-created cart, the response will have:

* The newly-created cart ID. In this example, the cart ID is `76f1bfe4-dbbe-4018-8ee6-2e3c36bf1518`.
* The physical product ID. In this example, the cart ID is `67642f07-49d1-4501-8b7d-2e589aec34b8`.

Cart ID is the same as Checkout ID and both represent the same identifier for a cart depending on which API is being consumed: the Cart API uses cart ID and the Checkout API uses Checkout ID.

#### 4.2.2 Find available pickup options with stock available

To find available pickup options, send a request to the [Find available pickup options](/developer/api-reference/rest/admin/management/pickup/pickup-options/post-pickup-options) endpoint.

#### Request

**`Example request: Find available pickup options`**

```http title="Example request: Find available pickup options"
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/pickup/options
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

{
  "search_area": {
    "coordinates": {
      "latitude": 32.8058616,
      "longitude": -98.0105544
    },
    "radius": {
      "value": 25,
      "unit": "MI"
    }
  },
  "items": [
    {
      "variant_id": 1,
      "quantity": 1
    }
  ]
}
```

#### Response

**`Example response: Find available pickup options`**

```json title="Example response: Find available pickup options"
{
  "results": [
    {
      "pickup_options": [
        {
          "pickup_method": {
            "id": 1,
            "location_id": 1,
            "display_name": "Office Pickup",
            "collection_instructions": "Bring your ID",
            "collection_time_description": "Collect during our opening hours of 0900 - 1700"
          },
          "available_items": [
            {
              "variant_id": 1,
              "quantity": 1
            }
          ]
        }
      ]
    }
  ]
}
```

#### 4.2.3 Create the pickup consignment for the checkout

To create the pickup consignment for the checkout, send a request to the [Add consignment to checkout](/developer/api-reference/rest/admin/management/checkouts/consignments/add-checkout-consignment) endpoint.

#### Request

**`Example request: Add consignment to checkout`**

```http title="Example request: Add consignment to checkout"
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkout_id}}/consignments
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

[
  {
    "pickup_option": {
      "pickup_method_id": 2
    },
    "line_items": [
      {
        "item_id": "67642f07-49d1-4501-8b7d-2e589aec34b8",
        "quantity": 1
      }
    ]
  }
]
```

#### Response

**`Example response: Add consignment to checkout`**

```json title="Example response: Add consignment to checkout"
{
  "data": {
    ...
    "consignments": [
      {
        "id": "6218019d81754",
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "coupon_discounts": [],
        "discounts": [],
        "line_item_ids": [
          "67642f07-49d1-4501-8b7d-2e589aec34b8"
        ],
        "selected_pickup_option": {
          "pickup_method_id": 2
        }
        ...
      }
    ]
    ...
  }
}
```

From the response we can see the consignment object now has a `selected_pickup_option` set with the `pickup_method_id` that you requested.

Currently, *Buy Online, Pick up in Store* only supports 1 consignment of type Pickup. If you attempt to mix pickup and shipping consignments or create multiple pickup consignments, you will receive an error message.

**`Example error response`**

```json title="Example error response" showLineNumbers={false}
{
  "status": 422,
  "title": "Pickup method is limited to 1 consignment.",
  "type": "/developer/docs/getting-started/api-status-codes"
}
```

If you have a change of mind, and you want to change it from pickup to be shipped, then you will need to update the consignment. To update a consignment, send a request to the [Update checkout consignment](/developer/api-reference/rest/admin/management/checkouts/consignments/update-checkout-consignment) endpoint.

#### Request

**`Example request: Update checkout consignment`**

```http title="Example request: Update checkout consignment"
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkout_id}}/consignments/{{consignment_id}}?include=consignments.available_shipping_options
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

{
  "shipping_address": {
    "first_name": "abc1",
    "last_name": "abc1",
    "company": "a",
    "email": "abc1@bigcommerce.com",
    "phone": "0410123456",
    "address1": "2808 Skyway Cir",
    "address2": "",
    "city": "Austin",
    "country_code": "US",
    "state_or_province": "",
    "state_or_province_code": "TX",
    "postal_code": "78704",
    "custom_fields": []
  },
  "line_items": [
    {
      "item_id": "67642f07-49d1-4501-8b7d-2e589aec34b8",
      "quantity": 1
    }
  ]
}
```

#### Response

**`Example response: Update checkout consignment`**

```json title="Example response: Update checkout consignment"
{
  "data": {
    ...
    "consignments": [
      {
        "id": "6218019d81754",
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "coupon_discounts": [],
        "discounts": [],
        "line_item_ids": [
          "67642f07-49d1-4501-8b7d-2e589aec34b8"
        ],
        "shipping_address": {
          "first_name": "abc1",
          "last_name": "abc1",
          "email": "abc1@bigcommerce.com",
          "company": "a",
          "address1": "2808 Skyway Cir",
          "address2": "",
          "city": "Austin",
          "state_or_province": "Texas",
          "state_or_province_code": "TX",
          "country": "United States",
          "country_code": "US",
          "postal_code": "78704",
          "phone": "0410123456",
          "custom_fields": []
        },
        "available_shipping_options": [
          {
            "id": "4dcbf24f457dd67d5f89bcf374e0bc9b",
            "type": "freeshipping",
            "description": "Free Shipping",
            "image_url": "",
            "cost": 0,
            "transit_time": "",
            "additional_description": ""
          }
        ]
      }
    ]
    ...
  }
}
```

The `available_shipping_options` is returned if we add the `include=consignments.available_shipping_options` to the request.

This allows us to select a shipping option as described in the next request:

#### Request

**`Example request: Update checkout consignment`**

```http title="Example request: Update checkout consignment"
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkout_id}}/consignments/{{consignment_id}}
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

{
  "shipping_option_id" : "4dcbf24f457dd67d5f89bcf374e0bc9b"
}
```

#### Response

**`Example response: Update checkout consignment`**

```json title="Example response: Update checkout consignment"
{
  "data": {
    ...
    "consignments": [
      {
        "id": "6218019d81754",
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "coupon_discounts": [],
        "discounts": [],
        "line_item_ids": [
          "67642f07-49d1-4501-8b7d-2e589aec34b8"
        ],
        "selected_shipping_option": {
          "id": "4dcbf24f457dd67d5f89bcf374e0bc9b",
          "type": "freeshipping",
          "description": "Free Shipping",
          "image_url": "",
          "cost": 0,
          "transit_time": "",
          "additional_description": ""
        },
        "shipping_address": {
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "jane.doe@bigcommerce.com",
          "company": "Acme Inc",
          "address1": "2808 Skyway Cir",
          "address2": "",
          "city": "Austin",
          "state_or_province": "Texas",
          "state_or_province_code": "TX",
          "country": "United States",
          "country_code": "US",
          "postal_code": "78704",
          "phone": "0410123456",
          "custom_fields": []
        }
      }
    ]
    ...
  }
}
```

We can see in the response above the `selected_shipping_option` contains the shipping method selected, and there is no longer a pickup object.

#### 4.2.4 Update pickup consignment in the cart/checkout

If you want to update the consignment from shipping to pickup or select another pickup method, you can edit the consignment and send a new pickup method ID. The pickup method ID is retrieved from the api call to the pickup endpoint earlier.

#### Request

**`Example request: Update checkout consignment`**

```http title="Example request: Update checkout consignment"
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkout_id}}/consignments/{{consignment_id}}
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json

{
  "pickup_option": {
    "pickup_method_id": 1
  },
  "line_items": [
    {
      "item_id": "67642f07-49d1-4501-8b7d-2e589aec34b8",
      "quantity": 1
    }
  ]
}
```

#### Response

**`Example response: Update checkout consignment`**

```json title="Example response: Update checkout consignment"
{
  "data": {
    ...
    "consignments": [
      {
        "id": "6218019d81754",
        "shipping_cost_inc_tax": 0,
        "shipping_cost_ex_tax": 0,
        "handling_cost_inc_tax": 0,
        "handling_cost_ex_tax": 0,
        "coupon_discounts": [],
        "discounts": [],
        "line_item_ids": [
          "67642f07-49d1-4501-8b7d-2e589aec34b8"
        ],
        "selected_pickup_option": {
          "pickup_method_id": 1
        }...
      }
    ]
    ...
  }
}
```

#### 4.2.5 Finalize order creation (i.e. complete checkout by API)

To finalize an order, send a request to the [Finalize an order](/developer/api-reference/rest/admin/management/checkouts/orders/create-order) endpoint.

#### Request

**`Example request: Finalize an order`**

```http title="Example request: Finalize an order"
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/checkouts/{{checkout_id}}/orders
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
```

#### Response

**`Example response: Finalize an order`**

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

The order ID is 126.