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’s id, which keeps the tax and accounting information together for filing. Record returns against it as refunds.

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 the customer paid in.

string

Currency the tax on this transaction will be filed 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. The time the transaction was created if you didn’t send one.

boolean

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

object

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

For a line’s effective tax rate, divide its tax_amount by its amount_excluding_tax. Don’t add up tax_rate values. See Effective tax rate.

The Transaction object

{
  "testmode": false,
  "id": "tr_123456789",
  "object": "tax.transaction",
  "calculation_id": "calc_123456789",
  "filing_currency_code": "USD",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1783369661107e97b4af5-b61a-487d-aa31-ecee6e616f7f",
      "product": {
        "reference_line_item_id": "line_123456789",
        "reference_product_id": "p-1233543",
        "reference_product_name": "Red Shoes",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.07,
          "tax_due_decimal": 14,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Tennessee",
          "tax_authority_type": "",
          "tax_type": "SALES"
        }
      ],
      "tax_amount": 14,
      "amount_excluding_tax": 200,
      "amount_including_tax": 214,
      "quantity": 2
    }
  ],
  "reference_order_id": "343-45836",
  "transaction_processed_at": 1714787673
}

Create a transaction

Records a sale from a calculation. Create it after the customer pays and before the calculation expires (24 hours). The payload is small because the transaction takes its line items and tax from the calculation. When Numeral files with the state, this order is included. Try it in the API reference.

Parameters

string

required

The id of the calculation to record.

string

required

Your order ID. Must be unique across your transactions.

integer

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

object

String key-value pairs, echoed back in the response. Up to 50 keys; keys and values 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-03-01' \
  -d '{
    "calculation_id": "calc_123456789",
    "reference_order_id": "343-45836"
  }'

Response

{
  "id": "tr_123456789",
  "object": "tax.transaction",
  "calculation_id": "calc_123456789",
  "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-03-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, in Unix seconds.

DELETE /tax/transactions/:id

curl -X DELETE https://api.numeralhq.com/tax/transactions/tr_123456789 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-03-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 or reversed.

timestamp

Unix seconds when the refund was made. The time the refund was created if you didn’t send one.

boolean

true if made with a test API key.

array of objects

The refunded line items. Same fields as the transaction’s line items.

The Refund object

{
  "id": "ref_tr_123456789",
  "object": "tax.refund",
  "refund_type": "partial",
  "testmode": false,
  "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.

Parameters

string

required

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

enum

required

full refunds everything. 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. Not needed for full.

string

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

number

Sale amount refunded on this line, excluding tax, as a negative number (e.g. -200).

number

Tax refunded on this line, as a negative number (e.g. -14).

number

Quantity refunded.

string

Your line item ID, used only for reporting.

Returns

A Refund object.

POST /tax/refunds

curl https://api.numeralhq.com/tax/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-03-01' \
  -d '{
    "transaction_id": "tr_123456789",
    "type": "partial",
    "line_items": [
      {
        "reference_product_id": "p-1233543",
        "reference_line_item_id": "line_123456789",
        "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-03-01'

Response

{
  "refunds": [
    {
      "id": "ref_tr_123456789",
      "object": "tax.refund",
      "testmode": false,
      "refund_processed_at": 1714787673,
      "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-03-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 is more than 24 hours old. 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`	`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