> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> Record sales and refunds for filing

A transaction records a completed sale. Numeral files and remits tax based on the transactions recorded in each jurisdiction and period. Create one from a [calculation](https://docs.numeral.com/v2025-05-12/objects/calculations.md) after the customer pays: you need the `calculation_id`, which keeps the tax and accounting information tidy for filing. Record returns against it as refunds.

```text Where transactions fit theme={null}
Sale
├─ POST /tax/calculations    → calculation id
├─ Customer pays
├─ POST /tax/transactions    → transaction id   (store it)
└─ Customer returns an item
      └─ POST /tax/refunds   → refund id
```

Endpoints
[Create a transactionPOST/tax/transactions](#create-a-transaction)
[Retrieve a transactionGET/tax/transactions/:id](#retrieve-a-transaction)
[Delete a transactionDELETE/tax/transactions/:id](#delete-a-transaction)
[Create a refundPOST/tax/refunds](#create-a-refund)
[List refunds for a transactionGET/tax/transactions/:id/refunds](#list-refunds-for-a-transaction)
[Reverse a refundPOST/tax/refund\_reversals](#reverse-a-refund)

## The Transaction object

### Attributes

**id** `string`

The ID of the transaction, `tr_…`. Store it: refunds and lookups use it.

**object** `string, value is "tax.transaction"`

String representing the object's type.

**calculation\_id** `string`

The calculation this transaction was created from.

**reference\_order\_id** `string`

Your order ID, as sent when creating the transaction.

**customer\_currency\_code** `string`

ISO 4217 currency of the transaction.

**filing\_currency\_code** `string`

Currency the tax on this transaction will be filed and remitted in.

**line\_items** `array of objects`

The line items from the calculation.

**line\_items\[].line\_item\_id** `string`

Numeral-generated ID for this line item.

**line\_items\[].product** `object`

`reference_line_item_id`, `reference_product_id`, `reference_product_name` and `product_tax_code`, as on the [calculation](https://docs.numeral.com/v2025-05-12/objects/calculations.md#the-calculation-object).

**line\_items\[].tax\_jurisdictions** `array of objects`

One row per taxing jurisdiction: `tax_rate`, `rate_type`, `jurisdiction_name`, `fee_amount`, and `note`. Same fields as on the [calculation](https://docs.numeral.com/v2025-05-12/objects/calculations.md#the-calculation-object).

**line\_items\[].tax\_amount** `number`

Tax on the line, in the currency's smallest unit.

**line\_items\[].amount\_excluding\_tax** `number`

Line amount excluding tax.

**line\_items\[].amount\_including\_tax** `number`

Line amount including tax.

**line\_items\[].quantity** `number`

Quantity sold.

**transaction\_processed\_at** `timestamp`

Unix seconds when the sale was made. Defaults to when the transaction was created.

**testmode** `boolean`

`true` if made with a test API key. Live transactions count toward your nexus totals, and Numeral files them where you're registered and collecting.

**metadata** `object`

Key-value pairs from the request. Only present when sent.

```json The Transaction object theme={null}
{
  "testmode": true,
  "id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571",
  "filing_currency_code": "USD",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1783369568468ae179a21-411f-4a7f-a192-66a23331dc24",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "wand_elder_12",
        "reference_product_name": "Elder Wand",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0725,
          "rate_type": "general state sales tax",
          "jurisdiction_name": "California",
          "fee_amount": 0,
          "note": "RATE_FRAC"
        },
        {
          "tax_rate": 0.025,
          "rate_type": "general county local sales tax",
          "jurisdiction_name": "Los Angeles",
          "fee_amount": 0,
          "note": "RATE_FRAC"
        }
      ],
      "tax_amount": 975,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10975,
      "quantity": 1
    }
  ],
  "reference_order_id": "343-45836",
  "transaction_processed_at": 1783369600
}
```

## Create a transaction

Records a sale from a calculation. Because the transaction comes from a calculation, the request is short. The response includes the calculation's line items. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/transactions).

### Parameters

**calculation\_id** `string` *required*

The `id` of the calculation to record.

**reference\_order\_id** `string` *required*

Your order ID. Must be unique across your transactions.

**transaction\_processed\_at** `number`

When the sale was made, Unix **seconds**. Defaults to now.

**metadata** `object`

Up to 50 keys, each up to 255 characters. Values must be strings of up to 255 characters.

### Returns

A [Transaction object](#the-transaction-object).

```bash POST /tax/transactions theme={null}
curl https://api.numeralhq.com/tax/transactions \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2025-05-12' \
  -d '{
    "calculation_id": "calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571",
    "reference_order_id": "343-45836"
  }'
```

```json Response theme={null}
{
  "testmode": true,
  "id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369568468633ea55e-084a-419e-9d47-9f07aa27f571",
  "reference_order_id": "343-45836",
  "...": "see The Transaction object"
}
```

## Retrieve a transaction

Returns a transaction by its `id`. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/get_transaction).

**transaction\_id** `string` *required*

The transaction's `id`.

### Returns

A [Transaction object](#the-transaction-object).

```bash GET /tax/transactions/:id theme={null}
curl https://api.numeralhq.com/tax/transactions/tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2025-05-12'
```

## Delete a transaction

Deletes a transaction, for example one recorded by mistake. To record a return, [create a refund](#create-a-refund) instead. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/delete_transaction).

**transaction\_id** `string` *required*

The transaction's `id`.

### Returns

The deleted object type and when it was deleted.

```bash DELETE /tax/transactions/:id theme={null}
curl -X DELETE https://api.numeralhq.com/tax/transactions/tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2025-05-12'
```

```json Response theme={null}
{
  "object": "tax.transaction",
  "deleted_at": 1721782604
}
```

## The Refund object

A refund records money returned to the customer against a transaction.

### Attributes

**id** `string`

The ID of the refund, `ref_tr_…`. Store it: reversing the refund needs it.

**object** `string, value is "tax.refund"`

String representing the object's type.

**refund\_type** `enum`

`full` or `partial`. Returned when the refund is created.

**refund\_processed\_at** `timestamp`

Unix seconds when the refund was made. Defaults to when the refund was created.

**testmode** `boolean`

`true` if made with a test API key.

**line\_items** `array of objects`

The refunded line items. Same fields as the [transaction's line items](#the-transaction-object).

```json The Refund object theme={null}
{
  "id": "ref_tr_123456789",
  "object": "tax.refund",
  "refund_type": "partial",
  "testmode": true,
  "refund_processed_at": 1714787673,
  "line_items": ["... same fields as the transaction's line items ..."]
}
```

## Create a refund

Records a full or partial refund against a transaction. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/refunds).

### Parameters

**transaction\_id** `string` *required*

The `id` of the transaction to refund.

**type** `enum` *required*

`full` refunds everything. `partial` refunds the `line_items` you send.

**refund\_processed\_at** `number`

When the refund was made, Unix **seconds**. Defaults to now.

**line\_items** `array of objects`

Required for `partial` refunds. Not needed for `full`.

**line\_items\[].reference\_product\_id** `string`

The product to refund. Numeral finds the matching line item on the original transaction by this ID.

**line\_items\[].sales\_amount\_refunded** `number`

Sale amount refunded on this line, excluding tax, in the currency's smallest unit, e.g. `-200`.

**line\_items\[].tax\_amount\_refunded** `number`

Tax refunded on this line, e.g. `-14`.

**line\_items\[].quantity** `number`

Quantity refunded.

**line\_items\[].reference\_line\_item\_id** `string`

Your line item ID, used only for reporting.

### Returns

A [Refund object](#the-refund-object).

```bash POST /tax/refunds theme={null}
curl https://api.numeralhq.com/tax/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2025-05-12' \
  -d '{
    "transaction_id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
    "type": "partial",
    "line_items": [
      {
        "reference_product_id": "wand_elder_12",
        "sales_amount_refunded": -10000,
        "tax_amount_refunded": -975,
        "quantity": 1
      }
    ]
  }'
```

## List refunds for a transaction

Returns every refund recorded against a transaction. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/get_refunds_for_transaction).

**transaction\_id** `string` *required*

The transaction's `id`.

### Returns

An object with a `refunds` array of [Refund objects](#the-refund-object), without `refund_type`.

```bash GET /tax/transactions/:id/refunds theme={null}
curl https://api.numeralhq.com/tax/transactions/tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2025-05-12'
```

```json Response theme={null}
{
  "refunds": [
    {
      "id": "ref_tr_123456789",
      "object": "tax.refund",
      "testmode": true,
      "refund_processed_at": 1714787673,
      "line_items": ["..."]
    }
  ]
}
```

## Reverse a refund

Undoes a refund you created. [Try it in the API reference](https://docs.numeral.com/api-reference/v2025-05-12/endpoint/refund_reversals).

**refund\_id** `string` *required*

The `id` of the refund to reverse.

### Returns

A [Refund object](#the-refund-object).

```bash POST /tax/refund_reversals theme={null}
curl https://api.numeralhq.com/tax/refund_reversals \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2025-05-12' \
  -d '{ "refund_id": "ref_tr_123456789" }'
```

## Errors

Errors return an `error` object with `error_code`, `error_message`, and sometimes `error_meta` (details such as the offending `field` and the `expected` and `received` types). Handle them by `error_code`. The request ID is in the `X-Request-Id` response header.

| HTTP | `error_code` | When |
| - | - | - |
| 400 | `missing_field` | A required field is missing. |
| 400 | `incorrect_type` | A field has the wrong type. |
| 400 | `unrecognized_field` | An unknown field was sent. |

Also returned:

* 404 on create when `calculation_id` doesn't exist.
* 404 on create refund when `transaction_id` doesn't exist.

```json 400 theme={null}
{
  "error": {
    "error_code": "missing_field",
    "error_message": "Field is required"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.