4.0 Manage checkout as a shopper

The Checkout SDK and Server-to-Server (S2S) Checkout V3 APIs 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 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 (opens in a new tab) 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.

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));

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

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

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
    }
  ]
}

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

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
    }
  ]
}

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

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
      }
    ]
  }
]

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.

{
  "status": 422,
  "title": "Pickup method is limited to 1 consignment.",
  "type": "https://developer.bigcommerce.com/api-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 endpoint.

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
    }
  ]
}

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:

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"
}

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.

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
    }
  ]
}

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

To finalize an order, send a request to the Finalize an order endpoint.

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

The order ID is 126.