## Check your email Your trial API key arrives by email at the address you provided. * The key is valid for 30 days. * All test-environment data is automatically deleted after 30 days. * Keep your key safe, and request a new one if you suspect it has been compromised. ## Authenticate and start testing Add your key to the `Authorization` header to authenticate requests — see [Authentication](/guides/authentication) for details. Once you're authenticated, follow the [Quickstart](/guides/quickstart) to run your first tax calculation and post a transaction. # Transaction Object Source: https://developer.zamp.com/guides/understanding-the-transaction-object Understand the Zamp transaction object — the core data structure carrying line items, addresses, and tax details across the API. ## 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** ```text theme={null} id name parentId transactedAt ``` **Properties** ```text theme={null} entity purpose marketplace ``` **Properties** ```text theme={null} recalculate ``` **Properties** ```text theme={null} currency discount subtotal (Deprecated) shipping handling taxCollected total ``` **Properties** ```text theme={null} shipToAddress shipFromAddress ``` **Properties** ```text theme={null} lineItems ``` ### 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](/guides/handling-refunds). 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. `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](/guides/zamp-tax-codes) for a list of Zamp tax codes. # Validating US-Addresses Source: https://developer.zamp.com/guides/validating-us-addresses A built-in address validator for US-based addresses, directly in your platform. ## Overview Zamp leverages the power of address validation platform, [Smarty](https://www.smarty.com/?v2), to validate addresses in the United States. ## Endpoints Used ```text theme={null} POST /addresses ``` ## Validating Customer Address Example Operate an Accounting Platform? Give users the power to validate an address in real-time when creating a new customer. ### Valid Address If `validatedAddress` is NOT `null`, inform the user that the address is valid.

Accuracy you can trust

Experts in your corner

Always ahead

One platform, global reach

Connects to your stack

Built for trust

Build with the API

See Zamp in action

The sales tax API that gets your returns filed

Calculations

Transactions

Addresses

Tax codes

Registrations

Filings

Companies

Full API reference

Start with a free trial

Use your Zamp account