POST /products/retrieve — read back up to 50 products by id

POST /v1/products/retrieve is the batch form of Retrieve Product. It reads back 1–50 products you already hold ids for, such as a cart or a saved list, in one request. Like the single form, it reads the index only, never fetches from the merchant, and is not billed.

Request

POST https://api.storerouter.ai/v1/products/retrieve
Authorization: Bearer <your-platform-api-key>
Content-Type: application/json

Body parameters

string[] (UUID)

required

1–50 product ids from earlier responses. Older ids for a product still work. Results come back in this order, one per entry, duplicates included. A value that is not a UUID returns 422.

Example

curl -sS https://api.storerouter.ai/v1/products/retrieve \
  -H "Authorization: Bearer $OCTOGEN_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uuids": [
      "0c0e3bb8-965a-4f2d-919b-182e7a24efc9",
      "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
    ]
  }'

Response

ProductRetrieveResult[]

required

One result per requested id, in request order. A miss never fails the request.

Show ProductRetrieveResult properties

string

required

The id you sent, in canonical lowercase form.

"found" | "not_found"

required

not_found covers an unknown id, a product that left the index, and a product outside your key’s catalog access.

string | null

The product’s current id. Store this one. null when not_found.

string | null

Catalog that supplies the product.

string | null

Human-readable catalog name.

string | null

Catalog source base URL, when configured.

boolean | null

false when the merchant no longer offers the product.

datetime | null

When the product was last deactivated, if it ever was.

MerchantProductView | null

The same product view lookup returns. null when not_found.

Example

{
  "results": [
    {
      "requestedUuid": "0c0e3bb8-965a-4f2d-919b-182e7a24efc9",
      "status": "found",
      "uuid": "464ec980-996e-4069-bb2d-16cfaae0e558",
      "catalogKey": "warrenlotas",
      "catalogDisplayName": "Warren Lotas",
      "sourceBaseUrl": "https://warrenlotas.com",
      "isActive": true,
      "lastDeactivatedAt": null,
      "product": {
        "uuid": "464ec980-996e-4069-bb2d-16cfaae0e558",
        "catalogKey": "warrenlotas",
        "productUrl": "https://warrenlotas.com/products/black-hoodie",
        "title": "Black Hoodie",
        "isActive": true
      }
    },
    {
      "requestedUuid": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "status": "not_found",
      "uuid": null,
      "catalogKey": null,
      "catalogDisplayName": null,
      "sourceBaseUrl": null,
      "isActive": null,
      "lastDeactivatedAt": null,
      "product": null
    }
  ]
}

Errors

Status	`detail`	Meaning
`422`	validation errors	`uuids` is empty, has more than 50 entries, or contains a value that is not a UUID.
`429`	`rate_limit_exceeded` or `retrieve_daily_item_limit_exceeded`	See Rate limits. Each id counts toward the daily ceiling. Honor `Retry-After`.
`503`	`product_retrieve_index_unavailable`	The index is busy. Retry after `Retry-After`.

Catalog API

Brands API

Coverage API

Data Models

POST /products/retrieve — read back up to 50 products by id

Request

Body parameters

Example

Response

Example

Errors

​Request

​Body parameters

​Example

​Response

​Example

​Errors

Request

Body parameters

Example

Response

Example

Errors