Thanks for being patient while we implement your feedback to improve the developer experience.

Create a Consignment

POST /checkouts/{checkoutId}/consignments

Request

Adds a new Consignment to Checkout.

Perform the following two steps to define the fulfillment of the items in the cart.

For shipping consignments:

1. Add a new Consignment to Checkout.
    * Send a `POST` request to `/consignments` with each shipping address, line item IDs, and quantities. Each address can have its own line item IDs.
    * Provide a full valid customer address before placing the order. If provided, the order placement will succeed. 
    * As part of the request URL make sure to add `include=consignments.availableShippingOptions` to return the available shipping options based on the items, the address, and the shipping location. This will return `availableShippingOptions` in the response.

  * Required Fields:
    * `shipping_address` (deprecated) or `address`
    * `lineItems`
2. [Update the Consignment](/api-reference/storefront/checkouts/checkout-consignments/checkoutsconsignmentsbycheckoutidandconsignmentidput) with Shipping Options.

For pickup consignments:

1. Create a new consignment object. 
  - Send a `POST` request to `/consignments` with line item IDs and quantities.
  - Provide a `pickupMethodId`. This is the `id` of the Pickup Method provided in the response body of the Storefront Pickup Options API.
  - Required Fields:
      * `pickupOption`
      * `lineItems`

To learn more about creating a Checkout Consignment, see the Carts and Checkouts Tutorial.

Note

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • checkoutId in path - string - required
  • include in query with default of consignments.availableShippingOptions - string

Body

array | application/json

  • shippingAddress    object

  • address    object

  • lineItems    array[object]

  • shippingOptionId    string

  • pickupOption    object

example

{
  "shippingAddress": {},
  "address": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "stateOrProvince": "string",
    "stateOrProvinceCode": "string",
    "countryCode": "string",
    "postalCode": "string",
    "phone": "string",
    "customFields": [
      {
        "fieldId": "string",
        "fieldValue": "string"
      }
    ],
    "shouldSaveAddress": true
  },
  "lineItems": [
    {
      "itemId": "string",
      "quantity": 0
    }
  ],
  "shippingOptionId": "string",
  "pickupOption": {
    "pickupMethodId": 0
  }
}

Response

Body

object | application/json

  • id    string

  • cart    object

    A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • billingAddress    object

  • consignments    array[object]

  • coupons    array[object]

    Coupons applied at the checkout level.

  • orderId    string

  • shippingCostTotal    number

    Shipping cost before any discounts are applied.

  • giftWrappingCostTotal    number

    Gift wrapping cost for all items, including or excluding tax.

  • handlingCostTotal    number

    Handling cost for all consignments including or excluding tax.

  • taxTotal    number

  • taxes    array[object]

  • subtotal    number

    Subtotal of the checkout before applying item-level discounts. Tax inclusive based on the store settings.

  • grandTotal    number

    The total payable amount, before applying any store credit or gift certificate.

  • giftCertificates    array[array]

    Applied gift certificate (as a payment method).

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • customerMessage    string

    Shopperʼs message provided as details for the order to be created from this cart

  • outstandingBalance    number

    grandTotal subtract the store-credit amount

  • isStoreCreditApplied    boolean

    true value indicates StoreCredit has been applied.

example

