> This page is for version v6.0 (default). > For other versions, use one of these documentation indexes: > - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt > - v5.0: https://docs.zip.tax/v-5-0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.zip.tax/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server. # Update Order POST https://api.zip-tax.com/merchant/order/update Content-Type: application/json Available on Enterprise PlanForwards to TaxCloud PATCH /connections/\{connectionId}/orders/\{orderId}. orderId is a path identifier; the remaining body is the update payload relayed unchanged. Requires a TaxCloud-connected merchant with credentials on file: this operation returns 403 for a self-managed merchant, whose only available transaction endpoint is /merchant/cart/calculate. Reference: https://docs.zip.tax/api-reference/merchant-transactions-tax-cloud/merchant-order-update ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects an object. - `merchantId` (string, required) — UUID of the merchant. Must be owned by the calling account. Consumed by the Ziptax layer for routing and not forwarded to TaxCloud. - `orderId` (string, required) — Your identifier for the order to update, as supplied when the order was created. Consumed for routing and not forwarded in the update payload. - `completedDate` (datetime, optional) — RFC3339 datetime the order was shipped on, which creates the tax liability. ## Response ### 200 TaxCloud response relayed verbatim. - `channel` (string, required) — The sales channel the order came from (e.g. amazon, ebay, walmart). Null when no channel was recorded. - `connectionId` (string, required) — The TaxCloud connection the order was recorded under. - `currency` (TaxCloudCurrency, required) — The currency the prices and tax amounts are denominated in. - `customerId` (string, required) — Your identifier for the customer in your own system. - `deliveredBySeller` (boolean, required) — Whether the seller delivered the order directly. - `destination` (TaxCloudAddress, required) — The ship-to (destination) address of the order. - `excludeFromFiling` (boolean, required) — Whether the order is excluded from tax filing. - `exemption` (TaxCloudExemption, required) — The exemption information recorded on the order. - `kind` (enum, required) — The kind of order: 'order' for a sale or 'credit' for a credit order. - Allowed values: `order`, `credit` - `orderId` (string, required) — Your identifier for the order in your own system. - `origin` (TaxCloudAddress, required) — The ship-from (origin) address of the order. - `batchId` (string, optional) — Batch ID grouping this order with related orders, if one was supplied. - `completedDate` (datetime, optional) — RFC3339 datetime the order was shipped/completed on, creating the tax liability. Absent for orders that are not yet completed. - `lineItems` (list of TaxCloudCartItemWithTaxResponse, optional) — The order's line items, each with its tax rate and amount. - `refunds` (list of TaxCloudRefundResponse, optional) — Refunds recorded against this order. Only included when the request set expand to 'refunds'. - `transactionDate` (datetime, optional) — RFC3339 datetime the order was purchased on. ## Errors ### 400 Merchant Order Update Body Bad Request Error Bad Request - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 401 Merchant Order Update Body Unauthorized Error Unauthorized - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 403 Merchant Order Update Body Forbidden Error Forbidden - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 404 Merchant Order Update Body Not Found Error Not Found - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 413 Merchant Order Update Body Content Too Large Error Request Entity Too Large - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 422 Merchant Order Update Body Unprocessable Entity Error Unprocessable Entity - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 429 Merchant Order Update Body Too Many Requests Error Too Many Requests - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 500 Merchant Order Update Body Internal Server Error Internal Server Error - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 502 Merchant Order Update Body Bad Gateway Error Bad Gateway - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ### 504 Merchant Order Update Body Gateway Timeout Error Gateway Timeout - `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem. - `errors` (list of ErrorDetail, optional) — List of individual error details - `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem. - `status` (long, optional) — HTTP status code - `title` (string, optional) — A short, human-readable summary of the problem type. This value should not change between occurrences of the error. - `type` (string, optional, default: about:blank) — A URI reference to human-readable documentation for the error. ## Types ### TaxCloudCurrency - `currencyCode` (enum, optional, default: USD) — ISO 4217 currency code the line-item prices are denominated in. USD or CAD. Defaults to USD when omitted. - Allowed values: `USD`, `CAD` ### TaxCloudAddress - `city` (string, required) — City or post-town of the address. - `line1` (string, required) — First line of the address: street number and name, PO Box, or building. Values longer than 50 characters are automatically truncated by TaxCloud. - `state` (string, required) — State, province, or other large territorial division, as a two-letter abbreviation (e.g. MN, CA, ON). - `zip` (string, required) — Postal or ZIP code. Five-digit (55401) and ZIP+4 (55401-2427) formats are accepted for US addresses. - `countryCode` (enum, optional, default: US) — ISO 3166-1 alpha-2 country code of the address. US (United States) or CA (Canada). Defaults to US when omitted. - Allowed values: `US`, `CA` - `line2` (string, optional) — Second line of the address, if any (e.g. apartment, suite, or unit number). Values longer than 50 characters are automatically truncated by TaxCloud. ### TaxCloudExemption - `exemptionId` (string, optional) — Identifier of an exemption certificate previously created for the customer (see /merchant/cert/create). When provided, the customer is treated as exempt and the certificate is associated with the transaction. - `isExempt` (boolean, optional) — Whether the customer is exempt from sales tax. Assumed true when exemptionId is provided. ### TaxCloudCartItemWithTaxResponse - `index` (long, required) — Zero-based position of the item within the cart or order. - `itemId` (string, required) — Your unique identifier for the line item, as submitted. - `originalPrice` (double, required) — The original (pre-discount) unit price, as submitted. - `price` (double, required) — The unit price tax was calculated on. When discounts were applied, this is the discounted unit price. - `quantity` (double, required) — Quantity of the item. - `tax` (TaxCloudTax, required) — The tax rate and amount calculated for this line item. - `tic` (long, optional) — Taxability Information Code (TIC) the item was calculated under. Null when no TIC applies. ### TaxCloudRefundResponse - `connectionId` (string, required) — The TaxCloud connection the refund was recorded under. - `batchId` (string, optional) — Batch ID grouping this refund with related refunds, if one was supplied. - `createdDate` (datetime, optional) — RFC3339 datetime the refund was created. - `items` (list of TaxCloudRefundItemResponse, optional) — The refunded line items, each with the refunded price, quantity, and tax amount. - `returnedDate` (datetime, optional) — RFC3339 datetime the refund took effect. ### ErrorDetail - `location` (string, optional) — Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' - `message` (string, optional) — Error message text - `value` (any, optional) — The value at the given location ### TaxCloudTax - `amount` (double, required) — The calculated tax amount for the line item, in the transaction currency. - `rate` (double, required) — The combined tax rate applied to the line item, as a decimal fraction (e.g. 0.08125 = 8.125%). ### TaxCloudRefundItemResponse - `index` (long, required) — Zero-based position of the item within the refund. - `itemId` (string, required) — The itemId of the refunded line item, matching the original order. - `price` (double, required) — The unit price refunded, calculated automatically from the order. When the order had discounts, this reflects the discounted amount actually paid. - `quantity` (double, required) — The quantity refunded. - `tax` (TaxCloudRefundTax, optional) — The tax amount refunded for this line item. - `tic` (long, optional) — Taxability Information Code (TIC) of the refunded item. ### TaxCloudRefundTax - `amount` (double, required) — The tax amount refunded for the item, calculated proportionally from the order's tax. When the order had discounts, this reflects tax on the discounted price. ## Examples **Request** ```json { "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "completedDate": "2026-07-13T14:00:00Z" } ``` **Response** ```json { "channel": null, "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a", "currency": { "currencyCode": "USD" }, "customerId": "customer-453", "deliveredBySeller": false, "destination": { "city": "Irvine", "line1": "200 Spectrum Center Dr", "state": "CA", "zip": "92618", "countryCode": "US" }, "excludeFromFiling": false, "exemption": { "exemptionId": null, "isExempt": null }, "kind": "order", "orderId": "order-2026-000123", "origin": { "city": "San Francisco", "line1": "1 Market St", "state": "CA", "zip": "94105", "countryCode": "US" }, "completedDate": "2026-07-13T14:00:00Z", "lineItems": [ { "index": 0, "itemId": "sku-1001", "originalPrice": 49.99, "price": 49.99, "quantity": 2, "tax": { "amount": 7.75, "rate": 0.0775 }, "tic": 0 } ], "transactionDate": "2026-07-13T14:00:00Z" } ``` **SDK Code** ```python import requests url = "https://api.zip-tax.com/merchant/order/update" payload = { "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "completedDate": "2026-07-13T14:00:00Z" } headers = { "X-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.zip-tax.com/merchant/order/update'; const options = { method: 'POST', headers: {'X-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"merchantId":"6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10","orderId":"order-2026-000123","completedDate":"2026-07-13T14:00:00Z"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.zip-tax.com/merchant/order/update" payload := strings.NewReader("{\n \"merchantId\": \"6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10\",\n \"orderId\": \"order-2026-000123\",\n \"completedDate\": \"2026-07-13T14:00:00Z\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-KEY", "") 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 require 'uri' require 'net/http' url = URI("https://api.zip-tax.com/merchant/order/update") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"merchantId\": \"6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10\",\n \"orderId\": \"order-2026-000123\",\n \"completedDate\": \"2026-07-13T14:00:00Z\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.zip-tax.com/merchant/order/update") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"merchantId\": \"6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10\",\n \"orderId\": \"order-2026-000123\",\n \"completedDate\": \"2026-07-13T14:00:00Z\"\n}") .asString(); ``` ```php request('POST', 'https://api.zip-tax.com/merchant/order/update', [ 'body' => '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "completedDate": "2026-07-13T14:00:00Z" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.zip-tax.com/merchant/order/update"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"merchantId\": \"6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10\",\n \"orderId\": \"order-2026-000123\",\n \"completedDate\": \"2026-07-13T14:00:00Z\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "completedDate": "2026-07-13T14:00:00Z" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.zip-tax.com/merchant/order/update")! 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() ```