Products

The ProductsService class (accessed via client.products) reads a store’s catalog: products and their variants, filtering and pagination across them, product specifications, and the collections products are grouped into.

Validation & Rate Limits: Product IDs must be valid UUIDs — malformed IDs return 400 immediately. All endpoints are rate-limited (publishable key: 1,000 requests/hr per IP; secret key: 10,000 requests/hr per key).

Product identifier: every product object exposes both id and product_id. They are the same value — use whichever fits your codebase.

Response Structure Tiers

To optimize performance across different device types, the service implements three response tiers:

Tier	Endpoint	Structure	Use Case
Tier 1: Catalog	`listProducts`	Flat: Root-level default variant data.	Homepages, Category Grids, Search.
Tier 2: PDP (Multi)	`getProduct`	Hierarchical: Root metadata + `variants` array.	Detail pages where users select options.
Tier 3: PDP (Simple)	`getProduct`	Flat: Full detail without `variants` array.	Single-variant products (no selection needed).

Catalog Discovery

`listProducts`

Retrieve a paginated list of products. This method returns flat structures (no variants array) to keep payloads small.

⚡ Performance: 50-70% smaller than detail endpoints.
🖼️ Thumbnails: Use thumbnail_url for fast rendering in lists without iterating arrays.
🛒 Quick Add: Includes default variant data (price, stock, sku) at root level.
🔍 Intelligence: Use the has_variants flag to determine if the UI should show “View Options”.
⏩ Pagination: Uses cursor-based navigation for stable, high-performance scrolling.

Lean by default. The list omits heavy fields a catalog grid rarely needs — the long-form description, the SEO block (seo_title / seo_description / seo_keywords), raw attributes / shipping_info, and the full media arrays — so grids stay fast. Get those on the detail calls (getProduct / getProductBySlug), request them explicitly with fields (e.g. fields: 'name,price,description,seo_title'), or pass full: true to return the complete object for every row. thumbnail_url, price, stock, has_variants and the taxonomy fields are always present.

const { products, pagination } = await client.products.listProducts({
  search: 'Sony',
  limit: 20,
  fields: 'name,price,stock,has_variants,product_slug,thumbnail_url'
});

// For subsequent pages, pass the cursor from the previous response:
// const next = await client.products.listProducts({ limit: 20, cursor: pagination.next_cursor });

console.log(`Has more: ${pagination.has_more}`);
if (pagination.next_cursor) {
  // Use pagination.next_cursor for the subsequent request
}

Response

{
  "products": [
    {
      "name": "Sony WH-1000XM4",
      "price": 349.99,
      "stock": 79,
      "has_variants": true,
      "product_slug": "sony-wh-1000xm4-a089d-7d425c0a",
      "thumbnail_url": "https://cdn.example.com/.../primary-1774785176485.jpg"
    }
  ],
  "pagination": {
    "limit": 20,
    "next_cursor": "MGM0OThhYzItNGI3Ny00YjAzLWE5YjgtZGJkNDY2MWVmYTU0",
    "has_more": true
  }
}

Personalized ordering

Pass personalize: true together with a signed-in customer’s session token (the x-auth-token header) and the page is ordered by how closely each product matches that shopper’s preferences, with the default order as the tiebreak. Without a customer session — or for a shopper who has no preference signal yet — the order is unchanged, so it is always safe to request.

const personalized = new Tybrite({
  apiKey: 'tybrite_pk_live_...',
  headers: { 'x-auth-token': customerSessionToken },
});

const { products } = await personalized.products.listProducts({
  personalize: true,
  limit: 20,
  fields: 'name,price,thumbnail_url'
});
// returns products re-ordered by how closely each matches this shopper; same row shape as above:
//   [ { name: "Sony WH-1000XM4", price: 349.99, thumbnail_url: "https://cdn.example.com/..." }, ... ]

Filter by brand. Pass brand (case-insensitive exact match) to build a brand landing page — pair it with listBrands below to render a “shop by brand” row, then list the chosen brand’s products:

const { products } = await client.products.listProducts({ brand: 'Samsung', limit: 20 });

Filter by category and subcategory

