> 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. # Create Order From Cart POST https://api.zip-tax.com/merchant/order/create-from-cart Content-Type: application/json Available on Enterprise PlanForwards to TaxCloud POST /connections/\{connectionId}/carts/orders to capture a previously calculated cart as an order. cartId and orderId travel in the forwarded body. 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-create-from-cart ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects an object. - `cartId` (string, required) — The cartId returned by (or supplied to) /merchant/cart/calculate identifying the calculated cart to convert into an order. - `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 resulting order in your own system. Used later with /merchant/order/get, /merchant/order/update, and /merchant/refund/create. - `completed` (boolean, optional) — Whether the order has shipped, creating a tax liability. Defaults to false. Ignored when completedDate is provided. - `completedDate` (datetime, optional) — RFC3339 datetime the order was shipped on, which created the tax liability. Takes precedence over the completed field when provided. - `kind` (enum, optional, default: order) — The kind of order to create: 'order' for a sale (default) or 'credit' for a credit order. - Allowed values: `order`, `credit` ## 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 Create from Cart 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 { "cartId": "my-cart-1", "merchantId": "merchantId", "orderId": "my-order-1" } ``` **Response** ```json { "channel": "amazon", "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a", "currency": { "currencyCode": "USD" }, "customerId": "customer-453", "deliveredBySeller": true, "destination": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427", "countryCode": "US", "line2": "line2" }, "excludeFromFiling": true, "exemption": { "exemptionId": "exemptionId", "isExempt": true }, "kind": "order", "orderId": "my-order-1", "origin": { "city": "Minneapolis", "line1": "323 Washington Ave N", "state": "MN", "zip": "55401-2427", "countryCode": "US", "line2": "line2" }, "batchId": "batchId", "completedDate": "2024-01-15T09:30:00Z", "lineItems": [ { "index": 0, "itemId": "item-1", "originalPrice": 12, "price": 10.75, "quantity": 1.5, "tax": { "amount": 1.31, "rate": 0.08125 }, "tic": 0 } ], "refunds": [ { "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a", "batchId": "batchId", "createdDate": "2024-01-15T09:30:00Z", "items": [ { "index": 1000000, "itemId": "itemId", "price": 1.1, "quantity": 1.1, "tic": 0 } ], "returnedDate": "2024-01-15T09:30:00Z" } ], "transactionDate": "2024-01-15T09:30:00Z" } ``` **SDK Code** ```python import requests url = "https://api.zip-tax.com/merchant/order/create-from-cart" payload = { "cartId": "my-cart-1", "merchantId": "merchantId", "orderId": "my-order-1" } 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/create-from-cart'; const options = { method: 'POST', headers: {'X-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"cartId":"my-cart-1","merchantId":"merchantId","orderId":"my-order-1"}' }; 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/create-from-cart" payload := strings.NewReader("{\n \"cartId\": \"my-cart-1\",\n \"merchantId\": \"merchantId\",\n \"orderId\": \"my-order-1\"\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/create-from-cart") 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 \"cartId\": \"my-cart-1\",\n \"merchantId\": \"merchantId\",\n \"orderId\": \"my-order-1\"\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/create-from-cart") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"cartId\": \"my-cart-1\",\n \"merchantId\": \"merchantId\",\n \"orderId\": \"my-order-1\"\n}") .asString(); ``` ```php request('POST', 'https://api.zip-tax.com/merchant/order/create-from-cart', [ 'body' => '{ "cartId": "my-cart-1", "merchantId": "merchantId", "orderId": "my-order-1" }', '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/create-from-cart"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"cartId\": \"my-cart-1\",\n \"merchantId\": \"merchantId\",\n \"orderId\": \"my-order-1\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "cartId": "my-cart-1", "merchantId": "merchantId", "orderId": "my-order-1" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.zip-tax.com/merchant/order/create-from-cart")! 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() ```