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.

​
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.

​
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. 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 does not currently have an Exemption Certificate Management System. While it is in-development, exemptions certificates will need to be maintained by your team in the interim.

​
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.
  • 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.

​
Key Notes

  • 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.

​
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. 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. lineItems.shipping - Only relevant if item-level shipping costs are applicable. lineItems.handling - Only relevant if item-level handling costs are applicable. lineItems.shippingHandling - Only relevant if item-level aggregate shipping and handling costs are applicable, and they are taxed differently. 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.