> 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. # Update Customer ID PUT https://api.bigcommerce.com/stores/{store_hash}/v3/carts/{cartId} Content-Type: application/json Updates a *Cartʼs* `customer_id`. **Notes** Changing the *Cart* `customer_id` will remove any promotions or shipping calculations on the *Cart*. These are tied to the customer depending on cart conditions and any customer groups. 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. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/carts/carts-single/update-cart ## 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 CartUpdatePutRequestData. - `customer_id` (integer, 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. ## Errors ### 409 Conflict Error Cart conflict - `status` (integer, optional) - `title` (string, optional) - `type` (string, optional) - `instance` (string, optional) - `errors` (ErrorResponseErrors, optional) ## Types ### 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. ### ErrorResponseErrors ### 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 **Request** ```json { "customer_id": 5, "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 Carts (Single)_updateCart_example import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId" payload = { "customer_id": 5, "version": 1 } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Carts (Single)_updateCart_example const url = 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"customer_id":5,"version":1}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Carts (Single)_updateCart_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId" payload := strings.NewReader("{\n \"customer_id\": 5,\n \"version\": 1\n}") req, _ := http.NewRequest("PUT", 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 Carts (Single)_updateCart_example require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"customer_id\": 5,\n \"version\": 1\n}" response = http.request(request) puts response.read_body ``` ```java Carts (Single)_updateCart_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"customer_id\": 5,\n \"version\": 1\n}") .asString(); ``` ```php Carts (Single)_updateCart_example request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId', [ 'body' => '{ "customer_id": 5, "version": 1 }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Carts (Single)_updateCart_example using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/carts/cartId"); var request = new RestRequest(Method.PUT); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"customer_id\": 5,\n \"version\": 1\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Carts (Single)_updateCart_example import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ "customer_id": 5, "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")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```