refunds

Refund order

Create a refund against an order. Multiple refunds are supported, but the total refunded quantity cannot exceed the original order quantity for each item. IMPORTANT: Refund prices and tax amounts are automatically calculated from the order. If the order had discounts applied, refunds will reflect the discounted prices (the actual amount paid). Do not send price or tax fields in the refund request - only itemId and quantity are required. Pass an idempotencyKey to make retries safe — a second request with the same key returns the original refund (HTTP 200) instead of creating a new one. Omitting idempotencyKey returns an X-TaxCloud-Warning response header recommending one; the refund is still created.

post/tax/connections/{connectionId}/orders/refunds/{orderId}

Request

  • Base URL: https://api.v3.taxcloud.com
  • URL: https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/refunds/{orderId}
  • Auth: HTTP bearer

Path parameters

connectionIdstring required

represents the ID of a connection. It is used as a unique identifier for the connection

orderIdstring required

the id of the order to refund against

Request body

$schemastring uri

A URL to the JSON Schema for this object.

batchIdstring

Optional batch ID for grouping refunds

idempotencyKeystring

Optional opaque key uniquely identifying this refund within the (connection, order). When present, a second create attempt with the same key returns the original refund (HTTP 200) instead of creating a new one. Recommended for ETL or Service Bus consumers that may retry. Use a stable identifier from your source system (e.g. a Shopify refund GID), not a request UUID.

returnedDatestring date-time nullable

The date of the return; defaults to the current timestamp. Leave empty (recommended) to deduct the refund from the current month's filing. Setting to a prior-month date may trigger an amended filing.

Response

Created

batchIdstring

Batch ID for grouping refunds

connectionIdstring required

represents the ID of a connection. It is used as a unique identifier for the connection

createdDatestring date-time

represents the time when the refund was created.

idempotencyKeystring

Echoed back when the refund was created with an idempotency key.

returnedDatestring date-time

represents the time when the refund took effect.

Changes

No recorded changes to this operation across all 1 revision of this API.