{
  "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
  "cart": {
    "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
    "customerId": 18,
    "email": "dwaynecole@testing.com",
    "currency": {
      "name": "US Dollars",
      "code": "USD",
      "symbol": "$",
      "decimalPlaces": 2
    },
    "isTaxIncluded": true,
    "baseAmount": 7.95,
    "discountAmount": 0,
    "cartAmount": 7.95,
    "coupons": [],
    "discounts": [
      {
        "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
        "discountedAmount": 0
      }
    ],
    "lineItems": {
      "physicalItems": [
        {
          "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
          "parentId": {},
          "variantId": 345,
          "productId": 174,
          "sku": "",
          "name": "1L Le Parfait Jar",
          "url": "https://{store_domain}/all/1l-le-parfait-jar/",
          "quantity": 1,
          "brand": "OFS",
          "isTaxable": true,
          "imageUrl": "https://cdn11.bigcommerce.com/s-{store_hash}/products/174/images/425/leparfaitmedium3_1024x1024_1024x1024__37756__81924.1534344526.330.500.jpg?c=2",
          "discounts": [],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 7.95,
          "listPrice": 7.95,
          "salePrice": 7.95,
          "extendedListPrice": 7.95,
          "extendedSalePrice": 7.95,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        }
      ],
      "digitalItems": [],
      "giftCertificates": [],
      "customItems": []
    },
    "createdTime": "2019-01-10T17:18:00+00:00",
    "updatedTime": "2019-01-10T17:19:47+00:00"
  },
  "billingAddress": {
    "id": "5c377ead301c2",
    "firstName": "Dwayne",
    "lastName": "Cole",
    "email": "dwaynecole@testing.com",
    "company": "",
    "address1": "Mauna Kea Access Rd",
    "address2": "",
    "city": "Hilo",
    "stateOrProvince": "Hawaii",
    "stateOrProvinceCode": "HI",
    "country": "United States",
    "countryCode": "US",
    "postalCode": "96720",
    "phone": "8081234567",
    "customFields": []
  },
  "consignments": [
    {
      "id": "5c377ead30ac1",
      "shippingCost": 8,
      "handlingCost": 0,
      "couponDiscounts": [],
      "discounts": [],
      "lineItemIds": [
        "243c9ca2-22b4-417a-8b09-b3fc05778b52"
      ],
      "selectedShippingOption": {
        "id": "d09e05c0-3788-44df-a1bb-b6d3afdf6841",
        "type": "shipping_byweight",
        "description": "Ship by Weight",
        "imageUrl": "",
        "cost": 8,
        "transitTime": ""
      },
      "address": {
        "firstName": "Dwayne",
        "lastName": "Cole",
        "email": "dwaynecole@example.com",
        "company": "",
        "address1": "Mauna Kea Access Rd",
        "address2": "",
        "city": "Hilo",
        "stateOrProvince": "Hawaii",
        "stateOrProvinceCode": "HI",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "96720",
        "phone": "8081234567",
        "customFields": [],
        "shouldSaveAddress": true
      }
    }
  ],
  "orderId": null,
  "shippingCostTotal": 8,
  "shippingCostBeforeDiscount": 8,
  "handlingCostTotal": 0,
  "taxTotal": 1.22,
  "coupons": [],
  "taxes": [
    {
      "name": "Tax",
      "amount": 1.22
    }
  ],
  "subtotal": 7.95,
  "grandTotal": 15.95,
  "giftCertificates": [],
  "createdTime": "2019-01-10T17:18:00+00:00",
  "updatedTime": "2019-01-10T17:19:47+00:00",
  "customerMessage": ""
}

Update a Consignment

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

Request

Updates an existing consignment. An update is either one of the following:

  1. Updates the consignment address and/or line items.
  2. Selects a specific fulfillment option.

Update the consignment address and line items

For this type of update, the payload is the same as when creating a new consignment. Update each Consignment shippingOptionId (shipping address and line items) with the availableShippingOption > id from the POST /consignment response.

Note: Updating a consignment could invalidate the value for selectedShippingOption and selectedPickupOption.

Select a specific fulfillment option

Before placing an order, each consignment must have a selectedShippingOption or a selectedPickupOption.

If the consignment already has a pick-up option selected and a shipping option is provided, the pick-up option will be deselected and the shipping option will be selected instead (and vice versa). The PUT request will fail if it contains a shipping option ID and a pickup option ID.

Required Fields:

  • shippingOptionId or pickupOptionId
  • lineItems

To learn more about creating a Checkout Consignment see Checkout Consignment API.

Note

  • You cannot pass both an address and a shippingOptionId because the shipping option may not be available for the new address
  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • checkoutId in path - string - required
  • consignmentId in path - string - required
  • include in query with default of consignments.availableShippingOptions, consignments.availablePickupOptions - string

Body

object | application/json

One or more of these three fields is mandatory. You can update address and line items in one request. You have to update shipping option ID or pickup option ID in a separate request since changing the address or line items can invalidate the previously available shipping options.

  • shippingAddress    object

  • address    object

  • lineItems    array[object]

  • shippingOptionId    string

  • pickupOption    object

example

{
  "shippingAddress": {},
  "address": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "company": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "stateOrProvince": "string",
    "stateOrProvinceCode": "string",
    "countryCode": "string",
    "postalCode": "string",
    "phone": "string",
    "customFields": [
      {
        "fieldId": "string",
        "fieldValue": "string"
      }
    ],
    "shouldSaveAddress": true
  },
  "lineItems": [
    {
      "itemId": "string",
      "quantity": 0
    }
  ],
  "shippingOptionId": "string",
  "pickupOption": {
    "pickupMethodId": 0
  }
}

Response

Body

object | application/json

  • id    string

  • cart    object

    A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • billingAddress    object

  • consignments    array[object]

  • coupons    array[object]

    Coupons applied at the checkout level.

  • orderId    string

  • shippingCostTotal    number

    Shipping cost before any discounts are applied.

  • giftWrappingCostTotal    number

    Gift wrapping cost for all items, including or excluding tax.

  • handlingCostTotal    number

    Handling cost for all consignments including or excluding tax.

  • taxTotal    number

  • taxes    array[object]

  • subtotal    number

    Subtotal of the checkout before applying item-level discounts. Tax inclusive based on the store settings.

  • grandTotal    number

    The total payable amount, before applying any store credit or gift certificate.

  • giftCertificates    array[array]

    Applied gift certificate (as a payment method).

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • customerMessage    string

    Shopperʼs message provided as details for the order to be created from this cart

  • outstandingBalance    number

    grandTotal subtract the store-credit amount

  • isStoreCreditApplied    boolean

    true value indicates StoreCredit has been applied.

