> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Store your products and their tax categories

A product is an item or SKU you sell, stored with its tax category. Create it once. On a [calculation](https://docs.numeral.com/v2026-11-01/objects/calculations.md), send only its `reference_product_id`: Numeral remembers the category and returns the right tax, so you don't track tax categories on your side.

```text Where products fit theme={null}
Setup
└─ POST /tax/products        send: your product ID + category
Checkout
└─ POST /tax/calculations    send: reference_product_id on each line item
```

Endpoints
[Create a productPOST/tax/products](#create-a-product)
[Retrieve a productGET/tax/products/:id](#retrieve-a-product)
[List all productsGET/tax/products](#list-all-products)
[Delete a productDELETE/tax/products/:id](#delete-a-product)

## The Product object

### Attributes

**object** `string, value is "tax.product"`

String representing the object's type.

**reference\_product\_id** `string`

Your ID for the product. It identifies the product in Numeral: use it on calculation line items and to retrieve or delete the product. Use the same ID as in your own product system to make reconciliation and record keeping simple.

**reference\_product\_name** `string`

The name of the product. Doesn't affect tax. Shown in reporting and reconciliation dashboards, which helps when you check transactions.

**product\_category** `string`

The tax category, which decides the tax rate for the product. Any category from the [product categories](https://docs.numeral.com/essentials/product-categories.md) list.

**created\_at** `timestamp`

Unix seconds when the product was created. `updated_at` follows the same pattern.

**testmode** `boolean`

`true` if made with a test API key.

> [!NOTE]
>
> On a [calculation](https://docs.numeral.com/v2026-11-01/objects/calculations.md#create-a-calculation), a `reference_product_id` that doesn't exist returns `PRODUCT_NOT_FOUND` (404), unless the line item also sends `fallback_product_category`. If the product exists, its stored category wins.

```json The Product object theme={null}
{
  "object": "tax.product",
  "reference_product_id": "p-123456789",
  "reference_product_name": "Red Shoes",
  "product_category": "CLOTHING_GENERAL",
  "created_at": 1721694425,
  "updated_at": 1721694425,
  "testmode": true
}
```

## Create a product

Creates a product with its tax category. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/products).

### Parameters

**reference\_product\_id** `string` *required*

Your ID for the product. Use it on calculation line items.

**reference\_product\_name** `string` *required*

The name of the product, shown in reporting.

**product\_category** `string` *required*

Tax category from the [product categories](https://docs.numeral.com/essentials/product-categories.md) list.

### Returns

A [Product object](#the-product-object).

```bash POST /tax/products theme={null}
curl https://api.numeralhq.com/tax/products \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Version: 2026-11-01' \
  -d '{
    "reference_product_id": "p-123456789",
    "reference_product_name": "Red Shoes",
    "product_category": "CLOTHING_GENERAL"
  }'
```

```json Response theme={null}
{
  "object": "tax.product",
  "reference_product_id": "p-123456789",
  "reference_product_name": "Red Shoes",
  "product_category": "CLOTHING_GENERAL",
  "created_at": 1721694425,
  "updated_at": 1721694425,
  "testmode": true
}
```

## Retrieve a product

Returns a product by its `reference_product_id`. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/get_product).

**reference\_product\_id** `string` *required*

Your ID for the product.

### Returns

A [Product object](#the-product-object).

```bash GET /tax/products/:id theme={null}
curl https://api.numeralhq.com/tax/products/p-123456789 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

## List all products

Returns your products, up to 50 at a time. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/get_products).

**cursor** `string`

Pagination cursor from a previous response.

### Returns

An object with a `products` array of [Product objects](#the-product-object), `has_more` (whether there are more to fetch), and `last_product_id`.

```bash GET /tax/products theme={null}
curl https://api.numeralhq.com/tax/products \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "products": [
    {
      "object": "tax.product",
      "reference_product_id": "p-123456789",
      "...": "see The Product object"
    }
  ],
  "has_more": false,
  "last_product_id": "p-123456789"
}
```

## Delete a product

Deletes a product. [Try it in the API reference](https://docs.numeral.com/api-reference/v2026-11-01/endpoint/delete_product).

**reference\_product\_id** `string` *required*

Your ID for the product.

### Returns

The deleted object type and when it was deleted.

```bash DELETE /tax/products/:id theme={null}
curl -X DELETE https://api.numeralhq.com/tax/products/p-123456789 \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'
```

```json Response theme={null}
{
  "object": "tax.product",
  "deleted_at": 1721782604
}
```

## Errors

Errors return `code`, `type`, and `message`. Handle them by `type`. Full list in [Error Codes](https://docs.numeral.com/api-reference/v2026-11-01/error-codes.md).

| HTTP | `type` | When |
| - | - | - |
| 400 | `MISSING_FIELD` | A required field is missing. |
| 400 | `INCORRECT_TYPE` | A field has the wrong type. |
| 400 | `INVALID_PRODUCT_CATEGORY` | `product_category` isn't in the [product categories](https://docs.numeral.com/essentials/product-categories.md) list. |
| 400 | `DUPLICATE_PRODUCT` | A product with this `reference_product_id` already exists. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.