products

Endpointhttps://api.smartersorting.com

Count filtered products

GET

https://api.smartersorting.com

/classification/v1/products/count

Counts products based on specified filters

Count filtered products › query Parameters

statuses

string[] · style: form · explode: true

Filter by product status - must be included in array format.

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

start_date

string · date-time

Only count records with last_updated_date > start_date

end_date

string · date-time

Only count records with last_updated_date < end_date

Count filtered products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Count filtered products › Responses

A count of products matching the criteria.

Response containing the count of products matching the filters.

count

integer

Total count of products matching the filters.

Lookup product by UPC

GET

https://api.smartersorting.com

/classification/v1/products/:upc

Lookup product by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

Lookup product by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Lookup product by UPC › Responses

Product found

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

PUT product attributes by UPC

PUT

https://api.smartersorting.com

/classification/v1/products/:upc

For the provided UPC, overwrite the existing product's attributes.

PUT product attributes by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

PUT product attributes by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

PUT product attributes by UPC › Request Body

PUT product attributes by UPC › Responses

Product attributes persisted

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

PUT/classification/v1/products/:upc

curl --request PUT \
  --url https://api.smartersorting.com/classification/v1/products/:upc \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_name": "ACME Anvil",
  "internal_sku": "retailer-id-123",
  "brand": "ACME",
  "description": "Custom description for your product"
}
'

shell

Example Request Body

{
  "product_name": "ACME Anvil",
  "internal_sku": "retailer-id-123",
  "brand": "ACME",
  "description": "Custom description for your product"
}

json

application/json

Example Responses

{
  "status": "CLASSIFICATION_COMPLETE",
  "last_updated_date": "2025-04-01T18:44:48.718Z",
  "created_date": "2025-04-01T18:41:10.589Z",
  "upc": "72527273070",
  "product_name": "Anvil",
  "attributes": [
    {
      "name": "some_name",
      "value": "SOME_VALUE"
    },
    {
      "name": "ANOTHER_NAME",
      "value": 9.86
    }
  ],
  "classifications": [
    {
      "name": "battery_chemistry",
      "value": "alkaline"
    }
  ],
  "attested": {
    "is_attested": false
  }
}

json

application/json

PATCH product attributes by UPC

PATCH

https://api.smartersorting.com

/classification/v1/products/:upc

Update or append attributes to the product identified by the provided UPC.

PATCH product attributes by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

PATCH product attributes by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

PATCH product attributes by UPC › Request Body

PATCH product attributes by UPC › Responses

Product attributes persisted

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

PATCH/classification/v1/products/:upc

curl --request PATCH \
  --url https://api.smartersorting.com/classification/v1/products/:upc \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_name": "ACME Anvil",
  "internal_sku": "retailer-id-123",
  "brand": "ACME",
  "description": "Custom description for your product"
}
'

shell

Example Request Body

{
  "product_name": "ACME Anvil",
  "internal_sku": "retailer-id-123",
  "brand": "ACME",
  "description": "Custom description for your product"
}

json

application/json

Example Responses

{
  "status": "CLASSIFICATION_COMPLETE",
  "last_updated_date": "2025-04-01T18:44:48.718Z",
  "created_date": "2025-04-01T18:41:10.589Z",
  "upc": "72527273070",
  "product_name": "Anvil",
  "attributes": [
    {
      "name": "some_name",
      "value": "SOME_VALUE"
    },
    {
      "name": "ANOTHER_NAME",
      "value": 9.86
    }
  ],
  "classifications": [
    {
      "name": "battery_chemistry",
      "value": "alkaline"
    }
  ],
  "attested": {
    "is_attested": false
  }
}

json

application/json

Bulk upload products

POST

https://api.smartersorting.com

/classification/v1/products/bulk

