Transactions

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

The Transaction Object

Core Properties

string

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. 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 (optional, default: false)

deprecated

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

string (Optional)

Customer’s entity exemption type: EDU_PRIVATE, EDU_PUBLIC, FEDERAL_GOV, LOCAL_GOV, NON_PROFIT, STATE_GOV, TRIBAL

string (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

number (Optional)

deprecated

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

number (Optional)

Transaction-level shipping

number (Optiona)

Transaction-level handling

number (Optional)

Combined shipping/handling

number

required

Actual tax collected amount

number

required

Total including tax and shipping / handling

address (optional)

Where transaction physically shipped from

address

required

Where shipped to or point of sale

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

Street address

string (Optional)

Additional address info

string

City name

string

Two-letter state code

string

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

string (Optional)

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

Line Item Properties

string

required

Unique line item identifier

number

required

Amount per unit

number

required

Number of units

number (Optional)

Line-item level discount

number (Optional)

Line-item level shipping

number (Optional)

Line-item level handling

number (Optional)

Combined line-item shipping/handling

string

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.

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

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

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

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

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

Core Concepts

Workflow Playbooks

API Reference

Integrations

Transactions

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

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