StylorDocs

Retrieve products

post/v1/products

Returns whole products by their itemIds, in the same shape search returns them: every variant with its price and stock, every photo, the store it is from. Use it to open a product page for an item you got as a compact card from feed, similar or rank, or a list of ids you saved.

Only products in your organization's active datasets are read. An id that is not one of them (archived, deleted, mistyped, another organization's) is left out of products without an error, so check the length when you need every one. Products come back in the order you asked for them, each once.

Prices in the shopper's market

Send the shopper's country and each product is priced as search prices it: price, currency and each variant's price, compareAtPrice and inStock are their market's. Without it, or for a country the store does not sell into, the store's default market is used and product.marketExact is false. Unlike search, a product their market does not sell is kept, marked product.soldHere: false, so a saved product can still be shown as unavailable rather than disappear.

Product reads draw on search's allowance, api.v1.search.query.

Public keyapi.v1.search.queryDemo key OK

Request body

application/jsonrequired
itemIdsarray<string>required

Full itemIds. Duplicates are returned once.

minItems: 1maxItems: 50
countrystring

The shopper's two-letter ISO 3166 country, such as US. Case does not matter.

Response

200The products found, in the order asked.
array<DatasetItem>required

One per id found. Ids not found are left out.

itemIdstring (uuid)required

Unique item id. It is the same id the queue entry was given at upload time.

e.g. "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11"
datasetIdstring (uuid)required

The dataset the item belongs to.

e.g. "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"
organizationIdstring (uuid)required

The organization that owns the dataset.

e.g. "0a2c1f4e-5b6d-7e8f-9012-3456789abcde"
statusstringrequired

Only active items are listed and searchable.

One ofactivearchived
e.g. "active"
versionnumberrequired

Ingest pipeline version the item was processed with.

e.g. 1
DatasetItemMetadatarequired

What Stylor's product labeller read from the item's photos and listing when it was processed. Fields with an enum are closed lists; the taxonomy (slot, family, features) is shared by every catalogue. Items processed before a field existed may lack it.

DatasetItemProductrequired

Merchant-facing product data. Everything here comes from your upload or your dataset configuration, not from AI.

DatasetItemOriginrequired

Where the item came from. Copied from the dataset's store configuration at processing time.

createdAtstring (date-time)required

When the processed item was first written.

e.g. "2025-03-04T18:22:41.913Z"
updatedAtstring (date-time)required

When the item was last rewritten by a sync or reprocess.

e.g. "2025-03-04T18:22:41.913Z"

Errors

26

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

400
Request body must be valid JSON.

The request body could not be parsed as JSON.

400
Request body must be a JSON object.

The request body is empty, or parsed to something other than a JSON object.

404
No active datasets found for this organization. Activate one via the dashboard (Dataset → Settings) or through the REST API before proceeding.

None of your datasets is active.

422
itemIds must be a non-empty array.

itemIds is missing, not an array, or empty.

422
itemIds can hold at most 50 ids.

itemIds holds more than 50 ids.

422
Each itemId must be a non-empty string.

An entry of itemIds is not a string, is blank, or is longer than 100 characters.

422
country must be a two-letter ISO 3166 country code, such as 'US'.

country was sent (non-null) but is not a string of exactly two letters.

curl -X POST "https://stylor.ai/api/v1/products" \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "itemIds": [
    "35a725c8-23fb-4009-a52a-2a778d2e504a",
    "a342cbe3-965b-4055-8ac3-20f63103cade"
  ],
  "country": "CA"
}'
Response · 200
{
  "products": [
    {
      "itemId": "35a725c8-23fb-4009-a52a-2a778d2e504a",
      "organizationId": "0b7c3d9e-1f2a-4b3c-9d8e-7f6a5b4c3d2e",
      "datasetId": "c1a2b3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "active",
      "version": 4,
      "product": {
        "name": "SLIM JEAN DENIM",
        "url": "https://ca.stussy.com/products/slim-jean-denim",
        "price": 195,
        "currency": "CAD",
        "market": "ca",
        "marketExact": true,
        "variants": [
          {
            "label": "Dark Wash Indigo / 30",
            "options": [
              {
                "name": "Color",
                "value": "Dark Wash Indigo"
              },
              {
                "name": "Size",
                "value": "30"
              }
            ],
            "inStock": false,
            "price": 195
          },
          {
            "label": "Dark Wash Indigo / 34",
            "options": [
              {
                "name": "Color",
                "value": "Dark Wash Indigo"
              },
              {
                "name": "Size",
                "value": "34"
              }
            ],
            "inStock": true,
            "price": 195
          }
        ],
        "assets": {
          "images": [
            {
              "originalImageUrl": "https://ca.stussy.com/cdn/shop/files/slim-jean-1.jpg",
              "uploaded": {
                "key": "v1/datasets/images/598fb45a-b960-4224-a83c-e9663116830d.jpeg",
                "url": "https://stylor.ai/api/v1/image/v1/datasets/images/598fb45a-b960-4224-a83c-e9663116830d.jpeg"
              }
            }
          ]
        }
      },
      "metadata": {
        "gender": "mens",
        "age_group": "adult",
        "slot": "bottom",
        "family": "jeans",
        "color_family": "blue",
        "fit": "slim"
      },
      "origin": {
        "siteUrl": "https://ca.stussy.com",
        "brandId": "ca-stussy-com",
        "brand": "Stussy"
      }
    }
  ]
}