Transactions

Persist transactions after taxes have been calculated and the transaction is processed in your system.

The Transaction Object

Core Properties

string, 25-character limit

required

Unique identifier for the transaction

string (Optional)

Friendly identifier (e.g., invoice number)

string (Optional)

Required for refund transactions; references original transaction id

datetime (ISO-8601)

required

Timestamp when transaction occurred in UTC. Can be in the past which will use historical rates (from 2023 and on), or the future, which will use the current date’s tax rates and rules.

boolean

default:"false"

Indicates whether Zamp will recalculate tax when a transaction is posted to Zamp

string (Optional)

Marketplace facilitator that collected payment and assumed sales tax responsibility

enum (Optional)

Customer’s entity type: EDU_PRIVATE, EDU_PUBLIC, EDUCATIONAL, FEDERAL_GOV, LOCAL_GOV, NON_PROFIT, STATE_GOV, TRIBAL , WHOLESALER, MANUFACTURER, SNAP, INDUSTRIAL_PROCESSING, LESSOR, AGRICULTURAL, MEDICAL, RELIGIOUS, DATA_CENTER, DIRECT_PAY , RESELLER

enum (Optional)

Purpose for sale: BUSINESS_USE, PERSONAL_USE, RENTAL_USE, RESALE

ISO-4217 currency code

default:"USD"

The currency of the transaction.

This must match the destination country if Zamp is filing the return

number (Optional)

Transaction-level discount. Only supports financially viable / rounded amounts (e.g. $10.30)

number (Optional)

deprecated

Total excluding tax and shipping/handling. This is no longer required

number (Optional)

Transaction-level shipping. Only supports financially viable / rounded amounts (e.g. $10.30)

number (Optiona)

Transaction-level handling. Only supports financially viable / rounded amounts (e.g. $10.30)

number (Optional)

Combined shipping/handling. Only supports financially viable / rounded amounts (e.g. $10.30)

number

required

Actual tax collected amount. Only supports financially viable / rounded amounts (e.g. $10.30)

number

required

Total including tax and shipping / handling. Only supports financially viable / rounded amounts (e.g. $10.30)

address (optional)

Where the transaction physically shipped from

address or coordinates

required

Where the transaction was shipped to or the point of sale location

array (Minimum 1)

required

Line item details

object (Optional)

Custom key-value pairs (max 50, keys 1-40 chars, values 1-500 chars)

Address Object

string, 2000-character limit

Street address

string (Optional) , 2000-character limit

Additional address info

string

City name

string

Two-letter state code

string

Format: ##### or #####-####

string (Optional)

ISO-3166 Alpha-2 code (Default, US)

json (optional)

Latitude and Longitude. Only available for the destination address. Will be returned on all posted transaction responses

Line Item Properties

string, 25-character limit

required

Unique line item identifier

number

required

Amount per unit. Supports up to 4-decimal places.

number

required

Number of units

number (Optional)

Line-item level discount. Supports up to 4-decimal places.

number (Optional)

Line-item level shipping. Supports up to 4-decimal places.

number (Optional)

Line-item level handling. Supports up to 4-decimal places.

number (Optional)

Combined line-item shipping/handling. Supports up to 4-decimal places.

string, 2000-character limit

required

Product description

string (Optional)

Product identifier

string (Optional)

Zamp tax code for product taxability

For point-of-sale orders, set shipFromAddress and shipToAddress to identical values.
Prefer separate shipping and handling amounts; use shippingHandling only if combined.
Updates/deletions for transactions in closed filing periods are forbidden.
Transactions created with transactedAt in closed periods auto-adjust to current time.
If lineItems.amount or any amounts at the line-item level are unrounded, the transaction-level values must be rounded after determining the line-item cost.

Entity Exemption Types

EDU_PRIVATE, EDU_PUBLIC, FEDERAL_GOV, NON_PROFIT, STATE_GOV , RESELLER

Other Entity Types

