> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Add Cart Line Items POST https://api.bigcommerce.com/stores/{store_hash}/v3/carts/{cartId}/items Content-Type: application/json Adds line item to the *Cart*. **Usage Notes** To add a custom item use `custom_items`. Note that images are not supported for custom items; the `image_url` field is accepted but does not render on the storefront. If a product has modifiers, omit the `variant_id` and instead use the `option_selections` array to describe both the **variant** and the **modifier** selections. 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. **Overridable fields** When adding a line item, you can override the following catalog values: | Field | Description | |-|-| | `list_price` | Override the product's price. By default, overriding a product's `list_price` makes it ineligible for V3 product-level promotions. In **Store Settings** under **Promotions and Coupons** in the control panel, you can change this behavior to allow promotions on overridden prices. | | `name` | Override the product name. Useful for locale-specific product names. | | `option_selections.name` | Override the name of an option or modifier selection. Useful for locale-specific option labels. | | `option_selections.value` | Override the value of an option or modifier selection. Useful for locale-specific option values. | Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/carts/items/add-cart-line-items ## Authentication - `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| |Carts|modify|`store_cart`| |Carts |read-only|`store_cart_read_only`| |Information & Settings | modify | `store_v2_information`| |Information & Settings | read-only| `store_v2_information`| ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `cartId` (string, required) — The identifier of a specific cart. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Query parameters - `include` (list of enum, optional) — * `redirect_urls`: Create a direct link to a cart. This can be used for the /POST request for carts. * `line_items.physical_items.options`: The cart returns an abbreviated result. Use this to return physical items product options. To return the extended cart object, use in a /POST request. * `line_items.digital_items.options`: The cart returns an abbreviated result. Use this to return digital items product options. To return the extended cart object, use in a /POST request. * `line_items.physical_items.stock_position`: Returns backorder and stock availability details for physical items. * `line_items.digital_items.stock_position`: Returns backorder and stock availability details for digital items. Since digital products cannot be backordered, backorder values are always zero. * `promotions.banners`: Returns a list of eligible banners. - Allowed values: `redirect_urls`, `line_items.physical_items.options`, `line_items.digital_items.options`, `line_items.physical_items.stock_position`, `line_items.digital_items.stock_position`, `promotions.banners` ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ### Body (application/json) This endpoint expects a Cart_Line_Item_Update_Post. - `line_items` (CartLineItemUpdatePostLineItems, optional) - `gift_certificates` (list of CartLineItemUpdatePostGiftCertificatesItems, optional) - `custom_items` (list of CartPostCustomItemItems, optional) - `version` (integer, optional) — 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. ## Response ### 201 The requested cart. - `data` (Cart_Full, optional) — A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data. - `meta` (metaCollection_open, optional) — Response metadata. ## Types ### CartLineItemUpdatePostLineItems ### CartLineItemUpdatePostGiftCertificatesItems - `name` (string, required) — Given name for gift certificate line item. - `theme` (enum, required) — The theme of the gift certificate. - Allowed values: `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, `Girl` - `amount` (double, required) - `quantity` (integer, required) - `sender` (CartLineItemUpdatePostGiftCertificatesItemsSender, required) - `recipient` (CartLineItemUpdatePostGiftCertificatesItemsRecipient, required) - `message` (string, optional) — Message shown to recipient, as provided by sender. ### CartPostCustomItemItems - `sku` (string, required) - `name` (string, required) - `quantity` (double, required) - `list_price` (double, required) - `image_url` (string, optional) — Not supported for custom items. Although the API accepts this field, the image does not display on the storefront. ### Cart_Full A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data. - `id` (string, optional) — Cart ID, provided after creating a cart with a POST request. - `customer_id` (integer, optional) — ID of the customer to which the cart belongs. - `channel_id` (integer, optional) — The channel ID. If no channel is specified, defaults to 1. - `email` (string, optional) — The cart’s email. This is the same email that is used in the billing address. - `currency` (CartFullCurrency, optional) — The currency. This is the same for both the cart and its subsequent checkout. - `tax_included` (boolean, optional) - `base_amount` (double, optional) — Sum of cart line-item amounts before cart-level discounts, coupons, or taxes. - `discount_amount` (double, optional) — Order-based discounted amount only - Excludes coupon discounts and product-based discounts. - `manual_discount_amount` (double, optional) — The entered value represents the order level manual discount. - `cart_amount` (double, optional) — Sum of cart line-item amounts minus cart-level discounts and coupons. This amount includes taxes (where applicable). - `coupons` (list of AppliedCoupon, optional) - `discounts` (list of CartFullDiscountsItems, optional) - `line_items` (LineItemsGet, optional) — `GET` - `created_time` (string, optional) — Time when the cart was created. - `updated_time` (string, optional) — Time when the cart was last updated. - `locale` (string, optional) — Locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format. - `promotions` (CartFullPromotions, optional) — This is available only when "include=promotions.banners" is presented in the URL. - `version` (integer, optional) — The current version of the cart increments with each successful update. You can use it to enable optimistic concurrency control for subsequent updates. ### metaCollection_open Response metadata. ### CartLineItemUpdatePostGiftCertificatesItemsSender - `name` (string, optional) - `email` (string, optional) ### CartLineItemUpdatePostGiftCertificatesItemsRecipient - `name` (string, optional) - `email` (string, optional) ### CartFullCurrency The currency. This is the same for both the cart and its subsequent checkout. - `code` (string, optional) — The [transactional currency](/developer/api-reference/rest/admin/management/currencies#definitions) code for the cart, formatted as an [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) string. ### AppliedCoupon |Type `int`|Type Name| |-|-| |`0`|`per_item_discount`| |`1`|`percentage_discount`| |`2`|`per_total_discount`| |`3`|`shipping_discount`| |`4`|`free_shipping`| |`5`|`promotion`| - `code` (string, required) — The coupon code. - `id` (string, optional) — The coupon ID. (read-only) - `coupon_type` (enum, optional) — Key name to identify the type of coupon. type 0: per_item_discount type 1: percentage_discount type 2: per_total_discount type 3: shipping_discount type 4: free_shipping type 5: promotion - Allowed values: `0`, `1`, `2`, `3`, `4`, `5` - `discounted_amount` (double, optional) — The discounted amount applied within a given context. - `display_name` (string, optional) — Display name of the coupon. ### CartFullDiscountsItems Example as part of a cart response: ``` "discounts": [ { "id": 2, "discounted_amount": 2 }, { "id": "coupon", "discounted_amount": 0.42 } ] ``` - `id` (string, optional) — ID of the applied discount. - `discounted_amount` (double, optional) — The discounted amount. ### LineItemsGet `GET` - `physical_items` (list of ItemPhysicalGet, optional) - `digital_items` (list of ItemDigitalGet, optional) - `gift_certificates` (list of ItemGiftCertificateGet, optional) - `custom_items` (list of ItemCustomGet, optional) ### CartFullPromotions This is available only when "include=promotions.banners" is presented in the URL. - `banners` (CartFullPromotionsBanners, optional) ### ItemPhysicalGet - `variant_id` (double, required) — The ID of the variant. Required in the /PUT or /POST request if the product has variants. - `product_id` (double, required) — The ID of the product. Required in a /POST request. - `quantity` (double, required) — Quantity of this item in the cart. - `id` (string, optional) — The line-item ID. - `parent_id` (string, optional) — Bundled items will have the ID of their parent item. - `added_by_attribute_id` (string, optional, nullable) — For a bundled item added via a B2B quote, the ID of the quote-item attribute that added it. Null otherwise. - `sku` (string, optional) — SKU of the variant. - `name` (string, optional) — The item’s product name. - `url` (string, optional) — The product URL. - `taxable` (boolean, optional) — Boolean value that specifies whether the item is taxable. - `image_url` (string, optional) — Image of the product or variant. - `discounts` (list of ItemPhysicalGetDiscountsItems, optional) - `coupons` (ItemPhysicalGetCoupons, optional) - `discount_amount` (double, optional) — The total value of all discounts applied to this item. This includes coupons and cart-level discounts. - `coupon_amount` (double, optional) — The total value of all coupons applied to this item. - `original_price` (double, optional) — An item’s original price is the same as the product default price in the admin panel. - `list_price` (double, optional) — The net item price before discounts and coupons are applied. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel. To enable v3 promotions at the product level, you must update the [promotion](https://support.bigcommerce.com/s/article/Store-Settings?language=en_US#promotion) settings in the control panel. - `sale_price` (double, optional) — Price of the item after all discounts are applied. (The final price before tax calculation.) - `extended_list_price` (double, optional) — List price of the item multiplied by the quantity. - `extended_sale_price` (double, optional) — Sale price of the item multiplied by the quantity. - `is_require_shipping` (boolean, optional) — Whether or not a physical product requires shipping. - `is_mutable` (boolean, optional) — Whether or not you can change or remove the item from the cart. Items that are immutable include those added automatically by promotions. - `added_by_promotion` (boolean, optional) — Whether or not a promotion added an additional item. - `is_custom_price` (boolean, optional) — Whether or not the item's price was overridden with a custom value using the `list_price` field. - `gift_wrapping` (ItemPhysicalGetGiftWrapping, optional) — The gift wrapping details for this item. - `stock_position` (ItemPhysicalGetStockPosition, optional) — Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=line_items.physical_items.stock_position` (or the `digital_items` equivalent) — not included by default. ### ItemDigitalGet - `id` (string, optional) — The line-item ID. - `parent_id` (string, optional) — Bundled items will have the ID of their parent item. - `variant_id` (double, optional) — The ID of the variant. Required in the /PUT or /POST request if the product has variants. - `product_id` (double, optional) — The ID of the product. Required in a /POST request. - `added_by_attribute_id` (string, optional, nullable) — For a bundled item added via a B2B quote, the ID of the quote-item attribute that added it. Null otherwise. - `sku` (string, optional) — SKU of the variant. - `name` (string, optional) — The item’s product name. - `url` (string, optional) — The product URL. - `quantity` (double, optional) — Quantity of this item in the cart. - `taxable` (boolean, optional) — Boolean value that specifies whether the item is taxable. - `image_url` (string, optional) — Image of the product or variant. - `discounts` (list of ItemDigitalGetDiscountsItems, optional) - `coupons` (ItemDigitalGetCoupons, optional) - `discount_amount` (double, optional) — The total value of all discounts applied to this item. This includes coupons and cart-level discounts. - `coupon_amount` (double, optional) — The total value of all coupons applied to this item. - `original_price` (double, optional) — An item’s original price is the same as the product default price in the admin panel. - `list_price` (double, optional) — The net item price before discounts and coupons. BigCommerce derives an item’s list price from the product default price or, if applicable, the sale price configured in the admin panel. - `sale_price` (double, optional) — Item’s price after all discounts are applied. (The final price before tax calculation.) - `extended_list_price` (double, optional) — List price of the item multiplied by the quantity. - `extended_sale_price` (double, optional) — Sale price of the item multiplied by the quantity. - `is_require_shipping` (boolean, optional) — Whether or not a physical product requires shipping. - `is_mutable` (boolean, optional) — Whether or not you can change or remove the item from the cart. Items that are immutable include those added automatically by promotions. - `added_by_promotion` (boolean, optional) — Whether or not a promotion added an additional item. - `is_custom_price` (boolean, optional) — Whether or not the item's price was overridden with a custom value using the `list_price` field. - `download_file_urls` (list of string, optional) — URLs to download all product files. - `download_page_url` (string, optional) — The URL for the combined downloads page. - `download_size` (string, optional) — Specifies the combined download size of all files in human-readable style; for example, `30MB`. ### ItemGiftCertificateGet - `id` (string, optional) - `name` (string, optional) — Name provided for the gift certificate that will appear in the control panel. - `theme` (string, optional) — The theme of the gift certificate. The following options are available:`Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`. - `amount` (double, optional) — Value must be between 1.00 and 1,000.00 in the store’s default currency. - `taxable` (boolean, optional) - `sender` (ItemGiftCertificateGetSender, optional) - `recipient` (ItemGiftCertificateGetRecipient, optional) - `message` (string, optional) — The message included in the gift certificate is limited to 200 characters. ### ItemCustomGet Add a custom item to the shopperʼs cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes. * Images are not supported for custom items. The `image_url` field is not rendered on the storefront. - `id` (string, optional) — ID of the custom item. - `sku` (string, optional) — SKU of the custom item. - `name` (string, optional) — Name of the item. - `quantity` (string, optional) - `list_price` (string, optional) — Specifies the price of the item. This value can include or exclude tax, depending on the store setup. - `extended_list_price` (double, optional) — List price of the item multiplied by the quantity. - `image_url` (string, optional) — Not rendered on the storefront. Although the API accepts and returns this field for custom items, the image does not display in the cart or at checkout. ### CartFullPromotionsBanners - `id` (string, optional) — ID of the promotion. - `type` (string, optional) — Type of the banner. - `page` (list of string, optional) — An array of the locations where the banner will display. - `text` (string, optional) — Text of the banner. ### ItemPhysicalGetDiscountsItems Example as part of a cart response: ``` "discounts": [ { "id": 2, "discounted_amount": 2 }, { "id": "coupon", "discounted_amount": 0.42 } ] ``` - `id` (ItemPhysicalGetDiscountsItemsId, optional) - `discounted_amount` (double, optional) — The discounted amount. ### ItemPhysicalGetCoupons ### ItemPhysicalGetGiftWrapping The gift wrapping details for this item. - `name` (string, optional) - `message` (string, optional) - `amount` (float, optional) ### ItemPhysicalGetStockPosition Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=line_items.physical_items.stock_position` (or the `digital_items` equivalent) — not included by default. - `quantity_on_hand` (integer, optional) — Number of units currently in stock and available to fulfill this line item without backordering. - `quantity_backordered` (integer, optional) — Number of units from this line item that are fulfilled via backorder. - `quantity_out_of_stock` (integer, optional) — Number of units from this line item that are out of stock and unavailable for backorder. - `backorder_message` (string, optional, nullable) — Backorder messaging shown to the customer for this line item. `null` if no backorder message applies. ### ItemDigitalGetDiscountsItems Example as part of a cart response: ``` "discounts": [ { "id": 2, "discounted_amount": 2 }, { "id": "coupon", "discounted_amount": 0.42 } ] ``` - `id` (ItemDigitalGetDiscountsItemsId, optional) - `discounted_amount` (double, optional) — The discounted amount. ### ItemDigitalGetCoupons ### ItemGiftCertificateGetSender - `name` (string, optional) - `email` (string, optional) ### ItemGiftCertificateGetRecipient - `name` (string, optional) - `email` (string, optional) ### ItemPhysicalGetDiscountsItemsId ### ItemDigitalGetDiscountsItemsId ## Examples ### Example 1 **Request** ```json { "line_items": [ { "list_price": 12.5, "option_selections": [ { "option_id": 8, "option_value": 8 } ], "product_id": 77, "quantity": 2 } ], "gift_certificates": [ { "name": "Happy Birthday", "theme": "Birthday", "amount": 50, "quantity": 1, "sender": { "name": "Jane Does", "email": "janedoe@example.com" }, "recipient": { "name": "Jane Does", "email": "janedoe@example.com" }, "message": "Happy Birthday Jane!" } ], "version": 1 } ``` **Response** ```json { "data": { "id": "string", "customer_id": 1, "channel_id": 1, "email": "string", "currency": { "code": "usd" }, "tax_included": true, "base_amount": 1.1, "discount_amount": 1.1, "manual_discount_amount": 1.1, "cart_amount": 1.1, "coupons": [ { "code": "string", "id": "string", "coupon_type": "0", "discounted_amount": 1.1, "display_name": "20% Off" } ], "discounts": [ { "id": "coupon", "discounted_amount": 1.1 } ], "line_items": { "physical_items": [ { "variant_id": 358, "product_id": 12, "quantity": 5, "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "gift_wrapping": { "name": "Gift Wrap 1", "message": "Happy Birthday!", "amount": 1.99 }, "stock_position": { "quantity_on_hand": 1, "quantity_backordered": 1, "quantity_out_of_stock": 1, "backorder_message": "string" } } ], "digital_items": [ { "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "variant_id": 358, "product_id": 12, "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "quantity": 5, "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "download_file_urls": [ "string" ], "download_page_url": "string", "download_size": "string" } ], "gift_certificates": [ { "id": "string", "name": "string", "theme": "string", "amount": 1.1, "taxable": true, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "message": "string" } ], "custom_items": [ { "id": "string", "sku": "string", "name": "string", "quantity": "string", "list_price": "string", "extended_list_price": 1.1, "image_url": "https://pathtoproductimage/ProductDefault.png" } ] }, "created_time": "string", "updated_time": "string", "locale": "string", "promotions": { "banners": { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } }, "version": 1 }, "meta": {} } ``` **SDK Code** ```python Example 1 import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload = { "line_items": [ { "list_price": 12.5, "option_selections": [ { "option_id": 8, "option_value": 8 } ], "product_id": 77, "quantity": 2 } ], "gift_certificates": [ { "name": "Happy Birthday", "theme": "Birthday", "amount": 50, "quantity": 1, "sender": { "name": "Jane Does", "email": "janedoe@example.com" }, "recipient": { "name": "Jane Does", "email": "janedoe@example.com" }, "message": "Happy Birthday Jane!" } ], "version": 1 } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example 1 const url = 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"line_items":[{"list_price":12.5,"option_selections":[{"option_id":8,"option_value":8}],"product_id":77,"quantity":2}],"gift_certificates":[{"name":"Happy Birthday","theme":"Birthday","amount":50,"quantity":1,"sender":{"name":"Jane Does","email":"janedoe@example.com"},"recipient":{"name":"Jane Does","email":"janedoe@example.com"},"message":"Happy Birthday Jane!"}],"version":1}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 1 package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload := strings.NewReader("{\n \"line_items\": [\n {\n \"list_price\": 12.5,\n \"option_selections\": [\n {\n \"option_id\": 8,\n \"option_value\": 8\n }\n ],\n \"product_id\": 77,\n \"quantity\": 2\n }\n ],\n \"gift_certificates\": [\n {\n \"name\": \"Happy Birthday\",\n \"theme\": \"Birthday\",\n \"amount\": 50,\n \"quantity\": 1,\n \"sender\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"recipient\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"message\": \"Happy Birthday Jane!\"\n }\n ],\n \"version\": 1\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example 1 require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"line_items\": [\n {\n \"list_price\": 12.5,\n \"option_selections\": [\n {\n \"option_id\": 8,\n \"option_value\": 8\n }\n ],\n \"product_id\": 77,\n \"quantity\": 2\n }\n ],\n \"gift_certificates\": [\n {\n \"name\": \"Happy Birthday\",\n \"theme\": \"Birthday\",\n \"amount\": 50,\n \"quantity\": 1,\n \"sender\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"recipient\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"message\": \"Happy Birthday Jane!\"\n }\n ],\n \"version\": 1\n}" response = http.request(request) puts response.read_body ``` ```java Example 1 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"line_items\": [\n {\n \"list_price\": 12.5,\n \"option_selections\": [\n {\n \"option_id\": 8,\n \"option_value\": 8\n }\n ],\n \"product_id\": 77,\n \"quantity\": 2\n }\n ],\n \"gift_certificates\": [\n {\n \"name\": \"Happy Birthday\",\n \"theme\": \"Birthday\",\n \"amount\": 50,\n \"quantity\": 1,\n \"sender\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"recipient\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"message\": \"Happy Birthday Jane!\"\n }\n ],\n \"version\": 1\n}") .asString(); ``` ```php Example 1 request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items', [ 'body' => '{ "line_items": [ { "list_price": 12.5, "option_selections": [ { "option_id": 8, "option_value": 8 } ], "product_id": 77, "quantity": 2 } ], "gift_certificates": [ { "name": "Happy Birthday", "theme": "Birthday", "amount": 50, "quantity": 1, "sender": { "name": "Jane Does", "email": "janedoe@example.com" }, "recipient": { "name": "Jane Does", "email": "janedoe@example.com" }, "message": "Happy Birthday Jane!" } ], "version": 1 }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Example 1 using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"line_items\": [\n {\n \"list_price\": 12.5,\n \"option_selections\": [\n {\n \"option_id\": 8,\n \"option_value\": 8\n }\n ],\n \"product_id\": 77,\n \"quantity\": 2\n }\n ],\n \"gift_certificates\": [\n {\n \"name\": \"Happy Birthday\",\n \"theme\": \"Birthday\",\n \"amount\": 50,\n \"quantity\": 1,\n \"sender\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"recipient\": {\n \"name\": \"Jane Does\",\n \"email\": \"janedoe@example.com\"\n },\n \"message\": \"Happy Birthday Jane!\"\n }\n ],\n \"version\": 1\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example 1 import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ "line_items": [ [ "list_price": 12.5, "option_selections": [ [ "option_id": 8, "option_value": 8 ] ], "product_id": 77, "quantity": 2 ] ], "gift_certificates": [ [ "name": "Happy Birthday", "theme": "Birthday", "amount": 50, "quantity": 1, "sender": [ "name": "Jane Does", "email": "janedoe@example.com" ], "recipient": [ "name": "Jane Does", "email": "janedoe@example.com" ], "message": "Happy Birthday Jane!" ] ], "version": 1 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Example 2: Custom Item **Request** ```json { "custom_items": [ { "sku": "abc-123", "name": "Custom Product", "quantity": 1, "list_price": 10 } ] } ``` **Response** ```json { "data": { "id": "string", "customer_id": 1, "channel_id": 1, "email": "string", "currency": { "code": "usd" }, "tax_included": true, "base_amount": 1.1, "discount_amount": 1.1, "manual_discount_amount": 1.1, "cart_amount": 1.1, "coupons": [ { "code": "string", "id": "string", "coupon_type": "0", "discounted_amount": 1.1, "display_name": "20% Off" } ], "discounts": [ { "id": "coupon", "discounted_amount": 1.1 } ], "line_items": { "physical_items": [ { "variant_id": 358, "product_id": 12, "quantity": 5, "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "gift_wrapping": { "name": "Gift Wrap 1", "message": "Happy Birthday!", "amount": 1.99 }, "stock_position": { "quantity_on_hand": 1, "quantity_backordered": 1, "quantity_out_of_stock": 1, "backorder_message": "string" } } ], "digital_items": [ { "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "variant_id": 358, "product_id": 12, "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "quantity": 5, "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "download_file_urls": [ "string" ], "download_page_url": "string", "download_size": "string" } ], "gift_certificates": [ { "id": "string", "name": "string", "theme": "string", "amount": 1.1, "taxable": true, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "message": "string" } ], "custom_items": [ { "id": "string", "sku": "string", "name": "string", "quantity": "string", "list_price": "string", "extended_list_price": 1.1, "image_url": "https://pathtoproductimage/ProductDefault.png" } ] }, "created_time": "string", "updated_time": "string", "locale": "string", "promotions": { "banners": { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } }, "version": 1 }, "meta": {} } ``` **SDK Code** ```python Example 2: Custom Item import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload = { "custom_items": [ { "sku": "abc-123", "name": "Custom Product", "quantity": 1, "list_price": 10 } ] } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example 2: Custom Item const url = 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"custom_items":[{"sku":"abc-123","name":"Custom Product","quantity":1,"list_price":10}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example 2: Custom Item package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload := strings.NewReader("{\n \"custom_items\": [\n {\n \"sku\": \"abc-123\",\n \"name\": \"Custom Product\",\n \"quantity\": 1,\n \"list_price\": 10\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Example 2: Custom Item require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"custom_items\": [\n {\n \"sku\": \"abc-123\",\n \"name\": \"Custom Product\",\n \"quantity\": 1,\n \"list_price\": 10\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java Example 2: Custom Item import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"custom_items\": [\n {\n \"sku\": \"abc-123\",\n \"name\": \"Custom Product\",\n \"quantity\": 1,\n \"list_price\": 10\n }\n ]\n}") .asString(); ``` ```php Example 2: Custom Item request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items', [ 'body' => '{ "custom_items": [ { "sku": "abc-123", "name": "Custom Product", "quantity": 1, "list_price": 10 } ] }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Example 2: Custom Item using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"custom_items\": [\n {\n \"sku\": \"abc-123\",\n \"name\": \"Custom Product\",\n \"quantity\": 1,\n \"list_price\": 10\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example 2: Custom Item import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = ["custom_items": [ [ "sku": "abc-123", "name": "Custom Product", "quantity": 1, "list_price": 10 ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Adding a line item with price and name overrides, and locale-specific option values. **Request** ```json { "line_items": [ { "list_price": 25, "name": "Camiseta", "option_selections": [ { "name": "Tamaño", "option_id": 125, "option_value": 127, "value": "Pequeño" } ], "product_id": 118, "quantity": 1, "variant_id": 140 } ] } ``` **Response** ```json { "data": { "id": "string", "customer_id": 1, "channel_id": 1, "email": "string", "currency": { "code": "usd" }, "tax_included": true, "base_amount": 1.1, "discount_amount": 1.1, "manual_discount_amount": 1.1, "cart_amount": 1.1, "coupons": [ { "code": "string", "id": "string", "coupon_type": "0", "discounted_amount": 1.1, "display_name": "20% Off" } ], "discounts": [ { "id": "coupon", "discounted_amount": 1.1 } ], "line_items": { "physical_items": [ { "variant_id": 358, "product_id": 12, "quantity": 5, "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "gift_wrapping": { "name": "Gift Wrap 1", "message": "Happy Birthday!", "amount": 1.99 }, "stock_position": { "quantity_on_hand": 1, "quantity_backordered": 1, "quantity_out_of_stock": 1, "backorder_message": "string" } } ], "digital_items": [ { "id": "6e193ce6-f327-4dcc-b75e-72cf6738525e", "parent_id": "string", "variant_id": 358, "product_id": 12, "added_by_attribute_id": "string", "sku": "SMGREEN", "name": "T-Shirt", "url": "http://your-store-url.mybigcommerce.com/your-product/", "quantity": 5, "taxable": false, "image_url": "https://pathtoproductimage/ProductDefault.png", "discounts": [ { "id": "string", "discounted_amount": 1.1 } ], "coupons": 1.1, "discount_amount": 4, "coupon_amount": 1.1, "original_price": 1.1, "list_price": 1.1, "sale_price": 1.1, "extended_list_price": 1.1, "extended_sale_price": 1.1, "is_require_shipping": false, "is_mutable": true, "added_by_promotion": false, "is_custom_price": false, "download_file_urls": [ "string" ], "download_page_url": "string", "download_size": "string" } ], "gift_certificates": [ { "id": "string", "name": "string", "theme": "string", "amount": 1.1, "taxable": true, "sender": { "name": "string", "email": "string" }, "recipient": { "name": "string", "email": "string" }, "message": "string" } ], "custom_items": [ { "id": "string", "sku": "string", "name": "string", "quantity": "string", "list_price": "string", "extended_list_price": 1.1, "image_url": "https://pathtoproductimage/ProductDefault.png" } ] }, "created_time": "string", "updated_time": "string", "locale": "string", "promotions": { "banners": { "id": "string", "type": "string", "page": [ "string" ], "text": "string" } }, "version": 1 }, "meta": {} } ``` **SDK Code** ```python Adding a line item with price and name overrides, and locale-specific option values. import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload = { "line_items": [ { "list_price": 25, "name": "Camiseta", "option_selections": [ { "name": "Tamaño", "option_id": 125, "option_value": 127, "value": "Pequeño" } ], "product_id": 118, "quantity": 1, "variant_id": 140 } ] } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Adding a line item with price and name overrides, and locale-specific option values. const url = 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"line_items":[{"list_price":25,"name":"Camiseta","option_selections":[{"name":"Tamaño","option_id":125,"option_value":127,"value":"Pequeño"}],"product_id":118,"quantity":1,"variant_id":140}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Adding a line item with price and name overrides, and locale-specific option values. package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items" payload := strings.NewReader("{\n \"line_items\": [\n {\n \"list_price\": 25,\n \"name\": \"Camiseta\",\n \"option_selections\": [\n {\n \"name\": \"Tamaño\",\n \"option_id\": 125,\n \"option_value\": 127,\n \"value\": \"Pequeño\"\n }\n ],\n \"product_id\": 118,\n \"quantity\": 1,\n \"variant_id\": 140\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Adding a line item with price and name overrides, and locale-specific option values. require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"line_items\": [\n {\n \"list_price\": 25,\n \"name\": \"Camiseta\",\n \"option_selections\": [\n {\n \"name\": \"Tamaño\",\n \"option_id\": 125,\n \"option_value\": 127,\n \"value\": \"Pequeño\"\n }\n ],\n \"product_id\": 118,\n \"quantity\": 1,\n \"variant_id\": 140\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java Adding a line item with price and name overrides, and locale-specific option values. import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"line_items\": [\n {\n \"list_price\": 25,\n \"name\": \"Camiseta\",\n \"option_selections\": [\n {\n \"name\": \"Tamaño\",\n \"option_id\": 125,\n \"option_value\": 127,\n \"value\": \"Pequeño\"\n }\n ],\n \"product_id\": 118,\n \"quantity\": 1,\n \"variant_id\": 140\n }\n ]\n}") .asString(); ``` ```php Adding a line item with price and name overrides, and locale-specific option values. request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items', [ 'body' => '{ "line_items": [ { "list_price": 25, "name": "Camiseta", "option_selections": [ { "name": "Tamaño", "option_id": 125, "option_value": 127, "value": "Pequeño" } ], "product_id": 118, "quantity": 1, "variant_id": 140 } ] }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Adding a line item with price and name overrides, and locale-specific option values. using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"line_items\": [\n {\n \"list_price\": 25,\n \"name\": \"Camiseta\",\n \"option_selections\": [\n {\n \"name\": \"Tamaño\",\n \"option_id\": 125,\n \"option_value\": 127,\n \"value\": \"Pequeño\"\n }\n ],\n \"product_id\": 118,\n \"quantity\": 1,\n \"variant_id\": 140\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Adding a line item with price and name overrides, and locale-specific option values. import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = ["line_items": [ [ "list_price": 25, "name": "Camiseta", "option_selections": [ [ "name": "Tamaño", "option_id": 125, "option_value": 127, "value": "Pequeño" ] ], "product_id": 118, "quantity": 1, "variant_id": 140 ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId/items")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```