Handling 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

GET | https://api.zamp.com/transactions
POST | https://api.zamp.com/calculations
POST | https://api.zamp.com/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

{
  "id": "REF-123",
  "name": "REF-123",
  "parentId": "123"
}

Handling Refund Transaction Dates

Don’t modify the original sale transaction when issuing refunds. The sales tax from that transaction may have already been filed and remitted.

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
Shipping or Handling were unintentionally charged
Credits are issued to customers

Process for partial refunds:

Issue a GET request to retrieve the original transaction
Subtract taxCollected from total
Retain the taxCollected amount but remove that property from the response
Modify line items, discounts, or quantities as needed; recalculate the total
POST the transformed data to /calculations
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:

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

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.

Sale Transaction Example

{
  "id": "123",
  "name": "INV-123",
  "transactedAt": "2023-07-01T00:00:00.000Z",
  "isResale": false,
  "discount": 2,
  "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

{
  "id": "REF-123-01",
  "name": "REF-INV-123-01",
  "parentId": "123",
  "transactedAt": "2024-01-01T00:00:00.000Z",
  "isResale": false,
  "discount": -2,
  "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"
    }
  ]
}

Non-Item Refunds

For refunds where the line item quantities or amounts were not impacted, they will still need to be included in the calculation and posting request to Zamp.

Shipping-Only Refund

Invalid Request

The below is an example of a request that is invalid, for a shipping-only Refund.

{
  "id": "BADREF-INV-001",
  "name": "BADREF-INV-001",
  "total": -10.76,
  "entity": null,
  "purpose": null,
  "currency": "USD",
  "parentId": "INV-001",
  "lineItems": [], // Transactions with no line items will be rejected
  "taxCollected": -0.76,
  "transactedAt": "2026-09-17 19:26:15",
  "shipToAddress": {
    "zip": "87110",
    "city": "Albuquerque",
    "line1": "6418 Lomas Blvd",
    "line2": null,
    "state": "NM",
    "country": "US"
  },
  "shipping": -10
}

{
  "id": "BADREF-INV-001",
  "name": "BADREF-INV-001",
  "total": -10.76,
  "entity": null,
  "purpose": null,
  "currency": "USD",
  "parentId": "INV-001",
  "lineItems": [], // Transactions with no line items will be rejected
  "taxCollected": -0.76,
  "transactedAt": "2026-09-17 19:26:15",
  "shipToAddress": {
    "zip": "87110",
    "city": "Albuquerque",
    "line1": "6418 Lomas Blvd",
    "line2": null,
    "state": "NM",
    "country": "US"
  },
  "shipping": -10
}

Correct Request

{
    "id": "REF-INV-001",
    "name": "REF-INV-001",
	"parentId": "INV-001",
    "total": -10.76,
    "entity": null,
    "purpose": null,
    "currency": "USD",
    "subtotal": 0,
    "lineItems": [
        {
            "id": "itemId1", // Include the original item
            "amount": 59.2,
            "discount": 0,
            "quantity": 0, // Nothing was refunded, so zero quantity
            "productSku": "productSku1",
            "productName": "Item 1",
            "productTaxCode": "R_TPP",
            "shippingHandling": 0
        }
    ],
    "taxCollected": -0.76,
    "transactedAt": "2026-09-17 19:25:38",
    "shipToAddress": {
        "zip": "87110",
        "city": "Albuquerque",
        "line1": "6418 Lomas Blvd",
        "line2": null,
        "state": "NM",
        "country": "US"
    },
    "shipping": -10
}

{
    "id": "REF-INV-001",
    "name": "REF-INV-001",
	"parentId": "INV-001",
    "total": -10.76,
    "entity": null,
    "purpose": null,
    "currency": "USD",
    "subtotal": 0,
    "lineItems": [
        {
            "id": "itemId1", // Include the original item
            "amount": 59.2,
            "discount": 0,
            "quantity": 0, // Nothing was refunded, so zero quantity
            "productSku": "productSku1",
            "productName": "Item 1",
            "productTaxCode": "R_TPP",
            "shippingHandling": 0
        }
    ],
    "taxCollected": -0.76,
    "transactedAt": "2026-09-17 19:25:38",
    "shipToAddress": {
        "zip": "87110",
        "city": "Albuquerque",
        "line1": "6418 Lomas Blvd",
        "line2": null,
        "state": "NM",
        "country": "US"
    },
    "shipping": -10
}

Tax-Only Refunds

In a scenario where only tax is refunded to a customer, but the order is not, it is recommended your integration recalculates tax to account for the reason why tax refund is initiated. The below outlines a few scenarios that could result in a taxable order into a non-taxable one:

Scenario	Expected Integration Behavior
Incorrect Item Taxability - The items in the order were classified incorrectly, and resulted in tax being charged for non-taxable items.	The original order should be refunded in Zamp using the full refund flow (see above), and the new transaction with the correct Product Tax Codes needs to be passed to Zamp as a replacement.
Exemption Not Applied - Customer is exempt from tax, but was not classified as exempt at the time of order submission.	This can be situationally dependent: Is the correction being made in the same month as the original transaction? Solution: You can update the transaction with the exemption and re-calculate and post the transaction. Does a payment reversal happen for the customer? Solution: Follow the full refund process, and repost the transaction with the exemption correctly assigned.
Incorrect Address -The customer accidentally placed an order to an address that was taxable for their items, and they requested an address change.	The original order should be refunded in Zamp using the full refund flow (see above), and the new transaction with the correct address should be recalculated and reposted to Zamp.

For questions or issues, contact support@zamp.com.

Home

Free Trial

Core Concepts

Workflow Playbooks

API Reference

Integrations

Handling Refunds

Overview

Endpoints Used

Refund and Sale Transaction Relationships

The parentId Property

Handling Refund Transaction Dates

Calculating Sales Tax for Refunds

Whole-Transaction Refunds

Partial-Transaction Refunds

Reporting Refund Transactions

Sale Transaction Example

Refund Transaction Example

Non-Item Refunds

Shipping-Only Refund

Invalid Request

Correct Request

Tax-Only Refunds

​Overview

​Endpoints Used

​Refund and Sale Transaction Relationships

​The parentId Property

​Handling Refund Transaction Dates

​Calculating Sales Tax for Refunds

​Whole-Transaction Refunds

​Partial-Transaction Refunds

​Reporting Refund Transactions

​Sale Transaction Example

​Refund Transaction Example

​Non-Item Refunds

​Shipping-Only Refund

​Invalid Request

​Correct Request

​Tax-Only Refunds

Overview

Endpoints Used

Refund and Sale Transaction Relationships

The parentId Property

Handling Refund Transaction Dates

Calculating Sales Tax for Refunds

Whole-Transaction Refunds

Partial-Transaction Refunds

Reporting Refund Transactions

Sale Transaction Example

Refund Transaction Example

Non-Item Refunds

Shipping-Only Refund

Invalid Request

Correct Request

Tax-Only Refunds