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 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/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 code 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 before 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. If you didn’t send it, 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, 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

calculation_id · string · required

The id of the calculation to record as a sale.

reference_order_id · string · required

Your order ID.

transaction_processed_at · number

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

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

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

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

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 or reversed, not when listed.

refund_processed_at · timestamp

Unix seconds when the refund was made. If you didn’t send it, 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": 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

transaction_id · string · required

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

type · enum · required

full refunds everything and needs no line_items. 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. Identify each line by reference_product_id.

line_items[].reference_product_id · string

The product to refund. Numeral finds the line on the original transaction with this reference_product_id.

line_items[].sales_amount_refunded · number

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

line_items[].tax_amount_refunded · number

Tax refunded on this line, as a negative number (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: 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.

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

refund_id · 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"
  }
}