---
title: "Record a refund"
method: POST
path: "/v1/refunds"
tags: ["Nexus"]
---

# Record a refund

`POST /v1/refunds`

## Request

- Base URL: `https://api.taxlocus.com`
- URL: `https://api.taxlocus.com/v1/refunds`
- Auth: HTTP bearer

Book a full or partial refund against a tracked entity's ledger and return updated nexus status. The ledger is append-only: a refund is a new row carrying a negative amount, never an edit of the original sale. Pass POSITIVE `refund_amount` / `tax_refunded` — the service applies the sign.

Supply `refunded_ref` (the `external_ref` of the original sale) wherever you can: the refund then inherits that sale's state, exempt, marketplace and jurisdiction fields so report totals net against the right buckets, and cumulative refunds are capped at the original sale amount (422 `refund_exceeds_sale`).

`state` is optional when `refunded_ref` resolves to a recorded sale — the original supplies it. Provide one or the other: a `refunded_ref` matching no sale, with no `state`, is rejected (422 `unknown_refund_state`) rather than guessed at.

Refunds reduce the dollar totals that economic-nexus thresholds are measured on, but do NOT reduce the transaction count — a refund is not an additional sale. Supports idempotency via `idempotency_key`.

## Request body

- object
  - `entity_id` string, uuid, required
  - `state` string
  - `refund_amount` number, required
  - `tax_refunded` number
  - `refund_date` string, date
  - `refunded_ref` string
  - `external_ref` string
  - `idempotency_key` string
  - `is_marketplace` boolean
  - `is_exempt` boolean
  - `county_fips` string
  - `place_geoid` string
  - `lat` number
  - `lng` number
  - `address` object
    - `line1` string, required
    - `city` string, required
    - `state` string, required
    - `postal_code` string, required

## Response `200`

Updated nexus status for the entity.

- object

## Other responses

- `400`: Error response.
- `401`: Error response.
- `429`: Error response.
- `500`: Error response.

---

[API](https://skmtc.dev/taxlocus/apis/taxlocus-rest-api.md) · [All operations](https://skmtc.dev/taxlocus/apis/taxlocus-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/taxlocus/apis/taxlocus-rest-api/revisions/f3d4b84bdc56?raw)