Transactions

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

The Transaction Object

Core Properties

Property	Type	Description
`id`	string	Unique identifier for the transaction
`name`	string (optional)	Friendly identifier (e.g., invoice number)
`parentId`	string (optional)	Required for refund transactions; references original transaction `id`
`transactedAt`	datetime (ISO-8601)	Timestamp when transaction occurred
`recalculate`	boolean (optional, default: false)	If false, uses provided `taxCollected` amount instead of calculating
`isResale`	boolean (optional, deprecated)	Whether the transaction is for resale. Use `RESALE` on `purpose` instead
`marketplace`	string (optional)	Marketplace facilitator that collected payment and assumed sales tax responsibility
`entity`	string (optional)	Customer’s entity exemption type
`purpose`	string (optional)	Purpose for sale: `BUSINESS_USE`, `PERSONAL_USE`, `RENTAL_USE`, `RESALE`
`currency`	string (optional, default: USD)	ISO-4217 currency code
`discount`	number (optional)	Transaction-level discount
`subtotal`	number	Total excluding tax and shipping/handling
`shipping`	number (optional)	Transaction-level shipping
`handling`	number (optional)	Transaction-level handling
`shippingHandling`	number (optional)	Combined shipping/handling
`taxCollected`	number (optional)	Actual tax collected amount
`total`	number	Total including tax and shipping/handling
`shipFromAddress`	address (optional)	Where transaction physically shipped from
`shipToAddress`	address	Where shipped to or point of sale
`lineItems`	array (min 1)	Line item details
`metadata`	object (optional)	Custom key-value pairs (max 50, keys 1-40 chars, values 1-500 chars)

Address Object

Property	Type	Description
`line1`	string	Street address
`line2`	string (optional)	Additional address info
`city`	string	City name
`state`	string	Two-letter state code
`zip`	string	Format: `#####` or `#####-####`
`country`	string (optional)	ISO-3166 Alpha-2 code

Line Item Properties

Property	Type	Description
`id`	string	Unique line item identifier
`amount`	number	Amount per unit
`quantity`	number	Number of units
`discount`	number (optional)	Line-item level discount
`shipping`	number (optional)	Line-item level shipping
`handling`	number (optional)	Line-item level handling
`shippingHandling`	number (optional)	Combined line-item shipping/handling
`productName`	string	Product description
`productSku`	string (optional)	Product identifier
`productTaxCode`	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.

Entity Exemption Types

EDU_PRIVATE, EDU_PUBLIC, FEDERAL_GOV, LOCAL_GOV, NON_PROFIT, STATE_GOV, TRIBAL

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

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,
  "subtotal": 18,
  "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"
  },
  "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

limit

integer

default:"10"

Number of items to return (1-100)

cursor

string

Pagination cursor from a previous nextCursor

minTransactedAt

datetime

Exclude transactions before this timestamp

maxTransactedAt

datetime

Exclude transactions after this timestamp

Request

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 /transactions

POST /transactions

curl -X POST https://api.zamp.com/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "123",
    "name": "INV-123",
    "transactedAt": "2023-07-01T00:00:00.000Z",
    "isResale": false,
    "currency": "USD",
    "discount": 2,
    "subtotal": 18,
    "shippingHandling": 5,
    "taxCollected": 2.25,
    "total": 25.25,
    "shipToAddress": {
      "line1": "120 SW 10TH AVE",
      "state": "KS",
      "city": "TOPEKA",
      "zip": "66612"
    },
    "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 transaction plus taxDue and the itemized taxes breakdown. When taxCollected is provided, it is allocated across each jurisdiction entry.

200

{
  "id": "123",
  "name": "INV-123",
  "taxDue": 1.58,
  "taxes": [
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.S.20",
      "jurisdictionName": "KANSAS",
      "jurisdictionDivision": "STATE",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": null,
      "taxableAmount": 18,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.04,
      "taxDue": 0.72,
      "taxCollected": 1.01
    },
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.S.20",
      "jurisdictionName": "KANSAS",
      "jurisdictionDivision": "STATE",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": "SHIPPING_HANDLING",
      "taxableAmount": 5,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.04,
      "taxDue": 0.2,
      "taxCollected": 0.29
    },
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.C.177",
      "jurisdictionName": "SHAWNEE COUNTY",
      "jurisdictionDivision": "COUNTY",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": null,
      "taxableAmount": 18,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.0135,
      "taxDue": 0.243,
      "taxCollected": 0.35
    },
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.C.177",
      "jurisdictionName": "SHAWNEE COUNTY",
      "jurisdictionDivision": "COUNTY",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": "SHIPPING_HANDLING",
      "taxableAmount": 5,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.0135,
      "taxDue": 0.0675,
      "taxCollected": 0.1
    },
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.I.71000",
      "jurisdictionName": "TOPEKA CITY",
      "jurisdictionDivision": "CITY",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": null,
      "taxableAmount": 18,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.015,
      "taxDue": 0.27,
      "taxCollected": 0.39
    },
    {
      "lineItemId": "LI-123",
      "state": "KS",
      "sourcing": "INTER_DESTINATION",
      "jurisdictionCode": "KS.I.71000",
      "jurisdictionName": "TOPEKA CITY",
      "jurisdictionDivision": "CITY",
      "compositeCode": "SNTOP",
      "compositeName": "TOPEKA",
      "exceptionCode": "FOOD_SUPPLEMENTS",
      "ancillaryType": "SHIPPING_HANDLING",
      "taxableAmount": 5,
      "nontaxableAmount": 0,
      "excludedAmount": 0,
      "taxRate": 0.015,
      "taxDue": 0.075,
      "taxCollected": 0.11
    }
  ]
}

Create a Refund Transaction

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

Request

POST /transactions

curl -X POST https://api.zamp.com/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "REF-123-01",
    "name": "REF-INV-123-01",
    "parentId": "123",
    "transactedAt": "2024-01-01T00:00:00.000Z",
    "isResale": false,
    "currency": "USD",
    "discount": -2,
    "subtotal": -18,
    "shippingHandling": -5,
    "taxCollected": -2.25,
    "total": -25.25,
    "shipToAddress": {
      "line1": "120 SW 10TH AVE",
      "state": "KS",
      "city": "TOPEKA",
      "zip": "66612"
    },
    "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-123-01",
  "parentId": "123",
  "name": "REF-INV-123-01",
  "transactedAt": "2024-01-01T00:00:00.000Z",
  "purpose": null,
  "entity": null,
  "currency": "USD",
  "discount": -2,
  "subtotal": -18,
  "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"
  },
  "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"
    }
  ],
  "taxDue": 0,
  "taxes": []
}

Retrieve a Transaction

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 /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/:id

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

​The Transaction Object

​Core Properties

​Address Object

​Line Item Properties

​Entity Exemption Types

​Marketplace Values

​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

The Transaction Object

Core Properties

Address Object

Line Item Properties

Entity Exemption Types

Marketplace Values

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