> 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. # Upsert Customs Information PUT https://api.bigcommerce.com/stores/{store_hash}/v3/shipping/products/customs-information Content-Type: application/json Creates and updates product customs information. This is a batch operation where the creation of multiple customs information objects can be done with one `PUT` request. **Limits** * Limit of 50 customs information objects per `PUT` request. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/shipping/v3/customs-information/update-customs-information ## Authentication - `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_read_only` | ### 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 - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### 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 list of customsInformation_request. - `list of customsInformation_request` ## Response ### 200 OK - `data` (list of customsInformation, optional) ## Errors ### 400 Bad Request Error Bad Request. One or more `product_id` values do not exist. - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — A short, human-readable summary of the problem. - `type` (string, optional) — A URL that describes the status code. - `errors` (map from string to string, optional) — Field-level error messages, keyed by field name. Empty when the error is not field-specific. ### 413 Content Too Large Error Payload Too Large. The request body has more than 50 objects. - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — A short, human-readable summary of the problem. - `type` (string, optional) — A URL that describes the status code. - `errors` (map from string to string, optional) — Field-level error messages, keyed by field name. Empty when the error is not field-specific. ### 422 Unprocessable Entity Error Unprocessable Entity. A customs information object failed validation, for example a missing required field or an invalid HS code. - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — A short, human-readable summary of the problem. - `type` (string, optional) — A URL that describes the status code. - `errors` (map from string to string, optional) — Field-level error messages, keyed by field name. Empty when the error is not field-specific. ## Types ### customsInformation_request Data about the customs information object. - `product_id` (integer, required) — The product ID to which the customs information data applies. - `country_of_origin` (string, required) — The country of manufacture, production, or growth represented in ISO 3166-1 alpha-2 format. - `commodity_description` (string, required) — Description that provides information for customs to identify and verify the shapes, physical characteristics, and packaging of each shipment. - `international_shipping` (boolean, required) — Flag to determine whether this product will be shipped internationally. - `hs_codes` (harmonizedSystemCodes, required) — Key-value pairs that are commonly used in the following form: `countryISO2: '/^[0-9A-Za-z]{6,14}$/'` This key-value pair represents a country and the associated `hs_code` that applies to that country. You can also use the `ALL` key in place of an ISO2 key to specify that the `hs_code` applies to all countries. The `ALL` key can be combined with other countries in the `hs_code` object. ### customsInformation Data about the customs information object. - `product_id` (integer, optional) — The ID of the product which the customs information data will apply to. - `country_of_origin` (string, optional) — The country of manufacture, production, or growth represented in ISO 3166-1 alpha-2 format. - `commodity_description` (string, optional) — Description that provides information for customs to identify and verify shapes physical characteristics and packaging of each shipment. - `international_shipping` (boolean, optional) — Flag to determine whether this product will be shipped internationally. - `hs_codes` (harmonizedSystemCodes, optional) — Key-value pairs that are commonly used in the following form: `countryISO2: '/^[0-9A-Za-z]{6,14}$/'` This key-value pair represents a country and the associated `hs_code` that applies to that country. You can also use the `ALL` key in place of an ISO2 key to specify that the `hs_code` applies to all countries. The `ALL` key can be combined with other countries in the `hs_code` object. - `created_at` (datetime, optional) — Date and time when the customs information was created. - `updated_at` (datetime, optional) — Date and time when the customs information was last updated. ### harmonizedSystemCodes Key-value pairs that are commonly used in the following form: `countryISO2: '/^[0-9A-Za-z]{6,14}$/'` This key-value pair represents a country and the associated `hs_code` that applies to that country. You can also use the `ALL` key in place of an ISO2 key to specify that the `hs_code` applies to all countries. The `ALL` key can be combined with other countries in the `hs_code` object. ## Examples **Request** ```json [ { "product_id": 77, "country_of_origin": "US", "commodity_description": "Baseball caps", "international_shipping": true, "hs_codes": { "ALL": "501000", "AU": "817355", "CA": "508313" } } ] ``` **Response** ```json { "data": [ { "product_id": 77, "country_of_origin": "US", "commodity_description": "Baseball caps", "international_shipping": true, "hs_codes": { "ALL": "501000", "AU": "817355", "CA": "508313", "US": "641000" }, "created_at": {}, "updated_at": {} } ] } ``` **SDK Code** ```python Example import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information" payload = [ { "product_id": 77, "country_of_origin": "US", "commodity_description": "Baseball caps", "international_shipping": True, "hs_codes": { "ALL": "501000", "AU": "817355", "CA": "508313" } } ] headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example const url = 'https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '[{"product_id":77,"country_of_origin":"US","commodity_description":"Baseball caps","international_shipping":true,"hs_codes":{"ALL":"501000","AU":"817355","CA":"508313"}}]' }; 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://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information" payload := strings.NewReader("[\n {\n \"product_id\": 77,\n \"country_of_origin\": \"US\",\n \"commodity_description\": \"Baseball caps\",\n \"international_shipping\": true,\n \"hs_codes\": {\n \"ALL\": \"501000\",\n \"AU\": \"817355\",\n \"CA\": \"508313\"\n }\n }\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 Example require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information") 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 {\n \"product_id\": 77,\n \"country_of_origin\": \"US\",\n \"commodity_description\": \"Baseball caps\",\n \"international_shipping\": true,\n \"hs_codes\": {\n \"ALL\": \"501000\",\n \"AU\": \"817355\",\n \"CA\": \"508313\"\n }\n }\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.put("https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("[\n {\n \"product_id\": 77,\n \"country_of_origin\": \"US\",\n \"commodity_description\": \"Baseball caps\",\n \"international_shipping\": true,\n \"hs_codes\": {\n \"ALL\": \"501000\",\n \"AU\": \"817355\",\n \"CA\": \"508313\"\n }\n }\n]") .asString(); ``` ```php Example request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information', [ 'body' => '[ { "product_id": 77, "country_of_origin": "US", "commodity_description": "Baseball caps", "international_shipping": true, "hs_codes": { "ALL": "501000", "AU": "817355", "CA": "508313" } } ]', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Example using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information"); 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 {\n \"product_id\": 77,\n \"country_of_origin\": \"US\",\n \"commodity_description\": \"Baseball caps\",\n \"international_shipping\": true,\n \"hs_codes\": {\n \"ALL\": \"501000\",\n \"AU\": \"817355\",\n \"CA\": \"508313\"\n }\n }\n]", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ [ "product_id": 77, "country_of_origin": "US", "commodity_description": "Baseball caps", "international_shipping": true, "hs_codes": [ "ALL": "501000", "AU": "817355", "CA": "508313" ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/shipping/products/customs-information")! 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() ```