Transactions

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 after the customer pays: you need the calculation_id, which keeps the tax and accounting information tidy for filing. Record returns against the transaction as refunds.A transaction carries most of the information from its calculation, including the line items, plus its own id.

Where transactions fit

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 Retrieve a transactionGET/tax/transactions/:id Delete a transactionDELETE/tax/transactions/:id Create a refundPOST/tax/refunds List refunds for a transactionGET/tax/transactions/:id/refunds Reverse a refundPOST/tax/refund_reversals

The Transaction object

Attributes

string

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

string, value is "tax.transaction"

String representing the object’s type.

string

The calculation this transaction was created from.

string

Your order ID, as sent when creating the transaction.

string

ISO 4217 currency of the transaction.

string

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

array of objects

The line items from the calculation.

string

Numeral-generated ID for this line item.

object

reference_line_item_id, reference_product_id, reference_product_name and product_tax_code, as on the calculation.

array of objects

One row per taxing jurisdiction: tax_rate, tax_due_decimal, fee_amount, rate_type, tax_authority_name, tax_authority_type, and tax_type. Same fields as on the calculation.

integer

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

integer

Line amount before tax.

integer

Line amount including tax.

number

Quantity sold.

timestamp

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

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.

object

Key-value pairs from the request.

The Transaction object

{
  "testmode": true,
  "id": "tr_123456789",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50856",
  "filing_currency_code": "USD",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd7",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-beverages",
        "reference_product_name": "Default BEVERAGES Product",
        "product_tax_code": "BEVERAGES"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 700,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        {
          "tax_rate": 0.0225,
          "tax_due_decimal": 225,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "DAVIDSON",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 925,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10925,
      "quantity": 1
    },
    {
      "line_item_id": "li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd8",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 700,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        },
        "... DAVIDSON row ..."
      ],
      "tax_amount": 925,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10925,
      "quantity": 1
    }
  ],
  "reference_order_id": "343-45836",
  "transaction_processed_at": 1783369800
}

Create a transaction

Records a sale from a calculation. Create it after the customer pays and before the calculation expires (24 hours). When it’s time to file, Numeral makes sure the order is included. Try it in the API reference.

Parameters

string

required

The id of the calculation to record as a sale.

string

required

Your order ID. Must be unique across your transactions.

integer

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

object

Your own key-value pairs. At most 50 keys. Keys up to 255 characters. Values must be strings of up to 255 characters.

Returns

A Transaction object.

POST /tax/transactions

curl https://api.numeralhq.com/tax/transactions \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "calculation_id": "calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50856",
    "reference_order_id": "343-45836"
  }'

Response

{
  "testmode": true,
  "id": "tr_123456789",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369695581b8ca8647-a864-40f4-bf8a-10ff46f50856",
  "reference_order_id": "343-45836",
  "...": "see The Transaction object"
}

Retrieve a transaction

Returns a transaction by its id. Try it in the API reference.

string

required

The transaction’s id.

Returns

A Transaction object.

GET /tax/transactions/:id

curl https://api.numeralhq.com/tax/transactions/tr_123456789 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-01-01'

Delete a transaction

Deletes a transaction, for example one recorded by mistake. To record a return, create a refund instead. Try it in the API reference.

string

required

The transaction’s id.

Returns

The deleted object type and when it was deleted.

DELETE /tax/transactions/:id

curl -X DELETE https://api.numeralhq.com/tax/transactions/tr_123456789 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-01-01'

Response

{
  "object": "tax.transaction",
  "deleted_at": 1721782604
}

The Refund object

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

Attributes

string

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

string, value is "tax.refund"

String representing the object’s type.

enum

full or partial. Returned when the refund is created.

timestamp

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

boolean

true if made with a test API key.

array of objects

The refunded line items, with the same fields as the transaction’s line items.

The Refund object

{
  "id": "ref_tr_123456789",
  "object": "tax.refund",
  "refund_type": "full",
  "testmode": true,
  "refund_processed_at": 1783456000,
  "line_items": [
    {
      "line_item_id": "li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd7",
      "product": {
        "reference_line_item_id": "",
        "reference_product_id": "default-beverages",
        "reference_product_name": "Default BEVERAGES Product",
        "product_tax_code": "BEVERAGES"
      },
      "tax_jurisdictions": ["..."],
      "tax_amount": -925,
      "amount_excluding_tax": -10000,
      "amount_including_tax": -10925,
      "quantity": 1
    },
    "..."
  ]
}

Create a refund

Records a full or partial refund against a transaction. Try it in the API reference.

Parameters

string

required

The id of the transaction to refund, as returned when you created it.

enum

required

full refunds everything, and needs no line_items. partial refunds the line_items you send.

integer

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

array of objects

Required for partial refunds.

string

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

number

Sale amount refunded on this line, excluding tax, as a negative number in the currency’s smallest unit.

number

Tax refunded on this line, as a negative number.

number

Quantity refunded.

string

Your line item ID, used only for reporting.

Returns

A Refund object.

curl https://api.numeralhq.com/tax/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "transaction_id": "tr_123456789",
    "type": "full"
  }'

curl https://api.numeralhq.com/tax/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{
    "transaction_id": "tr_123456789",
    "type": "partial",
    "line_items": [
      {
        "reference_product_id": "p-1233543",
        "sales_amount_refunded": -200,
        "tax_amount_refunded": -14,
        "quantity": 2
      }
    ]
  }'

List refunds for a transaction

Returns every refund recorded against a transaction. Try it in the API reference.

string

required

The transaction’s id.

Returns

An object with a refunds array of Refund objects, without refund_type.

GET /tax/transactions/:id/refunds

curl https://api.numeralhq.com/tax/transactions/tr_123456789/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-01-01'

Response

{
  "refunds": [
    {
      "id": "ref_tr_123456789",
      "object": "tax.refund",
      "testmode": true,
      "refund_processed_at": 1783456000,
      "line_items": ["..."]
    }
  ]
}

Reverse a refund

Undoes a refund you created, for example one recorded by mistake. Try it in the API reference.

string

required

The id of the refund to reverse.

Returns

A Refund object for the reversal.

POST /tax/refund_reversals

curl https://api.numeralhq.com/tax/refund_reversals \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-01-01' \
  -d '{ "refund_id": "ref_tr_123456789" }'

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.

HTTP	`type`	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.
400	`NEGATIVE_NUMBER_REQUIRED`	A refund amount isn’t negative.
400	`CALCULATION_EXPIRED`	The calculation has expired. Create a new one.
400	`TRANSACTION_ALREADY_EXISTS`	A transaction already exists for this `calculation_id`.
400	`REFERENCE_ORDER_ID_ALREADY_EXISTS`	A transaction already exists with this `reference_order_id`.
404	`CALCULATION_NOT_FOUND`	`calculation_id` doesn’t exist.
404	`TRANSACTION_NOT_FOUND`	The refund’s `transaction_id` doesn’t exist.

{
  "code": 404,
  "type": "CALCULATION_NOT_FOUND",
  "message": "Calculation not found"
}

{
  "code": 404,
  "type": "TRANSACTION_NOT_FOUND",
  "message": "Transaction not found"
}

Getting Started

API Reference

The Transaction object

Attributes

Create a transaction

Parameters

Returns

Retrieve a transaction

Returns

Delete a transaction

Returns

The Refund object

Attributes

Create a refund

Parameters

Returns

List refunds for a transaction

Returns

Reverse a refund

Returns

Errors