WHOLESALER, MANUFACTURER, SNAP, INDUSTRIAL_PROCESSING, LESSOR, AGRICULTURAL, MEDICAL, RELIGIOUS, DATA_CENTER, DIRECT_PAY , TRIBAL , LOCAL_GOV

Marketplace Values

ALIBABA, AMAZON, APPLE, BEST_BUY, COSTCO, EBAY, ETSY, EVENTBRITE, FLIP, GOOGLE, GUNBROKER, LOWES, MACYS, META, MIRAKL, NEWEGG, NINTENDO, OVERSTOCK, POSHMARK, REVERB, SHOP, SONY, TARGET_PLUS, TIKTOK, WALMART, WAYFAIR

Purpose Types

RESALE , BUSINESS_USE, PERSONAL_USE, RENTAL_USE

Example

The transaction object is the standard request shape across both the /transactions and /calculations endpoints.

{
  "id": "123",
  "name": "INV-123",
  "parentId": null,
  "transactedAt": "2023-07-01T00:00:00.000Z",
  "marketplace": "AMAZON",
  "entity": null,
  "purpose": null,
  "currency": "USD",
  "discount": 2,
  "shipping": 3,
  "handling": 2,
  "taxCollected": 2.25,
  "total": 27.25,
  "shipFromAddress": {
    "line1": "2000 W WASHINGTON ST",
    "line2": null,
    "city": "PHOENIX",
    "state": "AZ",
    "zip": "85009-5207"
  },
  "shipToAddress": {
    "line1": "120 SW 10TH AVE",
    "line2": null,
    "state": "KS",
    "city": "TOPEKA",
    "zip": "66612",
	"coordinates": null
  },
  "lineItems": [
    {
      "id": "LI-123",
      "amount": 10,
      "quantity": 2,
      "discount": 0,
      "shipping": 1.5,
      "handling": 0.5,
      "productName": "The Ultimate Sampler",
      "productSku": "SAMPLER-100",
      "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
    }
  ],
  "metadata": {
    "version": "1.0.0"
  }
}

List All Transactions

integer

default:"10"

Number of items to return (1-100)

string

Pagination cursor from a previous nextCursor

datetime

Exclude transactions before this timestamp

datetime

Exclude transactions after this timestamp

Request

GET | https://api.zamp.com/transactions

Keep in mind that this endpoint will only return transactions associated with that API key, not all transactions for a company.

GET /transactions

curl -G https://api.zamp.com/transactions \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

200

{
  "nextCursor": "x4WycXedwhQrEFuM",
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "taxDue": 2.18,
      "taxes": []
    }
  ]
}

Create a Transaction

Creates a new transaction. Uses the same request/response format as the Calculations endpoint.

Request

POST | https://api.zamp.com/transactions

POST /transactions

curl -X POST https://api.zamp.com/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "12345",
    "name": "INV-12345",
    "transactedAt": "2026-10-21T00:00:00.000Z",
    "isResale": false,
    "currency": "USD",
    "discount": 2,
    "shippingHandling": 5,
    "taxCollected": 2.25,
    "total": 25.25,
    "shipToAddress": {
      "line1": "120 SW 10TH AVE",
      "state": "KS",
      "city": "TOPEKA",
      "zip": "66612",
      "coordinates": null
    },
    "lineItems": [
      {
        "id": "LI-123",
        "amount": 10,
        "quantity": 2,
        "productName": "The Ultimate Sampler",
        "productSku": "SAMPLER-100",
        "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
      }
    ],
    "metadata": {
      "version": "1.0.0"
    }
  }'

Response

Returns the original transaction plus taxDue and the itemized taxes breakdown. When taxCollected is provided, it is allocated across each jurisdiction entry.

200