category_id and subcategory_id both match a whole branch of the taxonomy rather than a single node. A category matches products filed directly against it and products filed under any of its subcategories, at any depth; a subcategory matches products filed against it and every nested subcategory beneath it. A category page therefore returns the products of the branch as a shopper understands it — a “Computers” category includes everything under “Laptops” without listing each subcategory separately.

const { products, pagination } = await client.products.listProducts({
  categoryId: '0a4c2c19-16a6-4b1e-9d0e-4d8f1a6b2c37',
  limit: 20
});

Each value must be a valid UUID. An id that matches nothing returns an empty products array with a 200, not an error. The two filters can be combined, in which case a product must match both. The subcategories of a category are available from GET /v1/subcategories?category_id=…. Several ids in one request. Both parameters accept multiple ids, in three forms:

Form	Example
Repeated	`category_id=a&category_id=b`
Bracketed	`category_id[]=a&category_id[]=b`
Comma-separated	`category_id=a,b`

Passing several ids to one request keeps a single pagination cursor valid across the combined set. One request per category yields a separate cursor per response, and those cursors cannot be merged into a coherent page 2 — so a landing page spanning several categories is built from one multi-id request, not from several single-id requests stitched together.

`listBrands`

Return the catalog’s distinct brands, each with a product count, sorted by count (most products first). Use it to build brand navigation — for example a “featured brands” row after the hero — then pass a chosen brand to listProducts({ brand }).

const { brands, total } = await client.products.listBrands();

Response

{
  "brands": [
    { "brand": "Samsung", "product_count": 12 },
    { "brand": "Apple", "product_count": 9 },
    { "brand": "Sony", "product_count": 4 }
  ],
  "total": 3
}

On a marketplace operator key the brands are aggregated across all active merchants; pass storeId to scope to one merchant.

`getProduct`

Retrieve complete details for a single item. This method handles Multi-Variant products by returning a hierarchical structure that eliminates data redundancy and supports variant-aware media.

Product-Level: Shared metadata at the root (name, brand, media gallery).
Aggregate Data: total_stock (sum of all variants) and price_range (min/max using selling_price).
Variants Array: Clean array containing variant-specific attributes (color, size, SKU) and isolated media for that specific variation.

const product = await client.products.getProduct({
  id: '7d425c0a-50e7-4e39-af79-6f7945f9dfa8', // a multi-variant product (Sony WH-1000XM4)
  fields: 'name,thumbnail_url,media,price_range,total_stock,variants.sku,variants.media,variants.variant_attributes'
});

if (product.has_variants) {
  console.log(`Variants available: ${product.variant_count}`);
  console.log(`Price Range: ${product.price_range.min} - ${product.price_range.max}`);

  // Access variant-specific media (e.g., if user selects 'Grey' color)
  const greyVariant = product.variants.find(v => v.variant_attributes?.color === 'Grey');
  console.log(`Grey variation images: ${greyVariant?.media.length}`);
}

A multi-variant detail response (here shown for the “Nebula Ceramic Mug”, a 3-variant product) — root metadata plus aggregate price_range / total_stock and a clean variants[] array, each with its own SKU, attributes, and isolated media:

Response

{
  "product_id": "2b6a066a-25df-4238-9e90-50a4400fc21e",
  "name": "Nebula Ceramic Mug",
  "thumbnail_url": "https://cdn.example.com/seed/apimugblue/400",
  "media": [],
  "has_variants": true,
  "variant_count": 3,
  "total_stock": 397,
  "price_range": { "min": 14.99, "max": 15.55 },
  "variants": [
    { "sku": "API-MUG-WHT-2b6a", "variant_attributes": null, "variant_name": "White", "is_default": true,  "media": [] },
    { "sku": "API-MUG-BLU-2b6a", "variant_attributes": null, "variant_name": "Blue",  "is_default": false, "media": [] },
    { "sku": "API-MUG-BLK-2b6a", "variant_attributes": null, "variant_name": "Black", "is_default": false, "media": [] }
  ]
}

`getProductBySlug`

Retrieve a product using its SEO-friendly slug. Identical to getProduct in response structure but optimized for PDP routing.

