Add Consignment to Checkout
POST /stores/{store_hash}/v3/checkouts/{checkoutId}/consignments
Request
Adds a new consignment to a checkout.
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_namelast_nameaddress1citycountryemailcountry_code
Depending on the country, the following address properties may also be required:
postal_codestate_or_province
Authentication
- X-Auth-Token in header - required
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
Body
array | application/json
addressobject
line_itemsarray[object]
pickup_optionobject
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 } ], "pickup_option": { "pickup_method_id": 1 } }
Response
Body
object | application/json
dataobject
metaobject
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 } ], "discounts": [ { "id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d", "discounted_amount": 1.4 } ], "line_items": { "physical_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_taxable": true, "image_url": "string", "discounts": [ { "id": 0, "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0, "is_require_shipping": true, "is_mutable": true, "parent_id": 0, "gift_wrapping": { "name": "string", "message": "string", "amount": 0, "amount_as_integer": 0 } } ], "digital_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "parent_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_mutable": true, "is_require_shipping": true, "is_taxable": true, "image_url": "string", "discounts": [ { "id": "string", "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0 } ], "gift_certificates": [ { "theme": "string", "amount": 0, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "id": "string", "name": "string", "taxable": true, "message": "string" } ], "custom_items": [ { "quantity": 0, "id": "string", "extended_list_price": 0, "list_price": 0, "sku": "string", "name": "string", "image_url": "string" } ] }, "created_time": "string", "updated_time": "string" }, "billing_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" } ], "id": "string" }, "consignments": [ { "id": "string", "shippingAddress": {}, "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" } ], "id": "string" }, "available_shipping_options": [ { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" } ], "selected_shipping_option": { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" }, "coupon_discounts": [ { "code": "string", "amount": 0 } ], "discounts": [ { "id": 0 } ], "shipping_cost_inc_tax": 0, "shipping_cost_ex_tax": 0, "handling_cost_inc_tax": 0, "handling_cost_ex_tax": 0, "line_item_ids": [ "string" ], "selected_pickup_option": { "pickup_method_id": 0 } } ], "taxes": [ { "name": "string", "amount": 0 } ], "coupons": [ { "code": "SHOPNOW", "id": 1, "coupon_type": "percentage_discount", "discounted_amount": 0.9 } ], "order_id": "string", "shipping_cost_total_inc_tax": 0, "shipping_cost_total_ex_tax": 0, "handling_cost_total_inc_tax": 0, "handling_cost_total_ex_tax": 0, "tax_total": 0, "subtotal_inc_tax": 0, "subtotal_ex_tax": 0, "grand_total": 0, "created_time": "string", "updated_time": "string", "customer_message": "string", "promotions": [ { "banners": [ { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } ] } ] }, "meta": {} }
Update Checkout Consignment
PUT /stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId}
Request
Updates an existing consignment. The address, line item IDs, and the shipping option ID can be updated using this endpoint.
To add a new address and shipping options with line items, complete the following steps.
-
Add a new consignment to a checkout.
-
Assign a shipping option to the new consignment by sending a
PUTrequest to update the consignment'sshipping_option_idwith a returned value fromdata.consignments[N].available_shipping_option[N].idobtained in Step One.
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- 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 to get available shipping options.
Body
array | 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.
addressobject
line_itemsarray[object]
shipping_option_idstring
pickup_optionobject
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
dataobject
metaobject
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 } ], "discounts": [ { "id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d", "discounted_amount": 1.4 } ], "line_items": { "physical_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_taxable": true, "image_url": "string", "discounts": [ { "id": 0, "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0, "is_require_shipping": true, "is_mutable": true, "parent_id": 0, "gift_wrapping": { "name": "string", "message": "string", "amount": 0, "amount_as_integer": 0 } } ], "digital_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "parent_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_mutable": true, "is_require_shipping": true, "is_taxable": true, "image_url": "string", "discounts": [ { "id": "string", "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0 } ], "gift_certificates": [ { "theme": "string", "amount": 0, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "id": "string", "name": "string", "taxable": true, "message": "string" } ], "custom_items": [ { "quantity": 0, "id": "string", "extended_list_price": 0, "list_price": 0, "sku": "string", "name": "string", "image_url": "string" } ] }, "created_time": "string", "updated_time": "string" }, "billing_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" } ], "id": "string" }, "consignments": [ { "id": "string", "shippingAddress": {}, "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" } ], "id": "string" }, "available_shipping_options": [ { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" } ], "selected_shipping_option": { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" }, "coupon_discounts": [ { "code": "string", "amount": 0 } ], "discounts": [ { "id": 0 } ], "shipping_cost_inc_tax": 0, "shipping_cost_ex_tax": 0, "handling_cost_inc_tax": 0, "handling_cost_ex_tax": 0, "line_item_ids": [ "string" ], "selected_pickup_option": { "pickup_method_id": 0 } } ], "taxes": [ { "name": "string", "amount": 0 } ], "coupons": [ { "code": "SHOPNOW", "id": 1, "coupon_type": "percentage_discount", "discounted_amount": 0.9 } ], "order_id": "string", "shipping_cost_total_inc_tax": 0, "shipping_cost_total_ex_tax": 0, "handling_cost_total_inc_tax": 0, "handling_cost_total_ex_tax": 0, "tax_total": 0, "subtotal_inc_tax": 0, "subtotal_ex_tax": 0, "grand_total": 0, "created_time": "string", "updated_time": "string", "customer_message": "string", "promotions": [ { "banners": [ { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } ] } ] }, "meta": {} }
Delete Checkout Consignment
DELETE /stores/{store_hash}/v3/checkouts/{checkoutId}/consignments/{consignmentId}
Request
Removes an existing consignment from a checkout.
Removing the last consignment will remove the cart from the customer it is assigned to. Create a new redirect URL for the customer so they can access the cart again.
Authentication
- X-Auth-Token in header - required
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
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: xxxxxxxxxxxxxxxxx'
Response
Body
object | application/json
dataobject
metaobject
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 } ], "discounts": [ { "id": "5eba1f1e-0ec5-40f7-8058-f7b452c7237d", "discounted_amount": 1.4 } ], "line_items": { "physical_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_taxable": true, "image_url": "string", "discounts": [ { "id": 0, "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0, "is_require_shipping": true, "is_mutable": true, "parent_id": 0, "gift_wrapping": { "name": "string", "message": "string", "amount": 0, "amount_as_integer": 0 } } ], "digital_items": [ { "quantity": 0, "id": "string", "variant_id": 0, "parent_id": 0, "product_id": 0, "sku": "string", "name": "string", "url": "string", "is_mutable": true, "is_require_shipping": true, "is_taxable": true, "image_url": "string", "discounts": [ { "id": "string", "discounted_amount": 0 } ], "discount_amount": 0, "coupon_amount": 0, "original_price": 0, "list_price": 0, "sale_price": 0, "extended_list_price": 0, "extended_sale_price": 0 } ], "gift_certificates": [ { "theme": "string", "amount": 0, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "id": "string", "name": "string", "taxable": true, "message": "string" } ], "custom_items": [ { "quantity": 0, "id": "string", "extended_list_price": 0, "list_price": 0, "sku": "string", "name": "string", "image_url": "string" } ] }, "created_time": "string", "updated_time": "string" }, "billing_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" } ], "id": "string" }, "consignments": [ { "id": "string", "shippingAddress": {}, "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" } ], "id": "string" }, "available_shipping_options": [ { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" } ], "selected_shipping_option": { "description": "string", "id": "string", "type": "string", "image_url": "string", "cost": 0, "transit_time": "string" }, "coupon_discounts": [ { "code": "string", "amount": 0 } ], "discounts": [ { "id": 0 } ], "shipping_cost_inc_tax": 0, "shipping_cost_ex_tax": 0, "handling_cost_inc_tax": 0, "handling_cost_ex_tax": 0, "line_item_ids": [ "string" ], "selected_pickup_option": { "pickup_method_id": 0 } } ], "taxes": [ { "name": "string", "amount": 0 } ], "coupons": [ { "code": "SHOPNOW", "id": 1, "coupon_type": "percentage_discount", "discounted_amount": 0.9 } ], "order_id": "string", "shipping_cost_total_inc_tax": 0, "shipping_cost_total_ex_tax": 0, "handling_cost_total_inc_tax": 0, "handling_cost_total_ex_tax": 0, "tax_total": 0, "subtotal_inc_tax": 0, "subtotal_ex_tax": 0, "grand_total": 0, "created_time": "string", "updated_time": "string", "customer_message": "string", "promotions": [ { "banners": [ { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } ] } ] }, "meta": {} }