Skip to main content
POST
Classify Products

Classify Products Endpoint (2026-11-01)

Suggest a tax category for each product from its name and description, and optionally create the products in the same call. Every suggested category is a code from the product categories list, so the result can go straight into POST /tax/products or a calculation line item.
Product classification is in limited availability. Accounts that are not enabled receive a 404 ENDPOINT_NOT_FOUND from this endpoint. Contact your Numeral representative to enable it.
Remember to include the X-API-Version: 2026-11-01 header in your request to use this API version. This endpoint requires version 2026-01-01 or later.

Before you call it

Classification runs on your own AI provider keys, not Numeral’s. Store them in the dashboard under Developers > Product Classification AI API Keys and Settings before calling this endpoint. Test keys (sk_test_...) use the keys saved for the test environment and production keys use the production ones. A single OpenAI key is enough; Gemini and Anthropic keys are also supported. See the product classification guide for details.

How to read a result

Each entry in product_categories has a status: With create_products: true, product_creation_status reports what happened to each product record. Only classified products are created; fallback and failed products report not_classified. A product that already exists under the same reference_product_id is left unchanged and reports already_exists.

Limits

  • Up to 20 products per request.
  • One classification request in flight per account. A second concurrent request gets 429 with a Retry-After header.
  • A full batch can take tens of seconds, so allow at least 60 seconds for the response.

Errors

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
products
object[]
required

Products to classify. Between 1 and 20 per request.

Required array length: 1 - 20 elements
create_products
boolean
default:false

When true, every product that classifies successfully is also created with the suggested category, as if sent to POST /tax/products. Products already registered under the same reference_product_id are left unchanged. reference_product_id must then be unique within the batch.

Example:

false

Response

One result per input product, in request order

object
string
required

Always list.

Example:

"list"

create_products
boolean
required

Echo of the request's create_products.

Example:

false

product_categories
object[]
required

One result per input product, in the same order as the request.

testmode
boolean
required

true if called with a test API key.

Example:

true