const product = await client.products.getProductBySlug({
  slug: 'sony-wh-1000xm4-a089d-7d425c0a',
  fields: 'seo_title,seo_description,thumbnail_url,media,price_range,variants.*'
});
// returns identical structure to getProduct: root metadata + (for multi-variant products)
//   price_range, total_stock, and a variants[] array. See the getProduct response above.

SEO metadata

Every product carries optional SEO metadata for rendering search-engine-friendly product detail pages:

seo_title — the <title> for the product page.
seo_description — the meta description.
seo_keywords — an array of keywords.

const product = await client.products.getProductBySlug({ slug: 'sony-wh-1000xm4-a089d-7d425c0a' });
// returns product.seo_title, product.seo_description, and product.seo_keywords (string[]) are present
//   when set, e.g. seo_title: "Nebula Ceramic Mug | 350ml Dishwasher Safe",
//   seo_keywords: ["ceramic mug", "stoneware mug", "coffee mug", "dishwasher safe mug"]
document.title = product.seo_title ?? product.name;
// <meta name="description" content={product.seo_description ?? product.description} />

These fields are also included in a store’s public catalog feed, so a catalog mirrored from one store into another preserves its SEO metadata.

📸 Media Gallery System

The media system supports a fully-functional, variant-aware gallery.

Root-Level Media

thumbnail_url: Represents the primary image for the product. Perfect for simple grids.
media: An array of objects containing all base-level images and videos.

Variant Media

Each variant in the variants[] array can have its own media array. This allows you to show specific images when a user selects a particular variation (e.g., rotating the gallery to show the “Midnight Blue” model). Media Object Structure:

Field	Type	Description
`id`	`uuid`	Unique identifier for the media item.
`url`	`string`	Full CDN URL for the asset.
`type`	`string`	`image` or `video`.
`position`	`number`	Explicit sort order (starting from 0).
`alt_text`	`string`	Accessibility text.
`is_primary`	`boolean`	Whether this is the main image (used for `thumbnail_url`).

🎨 Advanced Field Filtering

Tybrite supports powerful field selection to minimize bandwidth.

Root-Level Filtering

Exclude large metadata objects by selecting only top-level fields.

fields=product_id,name,brand,thumbnail_url,total_stock,price_range,variants

Nested Array Filtering

Use dot notation to select specific fields within nested arrays.

# Get only the SKU and specific media for each variant
fields=name,variants.sku,variants.media,variants.variant_attributes

Supported Fields for Filtering:

Core: product_id, name, sku, description, thumbnail_url, media
Pricing: price, selling_price, sale_price, price_range
Inventory: stock, total_stock, last_restocked (last_restocked is not returned by default — request it explicitly)
Variants: variants.sku, variants.selling_price, variants.media, variants.variant_attributes

Product Specifications

`getProductSpecifications`

Retrieve the latest published specifications for a single variant. Specifications are stored per variant, so pass a variant id (e.g. a variant_id from getProduct().variants[]) — not a product id. A product id returns 404.

const { specification_data } = await client.products.getProductSpecifications({
  id: '9a47e047-b1b6-4c35-9617-820629e22e04' // a VARIANT UUID (not a product id)
});

Response

{
  "id": "3b16b560-418f-4fe5-a35e-7ce9c214d795",
  "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
  "template_id": "599b4ff3-bda4-463d-a22e-e631d834875a",
  "specification_data": {
    "brand": "Sony",
    "color": "Black",
    "model": "WH-1000XM4",
    "product_type": "Accessory",
    "storage_type": "HDD"
  },
  "status": "published",
  "version": 1,
  "created_at": "2026-06-20T10:05:26.106528+00:00",
  "updated_at": "2026-06-20T10:05:26.106528+00:00"
}

Returns 404 (“No specifications found for this product”) if the variant has no published specification — or if you passed a product id instead of a variant id. To browse all specs across the catalog (each tagged with its variant_id), use listProductSpecifications.

`getProductCustomFields`

Retrieve the merchant’s own custom fields for a product. A merchant can define fields Galactic Core does not — a care instruction, a country of origin, a fabric composition — and fill them per product. Only fields the merchant published are returned. A custom field can hold a cost or an internal reference, so a field is private unless it is explicitly marked public, and a private field is absent rather than empty. A product with no published fields returns an empty array.