{
    "id": "12345",
    "parentId": null,
    "name": "INV-12345",
    "transactedAt": "2026-10-21T00:00:00.000Z",
    "isResale": false,
    "marketplace": null,
    "entity": null,
    "purpose": null,
    "recalculate": false,
    "currency": "USD",
    "discount": 2,
    "subtotal": 18,
    "shipping": 0,
    "handling": 0,
    "shippingHandling": 5,
    "taxCollected": 2.25,
    "total": 25.25,
    "shipFromAddress": null,
    "shipToAddress": {
        "line1": "120 SW 10TH AVE",
        "line2": null,
        "city": "TOPEKA",
        "state": "KS",
        "zip": "66612",
        "country": "US",
        "coordinates": {
            "latitude": 39.046528,
            "longitude": -95.676529
        }
    },
    "lineItems": [
        {
            "id": "LI-123",
            "amount": 10,
            "quantity": 2,
            "discount": 0,
            "shipping": 0,
            "handling": 0,
            "shippingHandling": 0,
            "productName": "The Ultimate Sampler",
            "productSku": "SAMPLER-100",
            "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
        }
    ],
    "metadata": {
        "version": "1.0.0"
    },
    "taxDue": 2.25,
    "taxes": [
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.S.20",
            "jurisdictionName": "KANSAS",
            "jurisdictionDivision": "STATE",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": 0,
            "nontaxableAmount": 78.95,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.S.20",
            "jurisdictionName": "KANSAS",
            "jurisdictionDivision": "STATE",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": 21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.C.177",
            "jurisdictionName": "SHAWNEE COUNTY",
            "jurisdictionDivision": "COUNTY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": 78.95,
            "nontaxableAmount": 0,
            "excludedAmount": 0,
            "taxRate": 0.0135,
            "taxDue": 1.07,
            "taxCollected": 1.07
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.C.177",
            "jurisdictionName": "SHAWNEE COUNTY",
            "jurisdictionDivision": "COUNTY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": 21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.I.71000",
            "jurisdictionName": "TOPEKA CITY",
            "jurisdictionDivision": "CITY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": 78.95,
            "nontaxableAmount": 0,
            "excludedAmount": 0,
            "taxRate": 0.015,
            "taxDue": 1.18,
            "taxCollected": 1.18
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.I.71000",
            "jurisdictionName": "TOPEKA CITY",
            "jurisdictionDivision": "CITY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": 21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        }
    ]
}

Create a Refund Transaction

Creates a refund transaction linked to the original via parentId. See the Handling Refunds guide for details.

Request

POST | https://api.zamp.com/transactions

POST /transactions

curl -X POST https://api.zamp.com/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "REF-12345-01",
    "name": "REF-INV-12345-01",
    "parentId": "12345",
    "transactedAt": "2026-10-21T00:00:00.000Z",
    "isResale": false,
    "currency": "USD",
    "discount": -2,
    "shippingHandling": -5,
    "taxCollected": -2.25,
    "total": -25.25,
    "shipToAddress": {
      "line1": "120 SW 10TH AVE",
      "state": "KS",
      "city": "TOPEKA",
      "zip": "66612",
	  "coordinates": null
    },
    "lineItems": [
      {
        "id": "LI-123",
        "amount": 10,
        "quantity": -2,
        "productName": "The Ultimate Sampler",
        "productSku": "SAMPLER-100",
        "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
      }
    ]
  }'

Response

A refund reduces previously reported liability, so the negative amounts net against the original transaction. taxDue is 0 and taxes is empty when the refund fully offsets the original.

200