Upload products in text/csv format. The header row must include both "upc", and "name" (the product's name) at a minimum.

For the best classification results, please provide "brand" and "description".

Please note that the following fields, when provided by a supplier or retailer, will be treated as special parameters for a product which cannot be overwritten by enrichment or other automation and will be used for classification: "upc", "name", "brand", "supplier", "ingredients", "sds", "manual", "un38", "battery_chemistry", "size", "form" and "external_id".

Suppliers: Additionally, when providing "ingredients", please be advised not to include proprietary data, as this field will be shared with retailers based on a UPC match.

Finally, your CSV may include any other parameters you wish to be persisted and returned back in future results to make integration with your applications easier. An example of this may be an SKU or a department code. Note that if you provide "external_id", it will appear in other parts of the SmarterSorting ecosystem, such as our UI portal.

Bulk upload products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Bulk upload products › Request Body

string

Bulk upload products › Responses

Product batch successfully created

Represents the unique synthetic identifier for a batch of uploaded products

batchId

string

Retrieve filtered products

GET

https://api.smartersorting.com

/classification/v1/products

Returns products based on specified filters with pagination. Products will be ordered by last_updated_date descending.

Retrieve filtered products › query Parameters

start_date

string · date-time

Only include records with last_updated_date > start_date

end_date

string · date-time

Only include records with last_updated_date < end_date

statuses

string[] · style: form · explode: true

Filter by product status - must be included in array format.

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

page_size

integer · min: 1 · max: 100

Number of products per page (default 50, max 100)

Default: 50

page_token

string

A pagination token used to continue retrieving results from a previous query. If omitted, the query starts from the beginning. Use the value returned in the response to request the next batch of results.

Retrieve filtered products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Retrieve filtered products › Responses

A list of products matching the criteria.

Paginated response of products.

object

Pagination details.

object[]

GET/classification/v1/products

curl --request GET \
  --url https://api.smartersorting.com/classification/v1/products \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "pagination": {
    "total": 100,
    "next_page_token": "WyJoZWxsbyIsICJ3b3JsZCJd",
    "page_size": 1
  },
  "products": [
    {
      "status": "CLASSIFICATION_COMPLETE",
      "last_updated_date": "2025-04-01T18:44:48.718Z",
      "created_date": "2025-04-01T18:41:10.589Z",
      "upc": "72527273070",
      "product_name": "Anvil",
      "attested": {
        "is_attested": false
      },
      "classifications": [
        {
          "name": "battery_chemistry",
          "value": "alkaline"
        }
      ],
      "attributes": [
        {
          "name": "some_name",
          "value": "SOME_VALUE"
        },
        {
          "name": "ANOTHER_NAME",
          "value": 9.86
        }
      ]
    }
  ]
}

json

application/json

docs

Count filtered products

GET

https://api.smartersorting.com

/classification/v1/products/count

Counts products based on specified filters

Count filtered products › query Parameters

statuses

string[] · style: form · explode: true

Filter by product status - must be included in array format.

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

start_date

string · date-time

Only count records with last_updated_date > start_date

end_date

string · date-time

Only count records with last_updated_date < end_date

Count filtered products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Count filtered products › Responses

A count of products matching the criteria.

Response containing the count of products matching the filters.

count

integer

Total count of products matching the filters.

Lookup product by UPC

GET

https://api.smartersorting.com

/classification/v1/products/:upc

Lookup product by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

Lookup product by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Lookup product by UPC › Responses

Product found

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

PUT product attributes by UPC

PUT

https://api.smartersorting.com

/classification/v1/products/:upc

For the provided UPC, overwrite the existing product's attributes.

PUT product attributes by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

PUT product attributes by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

PUT product attributes by UPC › Request Body

PUT product attributes by UPC › Responses

Product attributes persisted

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

PATCH product attributes by UPC

PATCH

https://api.smartersorting.com

/classification/v1/products/:upc

Update or append attributes to the product identified by the provided UPC.

PATCH product attributes by UPC › path Parameters

upc

string · pattern: ^(?=.*[1-9])[0-9]{1,… · required · style: simple

UPC for the desired product

A valid UPC. Must contain at least one non-zero digit and must not exceed 14 characters.

PATCH product attributes by UPC › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

PATCH product attributes by UPC › Request Body

PATCH product attributes by UPC › Responses

Product attributes persisted

A dictionary representing a product with string keys and any values

status

string · enum

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

last_updated_date

string · date

upc

string

product_name

string

object[]

Bulk upload products

POST

https://api.smartersorting.com

/classification/v1/products/bulk

Upload products in text/csv format. The header row must include both "upc", and "name" (the product's name) at a minimum.

For the best classification results, please provide "brand" and "description".

Suppliers: Additionally, when providing "ingredients", please be advised not to include proprietary data, as this field will be shared with retailers based on a UPC match.

Bulk upload products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Bulk upload products › Request Body

string

Bulk upload products › Responses

Product batch successfully created

Represents the unique synthetic identifier for a batch of uploaded products

batchId

string

Retrieve filtered products

GET

https://api.smartersorting.com

/classification/v1/products

Returns products based on specified filters with pagination. Products will be ordered by last_updated_date descending.

Retrieve filtered products › query Parameters

start_date

string · date-time

Only include records with last_updated_date > start_date

end_date

string · date-time

Only include records with last_updated_date < end_date

statuses

string[] · style: form · explode: true

Filter by product status - must be included in array format.

Enum values:

PENDING

CLASSIFICATION_COMPLETE

IN_REVIEW

page_size

integer · min: 1 · max: 100

Number of products per page (default 50, max 100)

Default: 50

page_token

string

Retrieve filtered products › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Retrieve filtered products › Responses

A list of products matching the criteria.

Paginated response of products.

object

Pagination details.

object[]