> 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. # Orders Orders record a completed sale for compliance purposes. You can create an order from a previously calculated [cart](cart), or create one directly from a full order payload, then retrieve or update it later. All four operations act on a single [TaxCloud-connected merchant](taxcloud-connected-merchants) identified by `merchantId`. All endpoints use `POST` and the `X-API-KEY` header. See [Merchant Transactions](transactions) for the shared conventions, error shapes, and usage rules. The `Address`, `Line item`, and `Discounts` object schemas are shared with [Cart Tax Calculation](cart#address-object). > **Info** > > Orders are not available for [self-managed merchants](self-managed-merchants) — > all four operations return `403`. Their > [cart calculations](self-managed-cart-calculation) are stateless, so there is no > stored cart or order to act on. ## Create an order from a cart Turn a cart you calculated with [Cart Tax Calculation](cart) into a recorded order. ```http POST https://api.zip-tax.com/merchant/order/create-from-cart ``` | Field | Type | Required | Description | | --------------- | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded. | | `cartId` | string (1–50 chars) | Yes | The cart identifier returned by (or supplied to) [`cart/calculate`](cart). | | `orderId` | string (1–50 chars) | Yes | Your identifier for the resulting order. Used later with `order/get`, `order/update`, and [`refund/create`](refunds). | | `completed` | boolean | No | Whether the order has shipped, creating a tax liability. Defaults to `false`. Ignored when `completedDate` is provided. | | `completedDate` | string (RFC3339 date-time) | No | The datetime the order was shipped on, which created the tax liability. Takes precedence over `completed`. | | `kind` | string | No | `order` (default) for a sale, or `credit` for a credit order. | #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/order/create-from-cart" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "cartId": "cart-2026-000123", "orderId": "order-2026-000123", "completed": true }' ``` Returns the recorded [order](#order-response). ## Create an order Record an order directly, without a prior cart calculation. The tax amounts on each line item are the amounts your checkout collected. ```http POST https://api.zip-tax.com/merchant/order/create ``` | Field | Type | Required | Description | | ------------------- | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `merchantId` | string (UUID) | Yes | The connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded. | | `orderId` | string (max 50 chars) | Yes | Your identifier for the order. Used later with `order/get`, `order/update`, and [`refund/create`](refunds). | | `customerId` | string (max 50 chars) | Yes | Your identifier for the customer. Used to match exemption certificates and order history. | | `transactionDate` | string (RFC3339 date-time) | Yes | The datetime the order was purchased on. | | `completedDate` | string (RFC3339 date-time) | Yes | The datetime the order was shipped on, which created the tax liability. | | `origin` | [Address](cart#address-object) | Yes | The ship-from address of the sale. | | `destination` | [Address](cart#address-object) | Yes | The ship-to address of the sale. | | `currency` | object | Yes | `{ "currencyCode": "USD" }`. ISO 4217 code the prices are denominated in: `USD` or `CAD`. | | `lineItems` | array | Yes | The items on the order. Same shape as the cart [line item](cart#line-item-object), **plus a required `tax` object** per item: `{ "rate": 0.0775, "amount": 7.75 }` with the rate and amount collected. | | `kind` | string | No | `order` (default) for a sale, or `credit` for a credit order. | | `channel` | string | No | The sales channel the order came from. Pass one of `amazon`, `ebay`, or `walmart` to exclude marketplace-collected tax from filing. | | `deliveredBySeller` | boolean | No | Whether the seller delivers the order directly rather than via common carrier. | | `discounts` | [Discounts](cart#discounts-object) | No | Optional line-item and order-level discounts. | | `exemption` | object | No | `{ "exemptionId": "...", "isExempt": true }`. Exemption information for the customer. | | `excludeFromFiling` | boolean | No | Whether to exclude the order from tax filing. | | `batchId` | string | No | Optional batch ID for grouping related orders. | #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/order/create" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "customerId": "customer-453", "transactionDate": "2026-07-13T14:00:00Z", "completedDate": "2026-07-13T14:00:00Z", "currency": { "currencyCode": "USD" }, "origin": { "line1": "1 Market St", "city": "San Francisco", "state": "CA", "zip": "94105" }, "destination": { "line1": "200 Spectrum Center Dr", "city": "Irvine", "state": "CA", "zip": "92618" }, "lineItems": [ { "index": 0, "itemId": "sku-1001", "price": 49.99, "quantity": 2, "tic": 0, "tax": { "rate": 0.0775, "amount": 7.75 } } ] }' ``` Returns the recorded [order](#order-response). ## Get an order Retrieve a recorded order. ```http POST https://api.zip-tax.com/merchant/order/get ``` | Field | Type | Required | Description | | ------------ | ------------- | -------- | ---------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. | | `orderId` | string | Yes | The order to retrieve, as supplied when the order was created. | | `expand` | string | No | Set to `refunds` to include the order's refunds in the response. | #### cURL ```bash curl -X POST "https://api.zip-tax.com/merchant/order/get" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10", "orderId": "order-2026-000123", "expand": "refunds" }' ``` This is a read and is safe to retry. Returns the [order](#order-response). ## Update an order Modify a recorded order. Currently the `completedDate` can be set, which marks the order shipped and creates the tax liability. ```http POST https://api.zip-tax.com/merchant/order/update ``` | Field | Type | Required | Description | | --------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `merchantId` | string (UUID) | Yes | The connected merchant. | | `orderId` | string | Yes | The order to update, as supplied when the order was created. Consumed for routing and not forwarded in the update payload. | | `completedDate` | string (RFC3339 date-time) | No | The datetime the order was shipped on, which creates the tax liability. | > **Warning** > > Updates overwrite the fields you send. Because a retried update can clobber a > concurrent change, updates are not retried automatically. See > [Retries and idempotency](transactions#retries-and-idempotency). Returns the updated [order](#order-response). ## Order response All four operations return the order record: | Field | Type | Description | | ------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connectionId` | string | The TaxCloud connection the order was recorded under. | | `orderId` | string | Your identifier for the order. | | `kind` | string | `order` for a sale or `credit` for a credit order. | | `customerId` | string | Your identifier for the customer. | | `deliveredBySeller` | boolean | Whether the seller delivered the order directly. | | `origin` / `destination` | [Address](cart#address-object) | The ship-from and ship-to addresses. | | `currency` | object | The currency the prices and tax amounts are denominated in. | | `lineItems[]` | array | The order's line items with `index`, `itemId`, `tic`, `price` (discounted, when discounts applied), `originalPrice`, `quantity`, and `tax` (`rate`, `amount`). | | `transactionDate` | string (RFC3339 date-time) | When the order was purchased. | | `completedDate` | string (RFC3339 date-time) | When the order was shipped/completed. Absent for orders not yet completed. | | `exemption` | object | The exemption information recorded on the order. | | `channel` | string or null | The sales channel the order came from. | | `excludeFromFiling` | boolean | Whether the order is excluded from tax filing. | | `batchId` | string | Batch ID grouping this order, if one was supplied. | | `refunds[]` | array | Refunds recorded against the order. Only included when `expand` is `refunds`; see the [refund response](refunds#response). | ```json { "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a", "orderId": "order-2026-000123", "kind": "order", "customerId": "customer-453", "deliveredBySeller": false, "origin": { "line1": "1 Market St", "city": "San Francisco", "state": "CA", "zip": "94105", "countryCode": "US" }, "destination": { "line1": "200 Spectrum Center Dr", "city": "Irvine", "state": "CA", "zip": "92618", "countryCode": "US" }, "currency": { "currencyCode": "USD" }, "lineItems": [ { "index": 0, "itemId": "sku-1001", "tic": 0, "price": 49.99, "originalPrice": 49.99, "quantity": 2, "tax": { "rate": 0.0775, "amount": 7.75 } } ], "transactionDate": "2026-07-13T14:00:00Z", "completedDate": "2026-07-13T14:00:00Z", "exemption": { "exemptionId": null, "isExempt": null }, "channel": null, "excludeFromFiling": false } ``` ## Related #### [Cart Tax Calculation](cart) Calculate a cart before creating an order from it. #### [Refunds](refunds) Refund all or part of an order. #### [Merchant Transactions](transactions) Shared conventions, errors, and usage.