{
    "id": "REF-12345-01",
    "parentId": "12345",
    "name": "REF-INV-12345-01",
    "transactedAt": "2026-10-21T00:00:00.000Z",
    "isResale": false,
    "marketplace": null,
    "entity": null,
    "purpose": null,
    "recalculate": false,
    "currency": "USD",
    "discount": -2,
    "subtotal": -18,
    "shipping": 0,
    "handling": 0,
    "shippingHandling": -5,
    "taxCollected": -2.25,
    "total": -25.25,
    "shipFromAddress": null,
    "shipToAddress": {
        "line1": "120 SW 10TH AVE",
        "line2": null,
        "city": "TOPEKA",
        "state": "KS",
        "zip": "66612",
        "country": "US",
        "coordinates": {
            "latitude": 39.046528,
            "longitude": -95.676529
        }
    },
    "lineItems": [
        {
            "id": "LI-123",
            "amount": 10,
            "quantity": -2,
            "discount": 0,
            "shipping": 0,
            "handling": 0,
            "shippingHandling": 0,
            "productName": "The Ultimate Sampler",
            "productSku": "SAMPLER-100",
            "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
        }
    ],
    "metadata": null,
    "taxDue": -2.25,
    "taxes": [
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.S.20",
            "jurisdictionName": "KANSAS",
            "jurisdictionDivision": "STATE",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": 0,
            "nontaxableAmount": -78.95,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.S.20",
            "jurisdictionName": "KANSAS",
            "jurisdictionDivision": "STATE",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": -21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.C.177",
            "jurisdictionName": "SHAWNEE COUNTY",
            "jurisdictionDivision": "COUNTY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": -78.95,
            "nontaxableAmount": 0,
            "excludedAmount": 0,
            "taxRate": 0.0135,
            "taxDue": -1.07,
            "taxCollected": -1.07
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.C.177",
            "jurisdictionName": "SHAWNEE COUNTY",
            "jurisdictionDivision": "COUNTY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": -21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.I.71000",
            "jurisdictionName": "TOPEKA CITY",
            "jurisdictionDivision": "CITY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "FOOD_SUPPLEMENTS",
            "ancillaryType": null,
            "taxableAmount": -78.95,
            "nontaxableAmount": 0,
            "excludedAmount": 0,
            "taxRate": 0.015,
            "taxDue": -1.18,
            "taxCollected": -1.18
        },
        {
            "lineItemId": "LI-123",
            "state": "KS",
            "sourcing": "INTRA_DESTINATION",
            "jurisdictionCode": "KS.I.71000",
            "jurisdictionName": "TOPEKA CITY",
            "jurisdictionDivision": "CITY",
            "compositeCode": "SNTOP",
            "compositeName": "TOPEKA",
            "exceptionCode": "SHIPPING_HANDLING",
            "ancillaryType": "SHIPPING_HANDLING",
            "taxableAmount": 0,
            "nontaxableAmount": -21.93,
            "excludedAmount": 0,
            "taxRate": 0,
            "taxDue": 0,
            "taxCollected": 0
        }
    ]
}

Retrieve a Transaction

GET | https://api.zamp.com/transactions/:id

GET /transactions/:id

curl https://api.zamp.com/transactions/123 \
  -H "Authorization: Bearer {token}"

Response

Returns the transaction object plus taxDue and the full itemized taxes breakdown (same shape as the Create a Transaction response).

200

{
  "id": "123",
  "name": "INV-123",
  "taxDue": 1.58,
  "taxes": [
    // itemized per-jurisdiction breakdown — see "Create a Transaction"
  ]
}

Update a Transaction

Updates a transaction by replacing the prior version with the same ID. Requires all transaction properties.

PUT | https://api.zamp.com/transactions

PUT /transactions/:id

curl -X PUT https://api.zamp.com/transactions/123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Delete a Transaction

Permanently deletes a transaction and all related tax information.

DELETE /transactions

DELETE /transactions/:id

curl -X DELETE https://api.zamp.com/transactions/123 \
  -H "Authorization: Bearer {token}"

Home

Free Trial

Core Concepts

Workflow Playbooks

API Reference

Integrations

Transactions

The Transaction Object

Core Properties

Address Object

Line Item Properties

Entity Exemption Types

Other Entity Types

Marketplace Values

Purpose Types

Example

List All Transactions

Request

Response

Create a Transaction

Request

Response

Create a Refund Transaction

Request

Response

Retrieve a Transaction

Response

Update a Transaction

Delete a Transaction