Transactions

These endpoints handle persisting transactions. Once you've calculated taxes and processed the transaction in your system, you'll want to create a corresponding transaction in Zamp. Then later, if that transaction changes, you can update or delete the transaction to ensure things stay in sync.

The transaction object

A transaction object contains all the details needed to calculate sales tax for an order or invoice using the Zamp API. It's the standard request shape across both the /transactions and /calculations endpoints.

Properties

Name
id
Type
string
Unique identifier for the transaction.
Name
name
Type
string (optional)
Friendly identifier for the transaction, ex: an invoice number.
Name
parentId
Type
string (optional)
Used and required for refund transactions only. The transaction identifier of the original transaction ("id" property).
Name
transactedAt
Type
datetime (ISO-8601)
Timestamp when the transaction occurred.
Name
recalculate
Type
boolean (optional, default=true)
If set to false, we will use the taxCollected amount provided to generate the tax details, otherwise Zamp's tax engine will calculate the tax details. This can lead to incongruencies between the tax collected amount and the actual tax that will be filed. You should only set this to false if you fully understand what the impacts are.
Name
isResale
deprecated
Type
boolean (optional)
Whether the transaction purpose is for resale.
Use "RESALE" option on Purpose instead.
Name
marketplace
Type
string (optional)
Description
Marketplace facilitator that collected payment and assumed sales tax responsibility for this transaction. When set, tax collected should be $0.
＋ Show allowed values
Name
entity
Type
string (optional)
A customer's entity exemption type for the transaction, if applicable.
＋ Show allowed values
Name
purpose
Type
string (optional)
The purpose for the sale of the transaction.
＋ Show allowed values
Name
discount
Type
number (optional)
Transaction level discount (excludes line-item level).
Name
subtotal
Type
number
Total excluding tax collected and shipping/handling.
Name
shippingHandling
Type
number (optional)
Transaction level shipping/handling (excludes line-item level).
Name
taxCollected
Type
number (optional)
Actual amount of tax collected.
Name
total
Type
number
Total including tax collected and shipping/handling.
Name
shipFromAddress
Type
address (optional)
Description
Address where transaction physically shipped from (not selling address).
＋ Show child properties
Name
shipToAddress
Type
address
Description
Address where transaction is shipped to or the point of sale.
＋ Show child properties
Name
lineItems
Type
array (minimum 1)
＋ Show child properties
Name
metadata
Type
object (optional)
Lets you store more information, structured as key-value pairs, for your own use and reference.
＋ Show child properties

For point-of-sale orders, the shipFromAddress and shipToAddress should be set to the same values.

Example: transaction object

{
  "id": "123",
  "name": "INV-123",
  "parentId": null,
  "transactedAt": "2023-07-01T00:00:00.000Z",
  "marketplace": "AMAZON",
  "entity": null,
  "purpose": null,
  "discount": 2,
  "subtotal": 18,
  "shippingHandling": 5,
  "taxCollected": 2.25,
  "total": 25.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,
      "shippingHandling": 0,
      "productName": "The Ultimate Sampler",
      "productSku": "SAMPLER-100",
      "productTaxCode": "R_TPP_FOOD-BEVERAGE_HOME-CONSUMPTION"
    }
  ],
  "metadata": {
    "version": "1.0.0"
  }
}

GET/transactions

List all transactions

This endpoint allows you to retrieve a paginated list of your API transactions.

Query params

Name
limit
Type
integer between 1–100 (optional, default=10)
Limit the number of items returned.
Name
cursor
Type
string (optional)
Cursor returned from a previous response (nextCursor) that's used to load the next page. A null value indicates no more pages.
Name
minTransactedAt
Type
datetime (optional, ISO-8601)
Exclude transactions with a transactedAt before this timestamp.
Name
maxTransactedAt
Type
datetime (optional, ISO-8601)
Exclude transactions with a transactedAt after this timestamp.

All responses include the transaction object along with two additional calculated properties: taxDue and taxes.

Request

GET

/transactions

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

Response

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

POST/transactions

Create a transaction

This endpoint creates a new transaction. It has the same request/response as the /calculations endpoint, but is intended for committing the transaction after the transaction is processed.

Request

Name
transaction
Type
transaction
The transaction object to calculate taxes for.

Response

Name
...
Type
transaction
The transaction object provided to the calculation.
Name
taxDue
Type
number
Tax amount that should be collected on transaction.
Name
taxes
Type
array
Breakdown of calculated taxes.

Request

POST

/transactions

{
  "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"
    }
  ],
  "metadata": {
    "version": "1.0.0"
  }
}

Response

{
  "id": "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
    }
  ]
}

POST/transactions

Create a refund transaction

This endpoint creates a refund transaction. It has the same request/response as the /calculations endpoint but is intended for committing a refund to a transaction that exists in Zamp. For more information, see our guide on handling refunds.

Request

Name
transaction
Type
transaction
The transaction object to calculate taxes for.

Response

Name
...
Type
transaction
The refund transaction object provided to the calculation.

Request

POST

/transactions

{
  "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"
    }
  ],
  "metadata": {
    "version": "1.0.0"
  }
}

Response

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

GET/transactions/:id

Retrieve a transaction

This endpoint allows you to retrieve a transaction with taxes by providing the transaction ID. Refer to the transaction object at the top of this page to see all properties are included with transaction objects.

Request

GET

/transactions/123

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

Response

{
  "id": "123",
  // ...
  "taxDue": 1.58,
  "taxes": [
    // ...
  ]
}

PUT/transactions/:id

Update a transaction

This endpoint allows you to perform an update on a transaction. An update requires all the same properties as create and will effectively replace the prior version of the transaction with the same ID.

Request

Name
transaction
Type
transaction
The transaction object to calculate taxes for.

Response

Name
...
Type
transaction
The transaction object provided to the calculation.
Name
taxDue
Type
number
Tax amount that should be collected on transaction.
Name
taxes
Type
array
Breakdown of calculated taxes.

Request

PUT

/transactions/123

{
  "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"
    }
  ],
  "metadata": {
    "version": "1.0.0"
  }
}

Response

{
  "id": "123",
  // ...
  "taxDue": 1.58,
  "taxes": [
    // ...
  ]
}

DELETE/transactions/:id

Delete a transaction

This endpoint allows you to delete a transaction from the Zamp API. Note: This will permanently delete the transaction and all of its related taxes.

Request

DELETE

/transactions/123

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