const { custom_fields } = await client.products.getProductCustomFields({
  id: '02525ff5-0916-4f00-857c-c2c6237e671b'
});

for (const field of custom_fields) {
  console.log(field.field_label, field.value); // "Care instructions" "Machine wash at 30"
}

Response

{
  "custom_fields": [
    {
      "field_name": "care_instructions",
      "field_label": "Care instructions",
      "field_type": "text",
      "unit_type": null,
      "value": "Machine wash at 30"
    }
  ]
}

The merchant controls both the field names and how many exist, so render the array rather than reading fixed keys. See Custom Fields for the full picture — which records carry them, what each type looks like, and how to send values with an order. field_type tells you the shape of value: multiselect is an array of strings, json, dimensions and weight are objects, and the rest are scalars — a number field arrives as a number, not as text. field_label is what the merchant calls the field and is the string to show; field_name is stable across label edits and is the one to key off in code.

value is null when the merchant defined a field but has not filled it for this product, which is distinct from the field not existing.

`listProductSpecifications`

Browse specifications across the catalog rather than fetching one variant’s. Useful for building a spec-driven filter (every value of “storage_type” in stock, say) without a request per variant.

const { specifications, pagination } = await client.products.listProductSpecifications({
  status: 'published',
  limit: 50
});

Response

{
  "specifications": [
    {
      "id": "12df2fed-8c31-4d0e-9b77-2a5c4f8e1b90",
      "variant_id": "9a47e047-b1b6-4c35-9617-820629e22e04",
      "template_id": "599b4ff3-bda4-463d-a22e-e631d834875a",
      "specification_data": {
        "brand": "Sony",
        "color": "Black",
        "model": "WH-1000XM4"
      },
      "status": "published",
      "version": 1,
      "created_at": "2026-06-20T10:05:26.106528+00:00",
      "updated_at": "2026-06-20T10:05:26.106528+00:00"
    }
  ],
  "pagination": { "limit": 50, "next_cursor": null, "has_more": false }
}

Parameter	Required	Description
`productId`	no	Narrows to a single variant’s specifications. Despite the name this matches on `variant_id` — pass a variant UUID, not a product UUID.
`status`	no	Filter by publication state, e.g. `published` or `draft`.
`limit`	no	Page size, default 50.
`cursor`	no	Pass `pagination.next_cursor` from the previous response to page.

Each entry carries its own variant_id, so a single pass over the list can be grouped by variant without further lookups.

Collections

Curated groups of products a merchant highlights on their storefront — a “Featured”, “New Arrivals”, or “Summer Edit” row. Each collection can carry a banner image, which makes it a natural building block for an image-led homepage.

`listProductCollections`

// List all active collections
const { collections } = await client.products.listProductCollections({ 
  showOnHomepage: 'true',
  limit: 20
});

Response

{
  "collections": [
    {
      "id": "45e28d12-9381-45f6-98bb-cb3a34c0a215",
      "name": "Featured",
      "slug": "featured",
      "description": "Hand-picked products to highlight on your storefront.",
      "collection_type": "featured_collections",
      "is_active": true,
      "show_on_homepage": true,
      "display_priority": 0,
      "image": "https://media.example.com/collections/featured-desktop.jpg",
      "image_mobile": "https://media.example.com/collections/featured-mobile.jpg"
    },
    {
      "id": "e9810818-5051-4b74-a53b-2ff843b4f435",
      "name": "New Arrivals",
      "slug": "new-arrivals",
      "description": null,
      "collection_type": "new_arrivals",
      "is_active": true,
      "show_on_homepage": true,
      "display_priority": 1,
      "image": null,
      "image_mobile": null
    }
  ],
  "pagination": { "limit": 20, "next_cursor": null, "has_more": false }
}

image is the collection’s banner and the image to use on every viewport; image_mobile is an optional phone-sized crop. Render the mobile image on small screens when it is set and fall back to image otherwise — a <picture> element with a mobile <source> handles this cleanly. Either field is null when the merchant has not added artwork.

