Docs
Management API
Checkouts
Checkout Consignments

Checkout Consignments

Add Consignment to Checkout

POST /checkouts/{checkoutId}/consignments

Request

Adds a new consignment to a checkout.

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

For more information about working with consignments, see Checkout consignment.

Though the only required address properties to create a consignment are email and country_code, to successfully create an order the address requires the following properties:

  • first_name
  • last_name
  • address1
  • city
  • country
  • email
  • country_code

Depending on the country, the following address properties may also be required:

  • postal_code
  • state_or_province

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • checkoutId in path - string
    required
    ID of the checkout; the same as the cart ID.
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
  • include in query - string
    Include the shipping options available to this checkout.

    Allowed: consignments.available_shipping_options

Body

array | application/json

  • address    object

  • line_items    array[object]

  • pickup_option    object

    Assigns a pickup consignment. Note: You cannot assign a shipping method with a pickup consignment.

  • version    integer

    The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.
    Example: 1

Shipping Consignment

[
{
"address": {
"first_name": "Jane",
"last_name": "Doe",
"email": "Jane.Doe@email.com",
"company": "BigCommerce",
"address1": "100 Main Street",
"address2": "string",
"city": "Austin",
"state_or_province": "Texas",
"state_or_province_code": "string",
"country_code": "US",
"postal_code": "78701",
"phone": "555-555-5555",
"custom_fields": [
{
"field_id": "string",
"field_value": "string"
}
]
},
"line_items": [
{
"item_id": "118f8774-387c-485e-a095-6ef76d5f1bbd",
"quantity": 1

Pickup Consignment

[
{
"line_items": [
{
"item_id": "118f8774-387c-485e-a095-6ef76d5f1bbd",
"quantity": 1
}
],
"pickup_option": {
"pickup_method_id": 1
},
"version": 1
}
]

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"cart": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"customer_id": 1,
"email": "user@example.com",
"currency": {
"code": "USD"
},
"base_amount": 5,
"channel_id": 0,
"discount_amount": 0.5,
"cart_amount_inc_tax": 4.14,
"cart_amount_ex_tax": 3.6,
"coupons": [
{
"code": "SHOPNOW",
"id": 1,
"coupon_type": "percentage_discount",
"discounted_amount": 0.9,
"display_name": "20% Off"
}
],
"discounts": [
{
"id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d",

Update Checkout Consignment

PUT /checkouts/{checkoutId}/consignments/{consignmentId}

Request

Updates an existing consignment. The address, line item IDs, and shipping option ID can be updated using this endpoint.

Use a separate PUT request to update the shipping option IDs if you also want to update the address and line item IDs.

To add new shipping options, complete the following steps:

  • Use the Add Consignment to Checkout endpoint to add a new [consignment] to a checkout.
  • Assign a shipping option to the new consignment by sending a PUT request to update the consignment's shipping_option_id with a returned value from data.consignments[N].available_shipping_option[N].id obtained in the Add Consignment to Checkout endpoint.

To update an existing address and line item IDs, assign a new address and line item IDs by sending a PUT request.

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

  1. Assign a shipping option to the new consignment by sending a PUT request to update the consignment's shipping_option_id with a returned value from data.consignments[N].available_shipping_option[N].id obtained in Step One.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • checkoutId in path - string
    required
    ID of the checkout; the same as the cart ID.
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • consignmentId in path - string
    required
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
  • include in query - string
    Include the shipping options available to this checkout.

    Allowed: consignments.available_shipping_options

Body

object | application/json
One or more of these three fields are mandatory. address and line_items can be updated in one request. shipping_option_id has to be updated in a separate request because changing the address or line items can invalidate the previously available shipping options.

  • address    object

  • line_items    array[object]

  • shipping_option_id    string

  • pickup_option    object

  • custom_shipping    object

  • version    integer

    The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.
    Example: 1

example

{
"address": {
"first_name": "string",
"last_name": "string",
"email": "string",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state_or_province": "string",
"state_or_province_code": "string",
"country_code": "string",
"postal_code": "string",
"phone": "string",
"custom_fields": [
{
"field_id": "string",
"field_value": "string"
}
]
},
"line_items": [
{
"item_id": "string",
"quantity": 0
}
],
"shipping_option_id": "string",
"pickup_option": {
"pickup_method_id": 1

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"cart": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"customer_id": 1,
"email": "user@example.com",
"currency": {
"code": "USD"
},
"base_amount": 5,
"channel_id": 0,
"discount_amount": 0.5,
"cart_amount_inc_tax": 4.14,
"cart_amount_ex_tax": 3.6,
"coupons": [
{
"code": "SHOPNOW",
"id": 1,
"coupon_type": "percentage_discount",
"discounted_amount": 0.9,
"display_name": "20% Off"
}
],
"discounts": [
{
"id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d",

Delete Checkout Consignment

DELETE /checkouts/{checkoutId}/consignments/{consignmentId}

Request

Removes an existing consignment from a checkout.

To prevent lost updates due to concurrent requests overriding changes made by others, it is recommended to enable optimistic concurrency control by including the version field in the request payload. If the provided version does not match the version on the server, a conflict error will be returned, which the client can handle accordingly.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • checkoutId in path - string
    required
    ID of the checkout; the same as the cart ID.
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • consignmentId in path - string
    required

Body

object | application/json

  • version    integer

    The cart version that you expect to apply the updates. If the provided version doesn't match the current cart version, you will receive a conflict error. This field is optional; if not provided, optimistic concurrency control will not apply.
    Example: 1

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/checkouts/[checkoutId]/consignments/[consignmentId]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"cart": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"customer_id": 1,
"email": "user@example.com",
"currency": {
"code": "USD"
},
"base_amount": 5,
"channel_id": 0,
"discount_amount": 0.5,
"cart_amount_inc_tax": 4.14,
"cart_amount_ex_tax": 3.6,
"coupons": [
{
"code": "SHOPNOW",
"id": 1,
"coupon_type": "percentage_discount",
"discounted_amount": 0.9,
"display_name": "20% Off"
}
],
"discounts": [
{
"id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d",
Did you find what you were looking for?
Update Checkout Billing AddressAdd Consignment to Checkout