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. 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 List transactions for an orderGET/tax/transactions?reference_order_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

Your payment ID. Empty when not set. Returned by the GET endpoints.

string

ISO 4217 currency the customer paid in.

string

Currency the tax on this transaction will be filed in.

number

Exchange rate from the customer currency to the filing currency. 0 when they’re the same. Returned by the GET endpoints.

string

The address the tax was calculated for. address_line_2 (can be null), address_city, address_province, address_postal_code and address_country follow the same pattern. Returned by the GET endpoints.

array of objects

The line items from the calculation.

string

Numeral-generated ID for this line item. Use it in partial refunds.

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, tax_type, and note. Same fields as on the calculation.

string

New in 2026-11-01. Why this row came out the way it did. Empty string for normally calculated tax. See Notes. Transactions created before this version was released may return an empty note.

integer

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

integer

Line amount before tax.

integer

Line amount including tax.

number

Quantity sold.

string

Sale type for the line, e.g. b2c.

timestamp

Unix seconds when the sale was made.

string

PURCHASE for a sale. Returned by the GET endpoints.

timestamp

Unix seconds when the transaction was recorded. updated_at follows the same pattern. Returned by the GET endpoints.

boolean

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

object

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

Transactions don’t have an effective_tax_rate. Use the one on the calculation, or divide tax_amount by amount_excluding_tax.

The Transaction object

{
  "object": "tax.transaction",
  "id": "tr_1793039302001",
  "calculation_id": "calc_1793039299123",
  "customer_currency_code": "USD",
  "filing_currency_code": "USD",
  "filing_currency_code_rate": 0,
  "reference_order_id": "order-1001",
  "reference_payment_id": "",
  "address_line_1": "233 S Wacker Dr",
  "address_line_2": null,
  "address_city": "Chicago",
  "address_province": "IL",
  "address_postal_code": "60606",
  "address_country": "US",
  "line_items": [
    {
      "line_item_id": "li_1793039299101",
      "product": {
        "reference_line_item_id": "widget",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 625,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Illinois",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.03,
          "tax_due_decimal": 300,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "Cook County",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.0125,
          "tax_due_decimal": 125,
          "fee_amount": 0,
          "rate_type": "GENERAL CITY LOCAL SALES TAX",
          "tax_authority_name": "Chicago",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        }
      ],
      "tax_amount": 1050,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 11050,
      "quantity": 2,
      "type": "b2c"
    },
    {
      "line_item_id": "li_1793039299102",
      "product": {
        "reference_line_item_id": "shipping",
        "reference_product_id": "default-shipping",
        "reference_product_name": "Default SHIPPING Product",
        "product_tax_code": "SHIPPING"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 62.5,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Illinois",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        "... Cook County and Chicago rows ..."
      ],
      "tax_amount": 105,
      "amount_excluding_tax": 1000,
      "amount_including_tax": 1105,
      "quantity": 1,
      "type": "b2c"
    }
  ],
  "transaction_processed_at": 1793039302,
  "transaction_type": "PURCHASE",
  "created_at": 1793039302,
  "updated_at": 1793039302,
  "testmode": true
}

Create a transaction

Records a sale from a calculation. Create it after the customer pays and before the calculation expires (24 hours). Try it in the API reference.The transaction comes back in the shape of the X-API-Version you send now, whatever version the calculation was made on.

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.

Returns

A Transaction object, without the GET-only fields.

POST /tax/transactions

curl https://api.numeralhq.com/tax/transactions \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "calculation_id": "calc_1793039299123",
    "reference_order_id": "order-1001"
  }'

Response

{
  "testmode": true,
  "id": "tr_1793039302001",
  "object": "tax.transaction",
  "calculation_id": "calc_1793039299123",
  "filing_currency_code": "USD",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1793039299101",
      "product": { "...": "..." },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 625,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Illinois",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        "..."
      ],
      "tax_amount": 1050,
      "amount_excluding_tax": 10000,
      "amount_including_tax": 11050,
      "quantity": 2,
      "type": "b2c"
    },
    "..."
  ],
  "reference_order_id": "order-1001",
  "transaction_processed_at": 1793039302
}

