Skip to main content
A product is an item or SKU you sell, stored with its tax category. Registering products ensures accurate, category-specific tax collection and reporting. Create one 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/:id

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

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