> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling Refunds

> Learn how to handle returns, credit memos, and whole or partial refunds.

# Overview

Refund logic shouldn't be complicated. This guide covers how to handle the various scenarios you may encounter when issuing returns, credit memos, and whole or partial refunds.

Reporting sales creates liability for businesses to taxable jurisdictions, while refund reporting reduces that liability. Accurate refund handling ensures businesses don't overpay taxes.

## Endpoints Used

```text theme={null}
GET /transactions
POST /calculations
POST /transactions
```

## Refund and Sale Transaction Relationships

When creating a refund transaction, the original sale transaction must already exist in Zamp. The sale's original `id` becomes the refund's `parentId`, signaling a refund relationship.

You can name refund transactions flexibly — prepend with identifiers like `CM-*` for credit memos or `REF-*` for refunds. Multiple refunds for a single sale can use incremented suffixes (e.g., `REF-*-01`, `REF-*-02`).

### The parentId Property

| Property   | Type                                    | Description                               |
| ---------- | --------------------------------------- | ----------------------------------------- |
| `parentId` | string (optional, required for refunds) | The original `id` of the sale transaction |

```json theme={null}
{
  "id": "REF-123",
  "name": "REF-123",
  "parentId": "123"
}
```

## Handling Refund Transaction Dates

<Warning>
  Don't modify the original sale transaction when issuing refunds. The sales tax from that transaction may have already been filed and remitted.
</Warning>

Set the refund's `transactedAt` to the date the refund is created. This reduces liability in the current filing period.

## Calculating Sales Tax for Refunds

### Whole-Transaction Refunds

For complete refunds, calculation calls aren't always necessary, though integrations with ERP or accounting systems should consider calling `/calculations`.

### Partial-Transaction Refunds

These occur when:

* One or more line item quantities decrease below original amounts
* Some line items are canceled entirely (but not all)
* Discounts are applied after the original transaction was reported
* Credits are issued to customers

**Process for partial refunds:**

1. Issue a `GET` request to retrieve the original transaction
2. Subtract `taxCollected` from `total`
3. Retain the `taxCollected` amount but remove that property from the response
4. Modify line items, discounts, or quantities as needed; recalculate `subtotal` and `total`
5. `POST` the transformed data to `/calculations`
6. Subtract the calculation response's `taxDue` from the retained `taxCollected`

The difference equals the sales tax owed to the customer.

## Reporting Refund Transactions

Refund transactions use the same endpoints as sales transactions with three key differences:

1. **Accurate identifiers** — unique `id`, `name`, and `parentId`
2. **Correct date** — `transactedAt` should reflect the refund date, not the sale date
3. **Negative values** — convert all positive floating-point numbers to negative

<Warning>
  **Never** pass a `lineItems[*].amount` property that is negative. Indicate a credit by reducing its `quantity` from the original sale. The `amount` stays positive; only the `quantity` becomes negative.
</Warning>

### Sale Transaction Example

```json theme={null}
{
  "id": "123",
  "name": "INV-123",
  "transactedAt": "2023-07-01T00:00:00.000Z",
  "isResale": false,
  "discount": 2,
  "subtotal": 18,
  "shippingHandling": 5,
  "taxCollected": 2.25,
  "total": 25.25,
  "shipToAddress": {
    "line1": "120 SW 10TH AVE",
    "line2": null,
    "state": "KS",
    "city": "TOPEKA",
    "zip": "66612"
  },
  "lineItems": [
    {
      "id": "LI-123",
      "amount": 10,
      "quantity": 2,
      "discount": 0,
      "shippingHandling": 0,
      "productName": "The Ultimate Sampler",
      "productSku": "SAMPLER-100",
      "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
    }
  ]
}
```

### Refund Transaction Example

```json theme={null}
{
  "id": "REF-123-01",
  "name": "REF-INV-123-01",
  "parentId": "123",
  "transactedAt": "2024-01-01T00:00:00.000Z",
  "isResale": false,
  "discount": -2,
  "subtotal": -18,
  "shippingHandling": -5,
  "taxCollected": -2.25,
  "total": -25.25,
  "shipToAddress": {
    "line1": "120 SW 10TH AVE",
    "line2": null,
    "state": "KS",
    "city": "TOPEKA",
    "zip": "66612"
  },
  "lineItems": [
    {
      "id": "LI-123",
      "amount": 10,
      "quantity": -2,
      "discount": 0,
      "shippingHandling": 0,
      "productName": "The Ultimate Sampler",
      "productSku": "SAMPLER-100",
      "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
    }
  ]
}
```

For questions or issues, contact [support@zamp.com](mailto:support@zamp.com).