> 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 Cart Currency POST https://your_store.example.com/api/storefront/carts/{cartId}/currency Content-Type: application/json Update currency of the *Cart*. Promotions and gift certificates that don't apply to the new currency will be removed from your cart. You cannot update the cart currency if the draft order cart or the cart contains a manual discount. > #### Note > * Substitute your storefront domain for `yourstore.example.com`. > * The Send a Test Request feature is not currently supported for this endpoint. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/storefront/carts/cart-currency/update-cart-currency ## Request ### Path parameters - `cartId` (string, required) — This cartʼs unique ID. ### Query parameters - `include` (list of enum, optional) — Sub-resources to include in the Cart response, in a comma-separated list. `lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return physical items product options. Can also be used in a /POST to have the extended Cart object return. `lineItems.digitalItems.options`: The Cart returns an abbreviated result. Use this to return digital items product options. Can also be used in a /POST to have the extended Cart object return. `lineItems.digitalItems.options,lineItems.physicalItems.options`: The Cart returns an abbreviated result. Use this to return digital and physical options. Can also be used in a /POST to have the extended Cart object return. `lineItems.physicalItems.stockPosition`: Returns backorder and stock availability details for physical items. `lineItems.digitalItems.stockPosition`: Returns backorder and stock availability details for digital items. Since digital products cannot be backordered, backorder values are always zero. - Allowed values: `lineItems.physicalItems.options`, `lineItems.digitalItems.options`, `lineItems.physicalItems.stockPosition`, `lineItems.digitalItems.stockPosition` ### 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 an object. - `currencyCode` (string, required) — currency code ## Response ### 200 A list of the shopper's carts. - `list of responseCart` ## Errors ### 400 Bad Request Error Bad request. Authentication Required. - `any` ### 404 Not Found Error Currency not found - `any` ### 422 Unprocessable Entity Error Missing or invalid data - `any` ## Types ### responseCart Cart object used in REST Storefront API cart responses. - `id` (string, optional) — Cart ID, provided after creating a cart with a POST. - `customerId` (integer, optional) — ID of the customer to which the cart belongs. - `email` (string, optional) — The cart's email. This is the same email that is used in the billing address - `currency` (responseCartCurrency, optional) — This will always be the same between cart and checkout. - `isTaxIncluded` (boolean, optional) — Whether this item is taxable. - `baseAmount` (double, optional) — Cost of cart’s contents, before applying discounts. - `discountAmount` (float, optional) — Order based discounted amount only - Coupon discounts and product based discounts are excluded. - `cartAmount` (double, optional) — Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes (where applicable). - `coupons` (list of ResponseCartCouponsItems, optional) - `discounts` (list of ResponseCartDiscountsItems, optional) - `lineItems` (responseCartLineItems, optional) - `createdTime` (string, optional) — Time when the cart was created. - `updatedTime` (string, optional) — Time when the cart was last updated. - `locale` (string, optional) — Locale of the cart. - `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. ### responseCartCurrency This will always be the same between cart and checkout. - `code` (string, optional) — ISO-4217 currency code. (See: https://www.iso.org/iso-4217-currency-codes.html.) - `decimalPlaces` (integer, optional) — The number of decimal places that prices have when you use the currency. - `name` (string, optional) — The name for the currency that the merchant entered in the control panel. - `symbol` (string, optional) — The currency symbol displayed on the storefront. ### ResponseCartCouponsItems - `code` (string, required) — The coupon code. - `couponType` (integer, optional) — |Type `int`|Type Name| |-|-| |`0`|`per_item_discount`| |`1`|`percentage_discount`| |`2`|`per_total_discount`| |`3`|`shipping_discount`| |`4`|`free_shipping`| |`5`|`promotion`| - `discountedAmount` (float, optional) — The discounted amount applied within a given context. - `displayName` (string, optional) — The coupon name displayed on the storefront. - `id` (string, optional) — The coupon ID. ### ResponseCartDiscountsItems - `discountedAmount` (float, optional) — The discounted amount applied within a given context. - `id` (string, optional) — ID of the applied discount. ### responseCartLineItems - `customItems` (list of responseCartLineItemsCustomItems, optional) - `digitalItems` (list of responseCartLineItemsDigitalItems, optional) — Array of `ItemDigital` objects. - `giftCertificates` (list of responseCartLineItemsGiftCertificates, optional) — Array of `ItemGiftCertificate` objects. - `physicalItems` (list of responseCartLineItemsItemsPhysicalItemsItems, optional) — Array of `ItemPhysical` objects. ### responseCartLineItemsCustomItems **Read Only** This will return in the Cart Response if the Cart was created using the [REST Management API](/developer/api-reference/rest/admin/management/carts). A custom item can only be added to a cart using the REST Management API. - `extendedListPrice` (integer, optional) - `id` (string, optional) — ID of the custom item - `listPrice` (integer, optional) — Price of the item. With or without tax depending on your stores set up. - `name` (string, optional) — Name of the custom item. - `quantity` (integer, optional) - `sku` (string, optional) — SKU of the custom item. ### responseCartLineItemsDigitalItems - `quantity` (double, required) — Quantity of this item. - `brand` (string, optional) — The products brand - `couponAmount` (double, optional) — The total value of all coupons applied to this item. - `discountAmount` (float, optional) — The total value of all discounts applied to this item (excluding coupon). - `discounts` (list of responseCartLineItemsDigitalItemsAllOf0DiscountsItems, optional) — List of discounts applied to this item, as an array of AppliedDiscount objects. - `extendedListPrice` (double, optional) — Item's list price multiplied by the quantity. - `extendedSalePrice` (double, optional) — Item's sale price multiplied by the quantity. - `id` (string, optional) — The line-item ID. - `imageUrl` (string, optional) — URL of an image of this item, accessible on the internet. - `isMutable` (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. - `isTaxable` (boolean, optional) — Whether the item is taxable. - `listPrice` (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. - `name` (string, optional) — The item's product name. - `options` (list of responseCartLineItemsDigitalItemsAllOf0OptionsItems, optional) — The list of selected options for this product. - `originalPrice` (double, optional) — An item’s original price is the same as the product default price in the admin panel. - `parentId` (string, optional) — The product is part of a bundle such as a product pick list, then the parentId or the main product id will populate. - `productId` (double, optional) — ID of the product. - `salePrice` (double, optional) — Item's price after all discounts are applied. (The final price before tax calculation.) - `sku` (string, optional) — SKU of the variant. - `stockPosition` (ResponseCartLineItemsDigitalItemsAllOf0StockPosition, optional) — Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=lineItems.digitalItems.stockPosition` — not included by default. Since digital products cannot be backordered, backorder values are always zero for digital items. - `type` (enum, optional) — The type of line item. - Allowed values: `digital` - `url` (string, optional) — The product URL. - `variantId` (double, optional) — ID of the variant. ### responseCartLineItemsGiftCertificates - `amount` (double, required) — Value must be between 1.00 and 1,000.00 in the storeʼs default currency. - `recipient` (responseCartLineItemsGiftCertificatesRecipient, required) - `sender` (responseCartLineItemsGiftCertificatesSender, required) - `theme` (string, required) — Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`. - `id` (string, optional) — ID of this gift certificate. - `taxable` (boolean, optional) — Whether or not the gift certificate is taxable. - `message` (string, optional) — Message that will be sent to the gift certificate's recipient. Limited to 200 characters. - `name` (string, optional) — Name provided for the gift certificate that appears in the control panel. - `type` (enum, optional) — The type of line item. - Allowed values: `giftCertificate` ### responseCartLineItemsItemsPhysicalItemsItems - `quantity` (double, required) — Quantity of this item. - `brand` (string, optional) — The products brand - `couponAmount` (double, optional) — The total value of all coupons applied to this item. - `discountAmount` (float, optional) — The total value of all discounts applied to this item (excluding coupon). - `discounts` (list of ResponseCartDiscountsItems, optional) - `extendedListPrice` (double, optional) — Item's list price multiplied by the quantity. - `extendedSalePrice` (double, optional) — Item's sale price multiplied by the quantity. - `giftWrapping` (responseCartLineItemsPhysicalItemGiftWrapping, optional) - `id` (string, optional) — The line-item ID. - `imageUrl` (string, optional) — URL of an image of this item, accessible on the internet. - `isMutable` (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. - `isShippingRequired` (boolean, optional) — Whether this item requires shipping to a physical address. - `isTaxable` (boolean, optional) — Whether the item is taxable. - `listPrice` (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. - `name` (string, optional) — The item's product name. - `options` (list of responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems, optional) — The list of selected options for this product. - `originalPrice` (double, optional) — An item’s original price is the same as the product default price in the admin panel. - `parentId` (double, optional) — The product is part of a bundle such as a product pick list, then the parentId or the main product id will populate. - `productId` (double, optional) — ID of the product. - `salePrice` (double, optional) — Item's price after all discounts are applied. (The final price before tax calculation.) - `sku` (string, optional) — SKU of the variant. - `stockPosition` (ResponseCartBaseItemStockPosition, optional) — Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=lineItems.physicalItems.stockPosition` (or the `digitalItems` equivalent) — not included by default. - `type` (enum, optional) — The type of line item. - Allowed values: `physical` - `url` (string, optional) — The product URL. - `variantId` (double, optional) — ID of the variant. ### responseCartLineItemsDigitalItemsAllOf0DiscountsItems - `discountedAmount` (float, optional) — The discounted amount applied within a given context. - `id` (double, optional) — ID of the applied discount. ### responseCartLineItemsDigitalItemsAllOf0OptionsItems - `name` (string, optional) — The product option name. For example, Color or Size - `nameId` (double, optional) — The product option identifier. It is the same as the `optionId` used in the request. - `value` (string, optional) — The product option value. For example, Red or Medium - `valueId` (double, optional) — The product option value identifier. It is the same as the `optionValue` used in the request. ### ResponseCartLineItemsDigitalItemsAllOf0StockPosition Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=lineItems.digitalItems.stockPosition` — not included by default. Since digital products cannot be backordered, backorder values are always zero for digital items. - `quantityOnHand` (integer, optional) — Number of units currently in stock and available to fulfill this line item without backordering. - `quantityBackordered` (integer, optional) — Number of units from this line item that are fulfilled via backorder. - `quantityOutOfStock` (integer, optional) — Number of units from this line item that are out of stock and unavailable for backorder. - `backorderMessage` (string, optional, nullable) — Backorder messaging shown to the customer for this line item. `null` if no backorder message applies. ### responseCartLineItemsGiftCertificatesRecipient - `email` (string, optional) — Contact's email address. - `name` (string, optional) — Contact's name. ### responseCartLineItemsGiftCertificatesSender - `email` (string, optional) — Contact's email address. - `name` (string, optional) — Contact's name. ### responseCartLineItemsPhysicalItemGiftWrapping - `amount` (float, optional) — Gift-wrapping price per product. - `message` (string, optional) - `name` (string, optional) — Name of the gift-wrapping option. ### responseCartLineItemsItemsPhysicalItemsItemsAllOf0OptionsItems - `name` (string, optional) — The product option name. For example, Color or Size - `nameId` (double, optional) — The product option identifier. It is the same as the `optionId` used in the request. - `value` (string, optional) — The product option value. For example, Red or Medium - `valueId` (double, optional) — The product option value identifier. It is the same as the `optionValue` used in the request. ### ResponseCartBaseItemStockPosition Backorder and stock availability details for this line item. Only returned when explicitly requested via `include=lineItems.physicalItems.stockPosition` (or the `digitalItems` equivalent) — not included by default. - `quantityOnHand` (integer, optional) — Number of units currently in stock and available to fulfill this line item without backordering. - `quantityBackordered` (integer, optional) — Number of units from this line item that are fulfilled via backorder. - `quantityOutOfStock` (integer, optional) — Number of units from this line item that are out of stock and unavailable for backorder. - `backorderMessage` (string, optional, nullable) — Backorder messaging shown to the customer for this line item. `null` if no backorder message applies. ## Examples **Request** ```json { "currencyCode": "string" } ``` **Response** ```json [ { "id": "770ded29-da45-4ee0-abc6-883e83c0e5ed", "customerId": 0, "email": "", "currency": { "code": "USD", "decimalPlaces": 2, "name": "US Dollars", "symbol": "$" }, "isTaxIncluded": false, "baseAmount": 246, "discountAmount": 0, "cartAmount": 221.4, "coupons": [], "discounts": [ { "discountedAmount": 24.6, "id": "a83dea21-d757-47a2-a06a-73cf6a983746" } ], "lineItems": { "customItems": [], "digitalItems": [], "giftCertificates": [], "physicalItems": [ { "quantity": 2, "brand": "BigCommerce", "couponAmount": 0, "discountAmount": 24.6, "discounts": [ { "discountedAmount": 24.6, "id": "string" } ], "extendedListPrice": 246, "extendedSalePrice": 221.4, "giftWrapping": null, "id": "a83dea21-d757-47a2-a06a-73cf6a983746", "imageUrl": "https://cdn11.bigcommerce.com/r-3b68d717e18793df0b51c71e16bc24664ad18b7c/themes/ClassicNext/images/ProductDefault.gif", "isMutable": true, "isShippingRequired": true, "isTaxable": true, "listPrice": 123, "name": "options test", "originalPrice": 130, "parentId": 6, "productId": 230, "salePrice": 110.7, "sku": "sku123-VA", "type": "physical", "url": "https://store.example.com/options-test/", "variantId": 193 } ] }, "createdTime": "2021-03-04T14:17:50+00:00", "updatedTime": "2021-03-04T14:17:50+00:00", "locale": "en", "version": 1 } ] ``` **SDK Code** ```python Example import requests url = "https://your_store.example.com/api/storefront/carts/cartId/currency" payload = { "currencyCode": "string" } headers = { "Accept": "application/json", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example const url = 'https://your_store.example.com/api/storefront/carts/cartId/currency'; const options = { method: 'POST', headers: {Accept: 'application/json', 'Content-Type': 'application/json'}, body: '{"currencyCode":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://your_store.example.com/api/storefront/carts/cartId/currency" payload := strings.NewReader("{\n \"currencyCode\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") 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 require 'uri' require 'net/http' url = URI("https://your_store.example.com/api/storefront/carts/cartId/currency") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["Content-Type"] = 'application/json' request.body = "{\n \"currencyCode\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java Example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://your_store.example.com/api/storefront/carts/cartId/currency") .header("Accept", "application/json") .header("Content-Type", "application/json") .body("{\n \"currencyCode\": \"string\"\n}") .asString(); ``` ```php Example request('POST', 'https://your_store.example.com/api/storefront/carts/cartId/currency', [ 'body' => '{ "currencyCode": "string" }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Example using RestSharp; var client = new RestClient("https://your_store.example.com/api/storefront/carts/cartId/currency"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"currencyCode\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example import Foundation let headers = [ "Accept": "application/json", "Content-Type": "application/json" ] let parameters = ["currencyCode": "string"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://your_store.example.com/api/storefront/carts/cartId/currency")! 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() ```