Skip to main content
A product is an item or SKU you sell, stored with its tax category. Registering products gives you category-specific tax collection and reporting. Create a product once. On a calculation, 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.
Where products fit
Endpoints
Create a productPOST/tax/productsRetrieve a productGET/tax/products/:idList all productsGET/tax/productsDelete a productDELETE/tax/products/:idClassify productsPOST/tax/products/classify

The Product object

Attributes

string, value is "tax.product"
String representing the object’s type.
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.
string
The name of the product. Doesn’t affect tax. Shown in reporting and reconciliation dashboards, which helps when you check transactions.
string
The tax category, which decides the tax rate for the product. Any category from the product categories list.
timestamp
Unix seconds when the product was created. updated_at follows the same pattern.
boolean
true if made with a test API key.
On 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.
The Product object

Create a product

Creates a product with its tax category. Try it in the API reference.

Parameters

string
required
Your ID for the product. Use it on calculation line items.
string
required
The name of the product, shown in reporting.
string
required
Tax category from the product categories list.

Returns

A Product object.
POST /tax/products
Response

Retrieve a product

Returns a product by its reference_product_id. Try it in the API reference.
string
required
Your ID for the product.

Returns

A Product object.
GET /tax/products/:id

List all products

Returns your products, up to 50 at a time. Try it in the API reference.
string
Pagination cursor from a previous response.

Returns

An object with a products array of Product objects, has_more (whether there are more to fetch), and last_product_id.
GET /tax/products
Response

Delete a product

Deletes a product. Try it in the API reference.
string
required
Your ID for the product.

Returns

The deleted object type and when it was deleted.
DELETE /tax/products/:id
Response

Classify products

Suggests a tax category for up to 20 products from their names and descriptions, using the AI provider keys stored for your account. Set create_products to create the classified products in the same call. Limited availability: see the product classification guide. Try it in the API reference.

Parameters

boolean
default:"false"
When true, every product that classifies successfully is created with the suggested category. Existing products are left unchanged. reference_product_id must be unique within the batch.
array
required
1 to 20 products. Each has reference_product_id (string, required), reference_product_name (string, required) and reference_product_description (string, optional). All up to 255 characters.

Returns

A list with one entry per product, in request order. Each entry has status (classified, fallback or failed), product_category (a code from the product categories list, GENERAL_MERCHANDISE on fallback, null on failure), confidence_score (0 to 1, null unless classified) and product_creation_status (not_requested, created, already_exists, not_classified or failed).
POST /tax/products/classify
Response

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.