`getProductCollection`

Fetch a single collection by id — the same shape listProductCollections returns for that entry, so use it when you land directly on a collection page and have only the id from the URL. A collection the merchant built from rules rather than by hand also carries those rules.

const collection = await client.products.getProductCollection({
  id: '45e28d12-9381-45f6-98bb-cb3a34c0a215'
});

Response

{
  "id": "45e28d12-9381-45f6-98bb-cb3a34c0a215",
  "name": "Featured",
  "slug": "featured",
  "description": "Hand-picked products to highlight on your storefront.",
  "collection_type": "featured_collections",
  "is_active": true,
  "show_on_homepage": true,
  "display_priority": 0,
  "image": "https://media.example.com/collections/featured-desktop.jpg",
  "image_mobile": "https://media.example.com/collections/featured-mobile.jpg",
  "rules": { "type": "manual" },
  "created_at": "2026-06-20T10:05:26.106528+00:00",
  "updated_at": "2026-06-20T10:05:26.106528+00:00"
}

rules describes how an automated or smart collection selects its products, and is null for a collection the merchant curated by hand. Returns 404 when no collection matches the id.

`getProductCollectionItems`

// Get items in a specific collection (returns all items, ordered by sort_order)
// Each item has: product_id, sort_order, and an embedded product object
const { items } = await client.products.getProductCollectionItems({
  id: '45e28d12-9381-45f6-98bb-cb3a34c0a215' // e.g. the "Featured" collection
});

for (const item of items) {
  console.log(`${item.product.name} — sort order: ${item.sort_order}`);
}

Response

{
  "items": [
    {
      "product_id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
      "sort_order": 0,
      "product": {
        "id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
        "name": "Sony WH-1000XM4",
        "slug": "sony-wh-1000xm4-a089d-7d425c0a",
        "brand": "Sony",
        "has_variants": true,
        "is_active": true
      }
    }
  ]
}

An empty collection returns { "items": [] }.

Response Codes

All product endpoints are GET and accept both publishable and secret keys.

Code	Meaning
`200`	Success.
`400`	Invalid request — malformed UUID, invalid slug, or unrecognized field in the `fields` parameter.
`401`	Invalid or missing API key.
`404`	Product, collection, or specification not found (single-resource endpoints only). List endpoints return `200` with an empty array.
`429`	Rate limit exceeded (1,000/hr per IP for `pk_`; 10,000/hr per key for `sk_`).
`500`	Internal server error.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Response Structure Tiers

Catalog Discovery

`listProducts`

Personalized ordering

Filter by category and subcategory

`listBrands`

`getProduct`

`getProductBySlug`

SEO metadata

📸 Media Gallery System

Root-Level Media

Variant Media

🎨 Advanced Field Filtering

Root-Level Filtering

Nested Array Filtering

Product Specifications

`getProductSpecifications`

`getProductCustomFields`

`listProductSpecifications`

Collections

`listProductCollections`

`getProductCollection`

`getProductCollectionItems`

Response Codes

​Response Structure Tiers

​Catalog Discovery

​listProducts

​Personalized ordering

​Filter by category and subcategory

​listBrands

​getProduct

​getProductBySlug

​SEO metadata

​📸 Media Gallery System

​Root-Level Media

​Variant Media

​🎨 Advanced Field Filtering

​Root-Level Filtering

​Nested Array Filtering

​Product Specifications

​getProductSpecifications

​getProductCustomFields

​listProductSpecifications

​Collections

​listProductCollections

​getProductCollection

​getProductCollectionItems

​Response Codes

Response Structure Tiers

Catalog Discovery

`listProducts`

Personalized ordering

Filter by category and subcategory

`listBrands`

`getProduct`

`getProductBySlug`

SEO metadata

📸 Media Gallery System

Root-Level Media

Variant Media

🎨 Advanced Field Filtering

Root-Level Filtering

Nested Array Filtering

Product Specifications

`getProductSpecifications`

`getProductCustomFields`

`listProductSpecifications`

Collections

`listProductCollections`

`getProductCollection`

`getProductCollectionItems`

Response Codes