Skip to main content

​
Overview

The Transaction Object is a core component of an integration with Zamp. It will contain all of the information for a given customer’s transaction, and will be used to both calculate taxes through Zamp’s tax engine and post transactions.

​
Key Elements

Properties
Properties
Properties
Properties
Properties
Properties

​
Transaction Identifiers

Transaction Identifiers serve two primary uses. One use is to serve as an identifier on your platform, and the other is to identify transactions within Zamp. You have a few options to use as identifiers:
Properties
id - This is the only required identifier for transactions to be posted to Zamp. It must be a unique string for the company account the transaction is posted for. name - This is an optional identifier that can be used for your internal ID or a customer’s invoice ID (an example). parentId - This is a special-use ID for refunds. It is highly recommended you leverage this ID for refund transactions. It is notably used to link the refund transaction to the original transaction. transactedAt - This will be the date and time of the transaction. A timestamp being set in a closed filing period (i.e. the transaction has already been filed by Zamp), it will be auto-adjusted to the current date and time.
Key Notes
  • In the Zamp Transactions Dashboard, the ID displayed for each transaction is by default, the name passed in the transaction. If none is passed, it will display your passed id.
  • Transactions can be posted into the future, but they will use the current date’s tax rules and rates, which are subject to change.
Taxes calculated for a transaction dated in the future may be stale by the time the transaction is filed. It is NOT recommended that users consistently send transactions in the future.

​
Transaction Classifications and Exemptions

For multi-channel sellers, sellers subject to Marketplace Facilitator Rules, or businesses selling to exempt customers, classifying transactions accordingly will guarantee accurate tax calculations and liability remittance.
Properties
entity - Eligible tax exempt customers need to be tagged appropriately in your UI, and will need to be passed to Zamp on transaction posting. Additionally, there are other entity types that can impact how data is filed. purpose - Tax Exemptions at the transaction level should be tagged in this field.  marketplace - If a sale occurs on a marketplace where the marketplace is responsible for collecting tax, tax will be $0.00 for any given transaction. This field is only required for those transactions.
Key Notes
  • Zamp supports the ability to handle transactions with resale and non-resale line items. See the Exemption Workflow Documentation.
  • Zamp offers an Exemption Certificate Management System within your Zamp account. Reach out to directly to your Zamp contact to enable this functionlaity.

​
Enabling or Disabling the Zamp Tax Engine Calculation

To allow for maximum flexibility, Zamp does not need to calculate on all transactions. Choose how and when Zamp calculates on your transactions.
Properties
recalculate - This boolean field determines whether Zamp will use its tax engine to determine tax liability based on the information within the Transaction Object. This is especially important when posting transactions to Zamp.
Use Cases
  • For a customer selling on multiple platforms, there are scenarios where they would not want Zamp to calculate taxes on a transaction where taxes have already been calculated. Disabling recalculate would be a solution to this scenario.
    Even when disabling recalculation, Zamp Product Tax Codes should still be mapped to items.
  • If you pass a taxCollected value and do not wish to have Zamp validate the amounts via a recalculation, leave this boolean as false. 
Key Notes
  • By default, the flag is set to false, indicating that Zamp will NOT calculate taxes on the transaction.
  • When building in functionality to disable this toggle (setting the flag to false), ensure your users are informed that Zamp will not be calculating taxes on those transactions.

​
Transaction Origin and Destination

As businesses continue to sell to customers around the United States and the rest of the world, the taxability of goods and services can depend on where a customer is located, or where the seller is located. It is important to provide Zamp both the shipping address of the business (shipFromAddress), and the shipping address of the customer (shipToAddress). Zamp will handle the rest.
Properties
shipFromAddress - This is where the good or service was physically shipped from, not the seller’s address (if different). The origin address is optional, but recommended. shipToAddress -  A destination address is required by Zamp at a bare minimum. This can either be a standard address format (street, city, state, zip-code), or in Latitudinal and Longitudinal coordinates.
Key Notes
  • If using a standard address format, either a Zip code OR a City and State are required to post transactions to Zamp. If both are missing, Zamp will return a 400 error.
  • Do NOT return empty strings for address fields. If you are omitting information within an address, pass null, as empty strings will result in a 400 error from Zamp.
  • If providing GPS coordinates for a destination address, you can also provide standard address data for Zamp to confirm they match.

​
Line Item and Taxability Information

Every transaction requires at least one line item. There are key elements within each line item which ensure accurate taxation of what is being sold.
Properties
lineItems - At least one is required, but add a new lineItem array for every line item.  lineItems.id - A required identifier that needs to be unique for the transaction itself. It can be duplicated across other transactions. lineItems.amount - The cost of this item. Can support up to 4-decimal places. lineItems.quantity - How many of this item were sold in this transaction? lineItems.discount - Pass this amount if there is a discount for this particular line item. Can support up to 4-decimal places. lineItems.shipping - Only relevant if item-level shipping costs are applicable. Can support up to 4-decimal places. lineItems.handling - Only relevant if item-level handling costs are applicable. Can support up to 4-decimal places. lineItems.shippingHandling - Only relevant if item-level aggregate shipping and handling costs are applicable, and they are taxed differently. Can support up to 4-decimal places. lineItems.productName - This is a required field that can be the name of your product, or a description of the product. lineItems.productSku - If your item has a SKU in your database, you can pass it here. It is not required. lineItems.productTaxCode - For virtually all transactions, Product Tax Codes are the foundation of calculating taxes accurately for orders. Zamp has a library of over 130 unique tax codes that cover all possible product types and scenarios. Each of your items should have a tax code assigned. See here for a list of Zamp tax codes.
Last modified on October 15, 2026