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 its id, which keeps the tax and accounting information together for filing. Record returns against the transaction 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 code 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, rate_type, jurisdiction_name, fee_amount, and note. Same fields as on the calculation.

number

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

number

Line amount before tax.

number

Line amount including tax.

number

Quantity sold.

timestamp

Unix seconds when the sale was made. If you didn’t send it, 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, echoed unchanged. Only present when sent.

The Transaction object

{
  "testmode": true,
  "id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c",
  "filing_currency_code": "USD",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "line_item_id": "li_1783369478353396a9168-1972-4798-80cb-536d96c0cc5a",
      "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": 1783369500
}

Create a transaction

Records a sale from a calculation. Create it after the customer pays. The payload is small because the tax details come from the calculation. Try it in the API reference.

Parameters

string

required

The id of the calculation to record as a sale.

string

required

Your order ID.

number

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

object

String key-value pairs, echoed back in the response. Same limits as on the calculation.

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: 2024-09-01' \
  -d '{
    "calculation_id": "calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c",
    "reference_order_id": "343-45836"
  }'

Response

{
  "testmode": true,
  "id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
  "object": "tax.transaction",
  "calculation_id": "calc_1783369478354d32be1ac-066b-49b1-a952-3e45e640c49c",
  "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_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2024-09-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_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2024-09-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, not when listed.

timestamp

Unix seconds when the refund was made. If you didn’t send it, when the refund was created.

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": true,
  "refund_processed_at": 1783369600,
  "line_items": ["... refunded line items, same fields as the transaction's ..."]
}

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.

number

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

array of objects

Required for partial refunds. Identify each line by reference_product_id.

string

The product to refund. Numeral finds the line on the original transaction with this reference_product_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: 2024-09-01' \
  -d '{
    "transaction_id": "tr_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477",
    "type": "partial",
    "line_items": [
      {
        "reference_product_id": "wand_elder_12",
        "sales_amount_refunded": -4000,
        "tax_amount_refunded": -390,
        "quantity": 1
      }
    ]
  }'

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_17364055483633b874c93-b888-4b78-a4b8-bf0e7b99e477/refunds \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2024-09-01'

Response

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

Reverse a refund

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

string

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: 2024-09-01' \
  -d '{ "refund_id": "ref_tr_123456789" }'

Errors

Errors in this version return an error object with error_code and error_message, and sometimes error_meta with details such as the offending field. The request ID is in the X-Request-Id response header, not the body.

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.
404	—	Create a transaction: `calculation_id` doesn’t exist.
404	—	Create a refund: `transaction_id` doesn’t exist.

400

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

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