---
title: "Classify Products"
method: POST
path: "/tax/products/classify"
---

# Classify Products

`POST /tax/products/classify`

## Request

- Base URL: `https://api.numeralhq.com`
- URL: `https://api.numeralhq.com/tax/products/classify`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/numeral-com/apis/numeral-api/docs/tax/products/classify/post.ts> (a function with typed inputs; its response is checked against the schema)

Suggest a Numeral tax category for up to 20 products from their names and descriptions, using the AI provider keys stored for your account. Optionally create the classified products in one call. Available on API version 2026-01-01 and later.

## Request body

- ProductClassificationRequest
  - `create_products` boolean: 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.
  - `products` ProductClassificationInput[], required: Products to classify. Between 1 and 20 per request.
    - `reference_product_id` string, required: Your ID for the product. Returned unchanged on the matching result and used as the product ID when `create_products` is true. 1 to 255 characters.
    - `reference_product_name` string, required: The product name. The main input to classification. 1 to 255 characters.
    - `reference_product_description` string: Optional product description. Improves classification for ambiguous names. Up to 255 characters.

## Response `200`

One result per input product, in request order

- ProductClassificationResponse
  - `object` string, required: Always `list`.
  - `create_products` boolean, required: Echo of the request's `create_products`.
  - `product_categories` ProductClassificationResult[], required: One result per input product, in the same order as the request.
    - `reference_product_id` string, required: The `reference_product_id` from the matching input.
    - `status` 'classified' | 'fallback' | 'failed', required: `classified`: a category was chosen with a confidence score. `fallback`: no category could be chosen, so `GENERAL_MERCHANDISE` is suggested with no score. `failed`: this product could not be processed; retry it.
    - `product_category` string, nullable, required: The suggested category, always a code from the product categories list. `GENERAL_MERCHANDISE` when `status` is `fallback`, `null` when `failed`.
    - `confidence_score` number, nullable, required: How confident the classifier is in `product_category`, from 0 to 1. `null` unless `status` is `classified`.
    - `product_creation_status` 'not_requested' | 'created' | 'already_exists' | 'not_classified' | 'failed', required: What happened to the product record. `not_requested` when `create_products` is false. Otherwise `created`, `already_exists` (a product with this ID was already registered and was not changed), `not_classified` (status was `fallback` or `failed`, so nothing was created), or `failed` (classified, but the product could not be saved).
  - `testmode` boolean, required: `true` if called with a test API key.

## Other responses

- `400`: Validation error, or no valid AI provider keys are stored for this environment (`PRODUCT_CLASSIFICATION_CREDENTIALS_MISSING`, `PRODUCT_CLASSIFICATION_CREDENTIALS_INVALID`)
- `404`: Product classification is not enabled for this account (`ENDPOINT_NOT_FOUND`)
- `429`: Another classification request is already in progress for this account, the service is at capacity, or your AI provider rate limited the request (`PRODUCT_CLASSIFICATION_CAPACITY_EXCEEDED`, `PRODUCT_CLASSIFICATION_PROVIDER_QUOTA`). Retry after the number of seconds in the `Retry-After` header.
- `503`: Product classification is temporarily unavailable (`PRODUCT_CLASSIFICATION_UNAVAILABLE`). Retry with backoff.

## Changes

- **2026-11-04** `b73dd8ee99c6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/numeral-com/apis/numeral-api/changes/tax/products/classify/post.md)

---

[API](https://skmtc.dev/numeral-com/apis/numeral-api.md) - [All operations](https://skmtc.dev/numeral-com/apis/numeral-api/llms.txt) - [OpenAPI document](https://skmtc.dev/numeral-com/apis/numeral-api/revisions/b73dd8ee99c6?raw)