Merchant Compliance

Refunds

Refund all or part of a recorded order for a connected merchant.

Issue a refund against an order you previously recorded with Orders. Omit items to refund the whole order, or include specific items to issue a partial refund. The operation acts on a single connected merchant identified by merchantId.

Uses POST and the X-API-KEY header. See Merchant Transactions for the shared conventions, error shapes, and usage rules.

Endpoint

1POST https://api.zip-tax.com/merchant/refund/create

Request body

FieldTypeRequiredDescription
merchantIdstring (UUID)YesThe connected merchant. Must be owned by the calling account. Consumed for routing and not forwarded.
orderIdstringYesThe order to refund, as supplied when the order was created. Consumed for routing and not forwarded in the refund payload.
itemsarrayNoThe items to refund. Omit or send an empty array for a full refund; include items for a partial refund. Each entry is { "itemId": "...", "quantity": 1 }.
returnedDatestring (RFC3339 date-time)NoInclude only if this return amends a previously filed sales tax return; providing it triggers an Amended Sales Tax Return. Not typically recommended.
batchIdstringNoOptional batch ID for grouping related refunds.

Refund item object

FieldTypeRequiredDescription
itemIdstring (1–50 chars)YesThe itemId of the line item to refund. Must match an itemId from the original order.
quantitynumber (0–99999.9999)YesThe quantity of the item to refund. May be fractional and must not exceed the quantity on the original order.

Refund prices and tax amounts are calculated automatically from the order — you do not send them. If the order had discounts applied, refunds use the discounted prices (the amounts the customer actually paid).

Examples

$curl -X POST "https://api.zip-tax.com/merchant/refund/create" \
>  -H "X-API-KEY: YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
>    "orderId": "order-2026-000123"
>  }'

Response

Returns the recorded refund:

FieldTypeDescription
connectionIdstringThe TaxCloud connection the refund was recorded under.
createdDatestring (RFC3339 date-time)When the refund was created.
returnedDatestring (RFC3339 date-time)When the refund took effect.
batchIdstringBatch ID grouping this refund, if one was supplied.
items[].indexintegerZero-based position of the item within the refund.
items[].itemIdstringThe refunded line item, matching the original order.
items[].pricenumberThe unit price refunded, calculated automatically from the order. Reflects discounted amounts when the order had discounts.
items[].quantitynumberThe quantity refunded.
items[].ticintegerTaxability Information Code of the refunded item.
items[].tax.amountnumberThe tax amount refunded, calculated proportionally from the order’s tax.
1{
2  "connectionId": "25eb9b97-5acb-492d-b720-c03e79cf715a",
3  "createdDate": "2026-07-14T09:30:00Z",
4  "returnedDate": "2026-07-14T09:30:00Z",
5  "items": [
6    {
7      "index": 0,
8      "itemId": "sku-1001",
9      "price": 49.99,
10      "quantity": 1,
11      "tic": 0,
12      "tax": { "amount": 3.87 }
13    }
14  ]
15}

Refunds are never retried automatically, and you should not retry them blindly, a duplicate refund is a financial incident. If a refund call times out or returns 502/504, first confirm whether it succeeded by fetching the order with order/get using "expand": "refunds", then retry only if the refund is not present.

Orders

Record and retrieve the orders you refund against.

Merchant Transactions

Shared conventions, errors, and usage.