Merchant Compliance

Orders

Record, retrieve, and update orders on behalf of a connected merchant.

Orders record a completed sale for compliance purposes. You can create an order from a previously calculated cart, or create one directly from a full order payload, then retrieve or update it later. All four operations act on a single connected merchant identified by merchantId.

All endpoints use POST and the X-API-KEY header. See Merchant Transactions for the shared conventions, error shapes, and usage rules. The Address, Line item, and Discounts object schemas are shared with Cart Tax Calculation.

Create an order from a cart

Turn a cart you calculated with Cart Tax Calculation into a recorded order.

1POST https://api.zip-tax.com/merchant/order/create-from-cart
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded.
cartIdstring (1–50 chars)YesThe cart identifier returned by (or supplied to) cart/calculate.
orderIdstring (1–50 chars)YesYour identifier for the resulting order. Used later with order/get, order/update, and refund/create.
completedbooleanNoWhether the order has shipped, creating a tax liability. Defaults to false. Ignored when completedDate is provided.
completedDatestring (RFC3339 date-time)NoThe datetime the order was shipped on, which created the tax liability. Takes precedence over completed.
kindstringNoorder (default) for a sale, or credit for a credit order.
cURL
$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.

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.

1POST https://api.zip-tax.com/merchant/order/create
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded.
orderIdstring (max 50 chars)YesYour identifier for the order. Used later with order/get, order/update, and refund/create.
customerIdstring (max 50 chars)YesYour identifier for the customer. Used to match exemption certificates and order history.
transactionDatestring (RFC3339 date-time)YesThe datetime the order was purchased on.
completedDatestring (RFC3339 date-time)YesThe datetime the order was shipped on, which created the tax liability.
originAddressYesThe ship-from address of the sale.
destinationAddressYesThe ship-to address of the sale.
currencyobjectYes{ "currencyCode": "USD" }. ISO 4217 code the prices are denominated in: USD or CAD.
lineItemsarrayYesThe items on the order. Same shape as the cart line item, plus a required tax object per item: { "rate": 0.0775, "amount": 7.75 } with the rate and amount collected.
kindstringNoorder (default) for a sale, or credit for a credit order.
channelstringNoThe sales channel the order came from. Pass one of amazon, ebay, or walmart to exclude marketplace-collected tax from filing.
deliveredBySellerbooleanNoWhether the seller delivers the order directly rather than via common carrier.
discountsDiscountsNoOptional line-item and order-level discounts.
exemptionobjectNo{ "exemptionId": "...", "isExempt": true }. Exemption information for the customer.
excludeFromFilingbooleanNoWhether to exclude the order from tax filing.
batchIdstringNoOptional batch ID for grouping related orders.
cURL
$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.

Get an order

Retrieve a recorded order.

1POST https://api.zip-tax.com/merchant/order/get
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant.
orderIdstringYesThe order to retrieve, as supplied when the order was created.
expandstringNoSet to refunds to include the order’s refunds in the response.
cURL
$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.

Update an order

Modify a recorded order. Currently the completedDate can be set, which marks the order shipped and creates the tax liability.

1POST https://api.zip-tax.com/merchant/order/update
FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant.
orderIdstringYesThe order to update, as supplied when the order was created. Consumed for routing and not forwarded in the update payload.
completedDatestring (RFC3339 date-time)NoThe datetime the order was shipped on, which creates the tax liability.

Updates overwrite the fields you send. Because a retried update can clobber a concurrent change, updates are not retried automatically. See Retries and idempotency.

Returns the updated order.

Order response

All four operations return the order record:

FieldTypeDescription
connectionIdstringThe TaxCloud connection the order was recorded under.
orderIdstringYour identifier for the order.
kindstringorder for a sale or credit for a credit order.
customerIdstringYour identifier for the customer.
deliveredBySellerbooleanWhether the seller delivered the order directly.
origin / destinationAddressThe ship-from and ship-to addresses.
currencyobjectThe currency the prices and tax amounts are denominated in.
lineItems[]arrayThe order’s line items with index, itemId, tic, price (discounted, when discounts applied), originalPrice, quantity, and tax (rate, amount).
transactionDatestring (RFC3339 date-time)When the order was purchased.
completedDatestring (RFC3339 date-time)When the order was shipped/completed. Absent for orders not yet completed.
exemptionobjectThe exemption information recorded on the order.
channelstring or nullThe sales channel the order came from.
excludeFromFilingbooleanWhether the order is excluded from tax filing.
batchIdstringBatch ID grouping this order, if one was supplied.
refunds[]arrayRefunds recorded against the order. Only included when expand is refunds; see the refund response.
1{
2  "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
3  "orderId": "order-2026-000123",
4  "kind": "order",
5  "customerId": "customer-453",
6  "deliveredBySeller": false,
7  "origin": { "line1": "1 Market St", "city": "San Francisco", "state": "CA", "zip": "94105", "countryCode": "US" },
8  "destination": { "line1": "200 Spectrum Center Dr", "city": "Irvine", "state": "CA", "zip": "92618", "countryCode": "US" },
9  "currency": { "currencyCode": "USD" },
10  "lineItems": [
11    {
12      "index": 0,
13      "itemId": "sku-1001",
14      "tic": 0,
15      "price": 49.99,
16      "originalPrice": 49.99,
17      "quantity": 2,
18      "tax": { "rate": 0.0775, "amount": 7.75 }
19    }
20  ],
21  "transactionDate": "2026-07-13T14:00:00Z",
22  "completedDate": "2026-07-13T14:00:00Z",
23  "exemption": { "exemptionId": null, "isExempt": null },
24  "channel": null,
25  "excludeFromFiling": false
26}
Cart Tax Calculation

Calculate a cart before creating an order from it.

Refunds

Refund all or part of an order.

Merchant Transactions

Shared conventions, errors, and usage.