Products API — Browse and Search the Product Catalog

The Products API gives you access to the full customer-facing product catalog. Use it to build storefront listing pages, search interfaces, and product detail views. Both endpoints are fully public — no session cookie is required. All money values are decimal strings (e.g., "99.99"), and all timestamps are ISO 8601 UTC.

List Products

Only products that have at least one ACTIVE variant and have not been soft-deleted are included in the public listing. Draft, inactive, and archived variants are invisible to customers.

Retrieve a paginated list of products. Optionally filter by brand or free-text search across name, brand, and description. Sort by name or recency.

GET /products

Query parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Number of results per page. Minimum 1, maximum 100.

string

Free-text search across product name, brand, and description (trimmed, max 100 characters).

string

Filter by exact brand name (trimmed, case-sensitive, max 255 characters). Example: Nike.

string

default:"-created_at"

Sort field. Prefix with - for descending. Allowed values: name, -name, created_at, -created_at, updated_at, -updated_at.

Response fields

boolean

Always true on a successful response.

array

Array of product summary objects.

Show Product summary object

string

Stable public identifier for the product. Pattern: prd_*. Use this ID with GET /products/{product_public_id}.

string

Display name of the product (e.g., "Runner Sneaker").

string

URL-safe slug derived from the product name (e.g., "runner-sneaker").

string | null

Brand name string, or null if no brand is set.

object | null

The product’s primary image, or null if no images have been uploaded.

Show primary_image fields

string

Fully-qualified ImageKit URL of the primary image.

string | null

Alt text for the image, or null if not set.

string

ISO 8601 UTC timestamp of when the product was created.

object

Pagination metadata.

Show Pagination meta fields

integer

Current page number.

integer

Items per page.

integer

Total matching products.

integer

Total number of pages.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

Example — List the newest Nike products

curl -G https://api.example.com/api/v1/products \
  --data-urlencode "brand=Nike" \
  --data-urlencode "sort=-created_at" \
  --data-urlencode "limit=20"

const response = await fetch(
  'https://api.example.com/api/v1/products?brand=Nike&sort=-created_at&limit=20'
);
const { data, meta } = await response.json();
console.log(`Found ${meta.total} products, showing page ${meta.page}`);

Example response

{
  "success": true,
  "data": [
    {
      "public_id": "prd_01H",
      "name": "Runner Sneaker",
      "slug": "runner-sneaker",
      "brand": "Nike",
      "primary_image": {
        "image_url": "https://ik.imagekit.io/demo/products/runner-sneaker.jpg",
        "alt_text": "Runner Sneaker front view"
      },
      "created_at": "2024-03-15T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Get Product Details

Retrieve a single product by its public ID. The response includes the full image gallery (ordered by display_order) and all active variants with computed pricing.

GET /products/{product_public_id}

Path parameters

string

required

The product’s public ID. Pattern: prd_*.

Response fields

object

Full product detail object.

Show Product detail fields

string

Public identifier. Pattern: prd_*.

string

Product display name.

string

URL-safe slug.

string | null

Full product description in plain text, or null if not set.

string | null

Brand name, or null if not set.

array

All product images, sorted by display_order ascending.

Show Image object fields

string

Image identifier. Pattern: pimg_*.

string

Fully-qualified ImageKit URL.

string | null

Descriptive alt text, or null if not set.

integer

Sort position (0-based). The image with the lowest display order is shown first.

boolean

true for exactly one image per product — the main thumbnail.

array

Active variants only (status ACTIVE). Each variant represents a purchasable SKU.

Show Variant object fields

string

Variant identifier. Pattern: var_*. Use this as variant_public_id when adding to cart.

string

Stock-keeping unit code (e.g., "RUN-001-BLK-42").

string

Base price as a decimal string (e.g., "99.99").

string

Pre-computed sale price as a decimal string. Always display this value to customers — it is the authoritative price used at checkout.

Always display final_price to customers — it is the authoritative price computed server-side and used at checkout. Do not compute discounts client-side.

Example — Fetch a product detail page

curl https://api.example.com/api/v1/products/prd_01H

const response = await fetch(
  'https://api.example.com/api/v1/products/prd_01H'
);
const { data } = await response.json();

// Find the primary image
const primaryImage = data.images.find(img => img.is_primary);

// List purchasable variants
data.variants.forEach(v => {
  console.log(`${v.sku}: ${v.final_price} (was ${v.price})`);
});

Example response

{
  "success": true,
  "data": {
    "public_id": "prd_01H",
    "name": "Runner Sneaker",
    "slug": "runner-sneaker",
    "description": "Lightweight daily trainer with responsive cushioning.",
    "brand": "Nike",
    "images": [
      {
        "public_id": "pimg_01H",
        "image_url": "https://ik.imagekit.io/demo/products/runner-sneaker.jpg",
        "alt_text": "Runner Sneaker front view",
        "display_order": 0,
        "is_primary": true
      },
      {
        "public_id": "pimg_02H",
        "image_url": "https://ik.imagekit.io/demo/products/runner-sneaker-side.jpg",
        "alt_text": "Runner Sneaker side view",
        "display_order": 1,
        "is_primary": false
      }
    ],
    "variants": [
      {
        "public_id": "var_01H",
        "sku": "RUN-001-BLK-42",
        "price": "99.99",
        "final_price": "89.99"
      },
      {
        "public_id": "var_02H",
        "sku": "RUN-001-WHT-42",
        "price": "99.99",
        "final_price": "99.99"
      }
    ]
  }
}

Error responses

Status	Description
`400`	Invalid query parameter format.
`404`	Product not found, soft-deleted, or has no active variants.

Auth & Sessions

Account

Catalog

Cart & Checkout

Reviews

Products API — Browse and Search the Product Catalog

List Products

Get Product Details

​List Products

​Get Product Details

List Products

Get Product Details