Checkout Consignment API

This article discusses how to create and update a consignment.

Overview

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 address. A checkout containing one or more physical products will always have at least one consignment associated with it. An order that ships to multiple addresses will have at least one consignment per address. It is also possible to create multiple consignments for the same address.

The REST Storefront, REST Management, and GraphQL Storefront APIs provide methods for creating checkout consignments, which are shipments waiting to happen. A newly created consignment returns a list of fulfillment options available based on the destination address. These APIs also provide methods for updating this consignment to change the destination, add or remove items, and select a fulfillment option. This article focuses on the REST Storefront API. For more about managing consignments with GraphQL, see GraphQL Storefront API: Carts and Checkout.

A checkout containing physical products is not eligible to become an order until each of its consignments contains a selected_shipping_option.

Authentication

To learn more about authentication, see Authentication and Example Requests.

REST Management

Use one of the following OAuth scopes for the REST Management API's Checkout endpoints.

UI Name	Permission	Parameter
Checkouts	read-only	`store_checkout_read_only`
Checkouts	modify	`store_checkout`

REST Storefront

The REST Storefront API allows developers to manage a shopper’s cart, checkout, and order data using client-side JavaScript on BigCommerce Stencil-powered storefronts. REST Storefront Checkout API requests do not require OAuth scopes.

GraphQL Storefront

See GraphQL Storefront API: Carts and Checkout.

For limits on the number of line items in a consignment, see the Create a consignment endpoint documentation. The REST Management API responds quickly when the checkout contains one consignment. Each additional consignment increases the amount of time the API takes to finish creating a checkout. The example API calls in this article use the REST Management API's Checkout endpoints.

Creating a consignment

Prerequisites: Prior to working with consignments, your code will need to create or retrieve a cart or checkout. The cart ID and checkout ID are the same.

The Create a consignment endpoint requires a checkoutID. You can create consignments associated with a cart before it becomes a checkout. This endpoint supports creating multiple consignments in a single call.

The following is an example POST request for creating two consignments. Append include=consignment.available_shipping_options to the endpoint so that you will have the information to select one of them in the next step.

Example request: Create a consignment

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}}
 
  [
    {
      "address": {
        "email": "jane2@example.com",
        "country_code": "US",
        "first_name": "BigCommerce",
        "last_name": "Cart/Checkout",
        "address1": "123 Main Street",
        "city": "Austin",
        "state_or_province": "Texas",
        "state_or_province_code": "TX",
        "postal_code": "78751",
        "phone": "688546",
        "custom_fields": [
          {
            "field_id": "field_25",
            "field_value": "Great!"
          }
        ]
      },
      "line_items": [
        {
          "item_id": "00a8e1c3-996f-4786-96ca-2a8a887b6648",
          "quantity": 1
        }
      ]
    },
    {
      "address": {
        "email": "testing@example.com",
        "country_code": "US",
        "first_name": "Testing",
        "last_name": "BigCommerce",
        "company": "BigCommerce",
        "address1": "111 Main Street",
        "address2": "#1324",
        "city": "Austin",
        "state_or_province": "Texas",
        "state_or_province_code": "TX",
        "postal_code": "78751",
        "phone": "+5185158x1{1-5}",
        "custom_fields": [
          {
            "field_id": "field_25",
            "field_value": "You're Welcome"
          }
        ]
      },
      "line_items": [
        {
          "item_id": "00a8e1c3-996f-4786-96ca-2a8a887b6648",
          "quantity": 1
        }
      ]
    }
  ]

Copy and paste your store_hash,access_token, and checkoutId into the form, then click Send.

Updating a consignment

The Update a consignment endpoint requires the checkoutId and the consignmentId. You can find the consignment ID in the response from the preceding API call. The checkout ID is the same as the cart ID.

There are two distinct kinds of consignment updates. The first selects a fulfillment option. The second can update the recipient's address and adjust the list of included line items.

⚠️

You must choose one type of consignment update because changing the address and weight can change available fulfillment options. You can't do both in the same API call.

The following is an example request that updates a consignment’s shipping_option_id with one of the available_shipping_options.id returned in the response from the Create a consignment endpoint.

Example request: Update a 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": "9241669174884c2f2e83b3adabf03f83"
}

Copy and paste your store_hash,access_token, checkoutId, consignmentId and query parameter (consignments.available_shipping_options) into the form, then click Send.