> ## 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

| Property           | Type                               | Description                                                                         |
| ------------------ | ---------------------------------- | ----------------------------------------------------------------------------------- |
| `id`               | string                             | Unique identifier for the transaction                                               |
| `name`             | string (optional)                  | Friendly identifier (e.g., invoice number)                                          |
| `parentId`         | string (optional)                  | Required for refund transactions; references original transaction `id`              |
| `transactedAt`     | datetime (ISO-8601)                | Timestamp when transaction occurred                                                 |
| `recalculate`      | boolean (optional, default: false) | If false, uses provided `taxCollected` amount instead of calculating                |
| `isResale`         | boolean (optional, **deprecated**) | Whether the transaction is for resale. Use `RESALE` on `purpose` instead            |
| `marketplace`      | string (optional)                  | Marketplace facilitator that collected payment and assumed sales tax responsibility |
| `entity`           | string (optional)                  | Customer's entity exemption type                                                    |
| `purpose`          | string (optional)                  | Purpose for sale: `BUSINESS_USE`, `PERSONAL_USE`, `RENTAL_USE`, `RESALE`            |
| `currency`         | string (optional, default: USD)    | ISO-4217 currency code                                                              |
| `discount`         | number (optional)                  | Transaction-level discount                                                          |
| `subtotal`         | number                             | Total excluding tax and shipping/handling                                           |
| `shipping`         | number (optional)                  | Transaction-level shipping                                                          |
| `handling`         | number (optional)                  | Transaction-level handling                                                          |
| `shippingHandling` | number (optional)                  | Combined shipping/handling                                                          |
| `taxCollected`     | number (optional)                  | Actual tax collected amount                                                         |
| `total`            | number                             | Total including tax and shipping/handling                                           |
| `shipFromAddress`  | address (optional)                 | Where transaction physically shipped from                                           |
| `shipToAddress`    | address                            | Where shipped to or point of sale                                                   |
| `lineItems`        | array (min 1)                      | Line item details                                                                   |
| `metadata`         | object (optional)                  | Custom key-value pairs (max 50, keys 1-40 chars, values 1-500 chars)                |

### Address Object

| Property  | Type              | Description                     |
| --------- | ----------------- | ------------------------------- |
| `line1`   | string            | Street address                  |
| `line2`   | string (optional) | Additional address info         |
| `city`    | string            | City name                       |
| `state`   | string            | Two-letter state code           |
| `zip`     | string            | Format: `#####` or `#####-####` |
| `country` | string (optional) | ISO-3166 Alpha-2 code           |

### Line Item Properties

| Property           | Type              | Description                          |
| ------------------ | ----------------- | ------------------------------------ |
| `id`               | string            | Unique line item identifier          |
| `amount`           | number            | Amount per unit                      |
| `quantity`         | number            | Number of units                      |
| `discount`         | number (optional) | Line-item level discount             |
| `shipping`         | number (optional) | Line-item level shipping             |
| `handling`         | number (optional) | Line-item level handling             |
| `shippingHandling` | number (optional) | Combined line-item shipping/handling |
| `productName`      | string            | Product description                  |
| `productSku`       | string (optional) | Product identifier                   |
| `productTaxCode`   | string (optional) | Zamp tax code for product taxability |

<Note>
  * 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.
</Note>

### 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,
  "subtotal": 18,
  "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

<ParamField query="limit" default="10" type="integer">
  Number of items to return (1-100)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous `nextCursor`
</ParamField>

<ParamField query="minTransactedAt" type="datetime">
  Exclude transactions before this timestamp
</ParamField>

<ParamField query="maxTransactedAt" type="datetime">
  Exclude transactions after this timestamp
</ParamField>

### Request

```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

```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

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

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

```bash DELETE /transactions/:id theme={null}
curl -X DELETE https://api.zamp.com/transactions/123 \
  -H "Authorization: Bearer {token}"
```