example

{
  "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
  "cart": {
    "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
    "customerId": 18,
    "email": "dwaynecole@testing.com",
    "currency": {
      "name": "US Dollars",
      "code": "USD",
      "symbol": "$",
      "decimalPlaces": 2
    },
    "isTaxIncluded": true,
    "baseAmount": 7.95,
    "discountAmount": 0,
    "cartAmount": 7.95,
    "coupons": [],
    "discounts": [
      {
        "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
        "discountedAmount": 0
      }
    ],
    "lineItems": {
      "physicalItems": [
        {
          "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
          "parentId": {},
          "variantId": 345,
          "productId": 174,
          "sku": "",
          "name": "1L Le Parfait Jar",
          "url": "https://{store_domain}/all/1l-le-parfait-jar/",
          "quantity": 1,
          "brand": "OFS",
          "isTaxable": true,
          "imageUrl": "https://cdn11.bigcommerce.com/s-{store_hash}/products/174/images/425/leparfaitmedium3_1024x1024_1024x1024__37756__81924.1534344526.330.500.jpg?c=2",
          "discounts": [],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 7.95,
          "listPrice": 7.95,
          "salePrice": 7.95,
          "extendedListPrice": 7.95,
          "extendedSalePrice": 7.95,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        }
      ],
      "digitalItems": [],
      "giftCertificates": [],
      "customItems": []
    },
    "createdTime": "2019-01-10T17:18:00+00:00",
    "updatedTime": "2019-01-10T17:19:47+00:00"
  },
  "billingAddress": {
    "id": "5c377ead301c2",
    "firstName": "Dwayne",
    "lastName": "Cole",
    "email": "dwaynecole@testing.com",
    "company": "",
    "address1": "Mauna Kea Access Rd",
    "address2": "",
    "city": "Hilo",
    "stateOrProvince": "Hawaii",
    "stateOrProvinceCode": "HI",
    "country": "United States",
    "countryCode": "US",
    "postalCode": "96720",
    "phone": "8081234567",
    "customFields": []
  },
  "consignments": [
    {
      "id": "5c377ead30ac1",
      "shippingCost": 8,
      "handlingCost": 0,
      "couponDiscounts": [],
      "discounts": [],
      "lineItemIds": [
        "243c9ca2-22b4-417a-8b09-b3fc05778b52"
      ],
      "selectedShippingOption": {
        "id": "d09e05c0-3788-44df-a1bb-b6d3afdf6841",
        "type": "shipping_byweight",
        "description": "Ship by Weight",
        "imageUrl": "",
        "cost": 8,
        "transitTime": ""
      },
      "address": {
        "firstName": "Dwayne",
        "lastName": "Cole",
        "email": "dwaynecole@testing.com",
        "company": "",
        "address1": "Mauna Kea Access Rd",
        "address2": "",
        "city": "Hilo",
        "stateOrProvince": "Hawaii",
        "stateOrProvinceCode": "HI",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "96720",
        "phone": "8081234567",
        "customFields": [],
        "shouldSaveAddress": true
      }
    }
  ],
  "orderId": null,
  "shippingCostTotal": 8,
  "shippingCostBeforeDiscount": 8,
  "handlingCostTotal": 0,
  "taxTotal": 1.22,
  "coupons": [],
  "taxes": [
    {
      "name": "Tax",
      "amount": 1.22
    }
  ],
  "subtotal": 7.95,
  "grandTotal": 15.95,
  "giftCertificates": [],
  "createdTime": "2019-01-10T17:18:00+00:00",
  "updatedTime": "2019-01-10T17:19:47+00:00",
  "customerMessage": ""
}

Delete a Consignment

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

Request

Removes an existing Consignment from Checkout.

Note

  • Substitute your storefront domain for yourstore.example.com.
  • The Send a Test Request feature is not currently supported for this endpoint.

Parameters

  • store_domain in path - string
  • checkoutId in path - string - required
  • consignmentId in path - string - required

example

const options = {method: 'DELETE', headers: {'Content-Type': 'application/json'}};

