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

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/transactionsRetrieve a transactionGET/tax/transactions/:idDelete a transactionDELETE/tax/transactions/:idCreate a refundPOST/tax/refundsList refunds for a transactionGET/tax/transactions/:id/refundsReverse a refundPOST/tax/refund_reversals

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.

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.

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.

The Transaction object

{
  "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.

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.

POST /tax/transactions

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"
  }'

Response

{
  "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.

transaction_id · string · required

The transaction’s id.

Returns

A Transaction object.

GET /tax/transactions/:id

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 instead. Try it in the API reference.

transaction_id · 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_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2025-05-12'

Response

{
  "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 Refund object

{
  "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.

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.

POST /tax/refunds

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.

transaction_id · 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_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2025-05-12'

Response

{
  "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.

refund_id · string · required

The id of the refund to reverse.

Returns

A Refund object.

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

400

{
  "error": {
    "error_code": "missing_field",
    "error_message": "Field is required"
  }
}