Retrieve a transaction

Returns a transaction by its id.

string

required

The transaction’s id.

Returns

A Transaction object.

GET /tax/transactions/:id

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

List transactions for an order

Returns the transactions recorded with a given reference_order_id.

string

required

Your order ID.

Returns

An object with a transactions array of Transaction objects.

GET /tax/transactions

curl 'https://api.numeralhq.com/tax/transactions?reference_order_id=order-1001' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Response

{
  "transactions": [
    {
      "object": "tax.transaction",
      "id": "tr_1793039302001",
      "reference_order_id": "order-1001",
      "...": "see The Transaction object"
    }
  ]
}

Delete a transaction

Deletes a transaction, for example one recorded by mistake. To record a return, create a refund instead.

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_1793039302001 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Response

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

The Refund object

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

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.

boolean

true if made with a test API key.

array of objects

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

array of objects

The original sale’s rows, including note, with the sale’s rates and tax_due_decimal.

integer

Tax refunded on this line (negative).

integer

Sale amount refunded on this line (negative).

integer

Total refunded on this line (negative).

number

Quantity refunded.

The Refund object

{
  "object": "tax.refund",
  "id": "ref_tr_1793039302101",
  "refund_processed_at": 1793039302,
  "refund_type": "partial",
  "testmode": true,
  "line_items": [
    {
      "line_item_id": "li_1793039299101",
      "product": {
        "reference_line_item_id": "widget",
        "reference_product_id": "default-general-merchandise",
        "reference_product_name": "Default GENERAL_MERCHANDISE Product",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0.0625,
          "tax_due_decimal": 625,
          "fee_amount": 0,
          "rate_type": "GENERAL STATE SALES TAX",
          "tax_authority_name": "Illinois",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.03,
          "tax_due_decimal": 300,
          "fee_amount": 0,
          "rate_type": "GENERAL COUNTY LOCAL SALES TAX",
          "tax_authority_name": "Cook County",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        },
        {
          "tax_rate": 0.0125,
          "tax_due_decimal": 125,
          "fee_amount": 0,
          "rate_type": "GENERAL CITY LOCAL SALES TAX",
          "tax_authority_name": "Chicago",
          "tax_authority_type": "",
          "tax_type": "SALES",
          "note": ""
        }
      ],
      "tax_amount": -525,
      "amount_excluding_tax": -5000,
      "amount_including_tax": -5525,
      "quantity": 1,
      "type": "b2c"
    }
  ]
}

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.

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.

string

The transaction line to refund. Or identify it by reference_product_id.

string

The product to refund, matched against the original transaction’s lines.

integer

required

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

integer

required

Tax refunded, as a negative number.

number

required

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-11-01' \
  -d '{
    "transaction_id": "tr_1793039302001",
    "type": "partial",
    "line_items": [
      {
        "line_item_id": "li_1793039299101",
        "sales_amount_refunded": -5000,
        "tax_amount_refunded": -525,
        "quantity": 1
      }
    ]
  }'

List refunds for a transaction

Returns every refund recorded against a transaction.

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_1793039302001/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Response

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

Reverse a refund

Undoes a refund you created, for example one recorded by mistake.

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-11-01' \
  -d '{ "refund_id": "ref_tr_1793039302101" }'

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 in this environment (test or live).
404	`TRANSACTION_NOT_FOUND`	`transaction_id` doesn’t exist.

404

{
  "code": 404,
  "type": "CALCULATION_NOT_FOUND",
  "message": "Unable to find calculation with ID: calc_does_not_exist in test environment."
}

Getting Started

API Reference

The Transaction object

Attributes

Create a transaction

Parameters

Returns

Retrieve a transaction

Returns

List transactions for an order

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

​The Transaction object

​Attributes

​Create a transaction

​Parameters

​Returns

​Retrieve a transaction

​Returns

​List transactions for an order

​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

The Transaction object

Attributes

Create a transaction

Parameters

Returns

Retrieve a transaction

Returns

List transactions for an order

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