fetch('https://yourstore.example.com/api/storefront/checkouts/[checkoutId]/consignments/[consignmentId]', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Response

Body

object | application/json

  • id    string

  • cart    object

    A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

  • billingAddress    object

  • consignments    array[object]

  • coupons    array[object]

    Coupons applied at the checkout level.

  • orderId    string

  • shippingCostTotal    number

    Shipping cost before any discounts are applied.

  • giftWrappingCostTotal    number

    Gift wrapping cost for all items, including or excluding tax.

  • handlingCostTotal    number

    Handling cost for all consignments including or excluding tax.

  • taxTotal    number

  • taxes    array[object]

  • subtotal    number

    Subtotal of the checkout before applying item-level discounts. Tax inclusive based on the store settings.

  • grandTotal    number

    The total payable amount, before applying any store credit or gift certificate.

  • giftCertificates    array[array]

    Applied gift certificate (as a payment method).

  • createdTime    string

    Time when the cart was created.

  • updatedTime    string

    Time when the cart was last updated.

  • customerMessage    string

    Shopperʼs message provided as details for the order to be created from this cart

  • outstandingBalance    number

    grandTotal subtract the store-credit amount

  • isStoreCreditApplied    boolean

    true value indicates StoreCredit has been applied.

example

{
  "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
  "cart": {
    "id": "29eb9b44-8f33-4e4a-9429-d0e8e24641ed",
    "customerId": 18,
    "email": "dwaynecole@testing.com",
    "currency": {
      "name": "US Dollars",
      "code": "USD",
      "symbol": "$",
      "decimalPlaces": 2
    },
    "isTaxIncluded": true,
    "baseAmount": 7.95,
    "discountAmount": 0,
    "cartAmount": 7.95,
    "coupons": [],
    "discounts": [
      {
        "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
        "discountedAmount": 0
      }
    ],
    "lineItems": {
      "physicalItems": [
        {
          "id": "243c9ca2-22b4-417a-8b09-b3fc05778b52",
          "parentId": {},
          "variantId": 345,
          "productId": 174,
          "sku": "",
          "name": "1L Le Parfait Jar",
          "url": "https://{store_domain}/all/1l-le-parfait-jar/",
          "quantity": 1,
          "brand": "OFS",
          "isTaxable": true,
          "imageUrl": "https://cdn11.bigcommerce.com/s-{store_hash}/products/174/images/425/leparfaitmedium3_1024x1024_1024x1024__37756__81924.1534344526.330.500.jpg?c=2",
          "discounts": [],
          "discountAmount": 0,
          "couponAmount": 0,
          "originalPrice": 7.95,
          "listPrice": 7.95,
          "salePrice": 7.95,
          "extendedListPrice": 7.95,
          "extendedSalePrice": 7.95,
          "isShippingRequired": true,
          "giftWrapping": {},
          "addedByPromotion": false
        }
      ],
      "digitalItems": [],
      "giftCertificates": [],
      "customItems": []
    },
    "createdTime": "2019-01-10T17:18:00+00:00",
    "updatedTime": "2019-01-10T17:19:47+00:00"
  },
  "billingAddress": {
    "id": "5c377ead301c2",
    "firstName": "Dwayne",
    "lastName": "Cole",
    "email": "dwaynecole@testing.com",
    "company": "",
    "address1": "Mauna Kea Access Rd",
    "address2": "",
    "city": "Hilo",
    "stateOrProvince": "Hawaii",
    "stateOrProvinceCode": "HI",
    "country": "United States",
    "countryCode": "US",
    "postalCode": "96720",
    "phone": "8081234567",
    "customFields": []
  },
  "consignments": [
    {
      "id": "5c377ead30ac1",
      "shippingCost": 8,
      "handlingCost": 0,
      "couponDiscounts": [],
      "discounts": [],
      "lineItemIds": [
        "243c9ca2-22b4-417a-8b09-b3fc05778b52"
      ],
      "selectedShippingOption": {
        "id": "d09e05c0-3788-44df-a1bb-b6d3afdf6841",
        "type": "shipping_byweight",
        "description": "Ship by Weight",
        "imageUrl": "",
        "cost": 8,
        "transitTime": ""
      },
      "address": {
        "firstName": "Dwayne",
        "lastName": "Cole",
        "email": "dwaynecole@testing.com",
        "company": "",
        "address1": "Mauna Kea Access Rd",
        "address2": "",
        "city": "Hilo",
        "stateOrProvince": "Hawaii",
        "stateOrProvinceCode": "HI",
        "country": "United States",
        "countryCode": "US",
        "postalCode": "96720",
        "phone": "8081234567",
        "customFields": []
      }
    }
  ],
  "orderId": null,
  "shippingCostTotal": 8,
  "shippingCostBeforeDiscount": 8,
  "handlingCostTotal": 0,
  "taxTotal": 1.22,
  "coupons": [],
  "taxes": [
    {
      "name": "Tax",
      "amount": 1.22
    }
  ],
  "subtotal": 7.95,
  "grandTotal": 15.95,
  "giftCertificates": [],
  "createdTime": "2019-01-10T17:18:00+00:00",
  "updatedTime": "2019-01-10T17:19:47+00:00",
  "customerMessage": ""
}