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

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

{
  "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
• 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

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,
  "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

{
  "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 [e-mail].