> ## Documentation Index > Fetch the complete documentation index at: https://developer.zamp.com/llms.txt > Use this file to discover all available pages before exploring further. # Transactions > Create, retrieve, update, and delete transactions for tax filing. Persist transactions after taxes have been calculated and the transaction is processed in your system. ## The Transaction Object ### Core Properties Unique identifier for the transaction Friendly identifier (e.g., invoice number) Required for refund transactions; references original transaction `id` 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 Indicates whether Zamp will recalculate tax when a transaction is posted to Zamp Marketplace facilitator that collected payment and assumed sales tax responsibility Customer’s entity exemption type: `EDU_PRIVATE`, `EDU_PUBLIC`, `FEDERAL_GOV`, `LOCAL_GOV`, `NON_PROFIT`, `STATE_GOV`, `TRIBAL` Purpose for sale: `BUSINESS_USE`, `PERSONAL_USE`, `RENTAL_USE`, `RESALE` The currency of the transaction. This must match the destination country if Zamp is filing the return Transaction-level discount Total excluding tax and shipping/handling. This is no longer required Transaction-level shipping Transaction-level handling Combined shipping/handling Actual tax collected amount Total including tax and shipping / handling Where transaction physically shipped from Where shipped to or point of sale Line item details Custom key-value pairs (max 50, keys 1-40 chars, values 1-500 chars) ### Address Object Street address Additional address info City name Two-letter state code Format: `#####` or `#####-####` ISO-3166 Alpha-2 code (Default, US) ### Line Item Properties Unique line item identifier Amount per unit Number of units Line-item level discount Line-item level shipping Line-item level handling Combined line-item shipping/handling Product description Product identifier 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. ```json theme={null} { "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 Number of items to return (1-100) Pagination cursor from a previous `nextCursor` Exclude transactions before this timestamp Exclude transactions after this timestamp ### Request ```markdown theme={null} GET /transactions ``` Keep in mind that this endpoint will only return transactions associated with that API key, not all transactions for a company. ```bash GET /transactions theme={null} curl -G https://api.zamp.com/transactions \ -H "Authorization: Bearer {token}" \ -d limit=10 ``` ### Response ```json 200 theme={null} { "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](/api-reference/calculations) endpoint. ### Request ```markdown theme={null} POST /transactions ``` ```bash POST /transactions theme={null} 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. ```json 200 theme={null} { "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](/guides/handling-refunds) guide for details. ### Request ```text theme={null} POST /transactions ``` ```bash POST /transactions theme={null} 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. ```json 200 theme={null} { "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 ```text theme={null} GET /transactions/:id ``` ```bash GET /transactions/:id theme={null} 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](#create-a-transaction) response). ```json 200 theme={null} { "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. ```text theme={null} PUT /transactions ``` ```bash PUT /transactions/:id theme={null} 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. ```text theme={null} DELETE /transactions ``` ```bash DELETE /transactions/:id theme={null} curl -X DELETE https://api.zamp.com/transactions/123 \ -H "Authorization: Bearer {token}" ```