Product Catalog API

Tell Smarter Sorting about products we should know about.

This API allows a retailer to submit and update their active item catalog to Smarter Sorting, indicating which products require registration by Suppliers as being potentially hazardous versus which are non-hazardous and only eligible for donation or disposal. Products submitted via this API form the base data set for results from the separate BOSS Recommendation API.

Usage:

  1. POST your ingest batch job
  2. Retain the id from the response
  3. Poll your job status at the GET /ingest/product/batch/{batch_job_id} endpoint
  4. Note success_count and error_count: once their sum matches item_count the job is complete

The batch job will be validated immediately for required fields, data types, etc. If this validation doesn't succeed a 400 will result and error messages will be returned.

Error messages may also be noted later in the job status output. If you see error messages of the form: "unable to update product, currently in X state (422)", this may occur if a product update is sent too quickly after the previous update, and the product is still going through automated processing. This condition is expected to be rare and temporary, and typically retrying the failed product update later (not the entire batch) should succeed. If it does not, contact support.

Unless otherwise noted, the following limits apply to fields in POST/PUT bodies, URL path and query params:

  • Date/time strings must be provided in ISO 8601 format. All values converted to UTC, no time zone info will be retained.
  • All string fields, path and query parameters are limited to 127 characters or fewer
  • All floating-point numeric values are limited to approximately 6 decimal places of precision, with a range from approximately 1E-37 to 1E+37
  • All integer numeric values are limited to ±2<sup>32</sup>
  • All UUIDs are UUIDv4. These will be generated initially by SmarterX, and used in subsequent ingest requests.
BASE URL
https://boss-test.smarterx.com

Authentication

Sign into view and manage your API credentials

Check status of service

Retrieve the status of the service. Use to check that api key authentication is working.

Protected by API Key

Headers

Authorization

required, string

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

x-request-id

string

Unique request id for tracing purposes that can be provided in the header of any request

GET
/v1/ingest/health
1

Create batch ingestion job

Creates a batch ingestion job

Protected by API Key

Headers

Authorization

required, string

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

Request Body

items

optional, array

tags

optional, array of strings

tags used to group batches for retrieving results

POST
/v1/ingest/product/batch
1
EXAMPLE BODY
{
  "items": [
    {
      "identifiers": [
        {
          "gtin": "00757037351253",
          "sku": "12345",
          "external_id": "your-identifier-here-123"
        }
      ],
      "action": "upsert",
      "data": {
        "product_name": "Kaboom Bowl Blaster",
        "product_name_french": "Kaboom Bowl Blaster",
        "supplier_name": "Church and Dwight",
        "supplier_id": "1234",
        "supplier_id2": "abc123",
        "reporting_metadata": {
          "hello": "world"
        },
        "registration_required_by_retailer": true,
        "active_purchasing": true,
        "date_added_to_item_catalog": "2022-08-05",
        "item_weight": 1,
        "item_weight_measured_in": "lbs",
        "random_weight": false,
        "food_item": false,
        "ebt_food_item": false
      }
    }
  ]
}

Get batch job status

Get the status of a batch job and items in the batch

Protected by API Key

Headers

Authorization

required, string

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

GET
/v1/ingest/product/batch/:batch_job_id
1

Your GET endpoint

Retrieve multiple batch job results, using a tag and a date/time

Protected by API Key

Headers

Authorization

required, string

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

Query Parameters

tag

required, string

tag matching the submitted batch job

updated_since

required, string

return batches updated since the specified date/time (ISO-8601)

GET
/v1/ingest/product/batches
1