Get product by ID or variant ID

Retrieve complete details for a single product using either its product ID or variant ID.

Response Structure:

• Simple products (no variants): Flat structure with all data at root level
• Multi-variant products: Hierarchical structure with:
  • Product-level data at root (name, description, brand, media, etc.)
  • Aggregate data (total_stock, price_range using selling_price)
  • Clean variants array with only variant-specific fields (no redundancy)

Field Filtering: Supports both root-level and nested variant filtering:

• Root filtering: ~ 38% bandwidth reduction
• Nested filtering: ~ 52% bandwidth reduction
• Example: fields=name,price_range,variants.sku,variants.selling_price,variants.stock

Currency: Prices returned in store’s default currency. For multi-currency support with geographic detection, use the /v1/prices/products/{id} endpoint instead.

GET /v1/products/{id}

Get product by ID or variant ID

cURL

curl --request GET \
  --url https://api.tybritelabs.com/v1/products/{id} \
  --header 'Authorization: Bearer <token>'

200

simple_product

{
  "product_id": "d8cea277-9bb6-4942-b9e9-2f2ac351509f",
  "name": "Apple MacBook Pro",
  "description": "13-inch MacBook Pro with M2 chip",
  "category_id": "90ed1bf0-6c3f-4ad8-8b17-bf0b63bd3d45",
  "category_name": "Laptops",
  "brand": "Apple",
  "thumbnail_url": "https://images.unsplash.com/photo-1517336714731-489689fd1ca8",
  "media": [],
  "variant_id": "cc35d16b-fca5-4faa-8699-d3d5d3521bca",
  "sku": "APP-MBP-13",
  "price": 189999,
  "selling_price": 189999,
  "stock": 39,
  "threshold": 30,
  "last_restocked": "2025-12-16",
  "has_variants": false,
  "display_currency": "USD",
  "currency_symbol": "$",
  "is_active": true,
  "created_at": "2025-12-16T07:58:03.673701+00:00",
  "updated_at": "2026-01-10T12:37:39.284762+00:00"
}

Authorizations

Authorization · string · header · required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

• Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
• Full read/write access to all endpoints
• ⚠️ NEVER expose in client-side code or public repositories
• Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

• Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
• Read-only access (GET requests only, plus POST semantic search)
• ✅ Safe for client-side JavaScript, mobile apps, and public code
• Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

• Authentication endpoints (/v1/auth/*): Secret key required
• Payment verification (POST /v1/payments/verify): Secret key required
• AI Recommendations (POST /v1/recommendations): Secret key required
• Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
• All write operations: Secret key required
• All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Path Parameters

id · string<uuid> · default: d8cea277-9bb6-4942-b9e9-2f2ac351509f · required

Product ID or Variant ID. This endpoint accepts both types of IDs, providing flexible product retrieval.

Accepted ID Types:

• Product ID: The main product identifier (e.g., d8cea277-9bb6-4942-b9e9-2f2ac351509f)
• Variant ID: A specific variant identifier (e.g., cc35d16b-fca5-4faa-8699-d3d5d3521bca)

Why This Matters:

• Simplifies API usage - no need to know if you have a product or variant ID
• Useful for barcode scanning where you might have variant IDs
• Consistent behavior regardless of ID type

Validation:

• Must be a valid UUID format
• Must exist in your store's product catalog
• Returns 404 if product/variant not found

SDK Usage:

// Works with product ID
const product1 = await client.products.getProduct(
  'd8cea277-9bb6-4942-b9e9-2f2ac351509f'
);
  
// Also works with variant ID
const product2 = await client.products.getProduct(
  'cc35d16b-fca5-4faa-8699-d3d5d3521bca'
);

Query Parameters

fields · string

Comma-separated list of fields to include in the response. Supports both root-level and nested variant filtering for maximum bandwidth optimization.

Root-Level Fields:

• Core: product_id, variant_id, name, sku, description
• Pricing: price, selling_price, sale_price, price_range, display_currency, currency_symbol
• Inventory: stock, total_stock, threshold, last_restocked
• Media: media, thumbnail_url
• Metadata: brand, category_name, subcategory_name, attributes.*
• Flags: has_variants, variant_count, is_default
• Variants: variants (includes all variant fields)

Nested Variant Filtering (52% bandwidth reduction): Use dot notation to filter specific fields within the variants array:

• variants.variant_id - Variant identifier
• variants.sku - Variant SKU
• variants.selling_price - Customer-facing price
• variants.stock - Stock quantity
• variants.variant_attributes - Variant attributes (color, size, etc.)
• variants.variant_name - Variant display name
• variants.is_default - Default variant flag
• variants.* - All variant fields (same as just variants)

Bandwidth Savings:

• Full product: ~1720 bytes (baseline)
• Root filtering: 1060 bytes ( 38% reduction)
• Nested filtering: 830 bytes ( 52% reduction)

Examples:

Root-level filtering (~ 38% reduction):

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

Nested variant filtering (~ 52% reduction):

fields=product_id,name,brand,total_stock,price_range,
  variants.variant_id,variants.sku,variants.selling_price,
  variants.stock,variants.variant_attributes

Minimal cart validation:

fields=product_id,total_stock,variants.variant_id,variants.stock

SDK Usage:

// Root-level filtering
const product = await client.products.getProduct(productId, {
  fields: 'name,price_range,total_stock,variants'
});
  
// Nested variant filtering (maximum optimization)
const product = await client.products.getProduct(productId, {
  fields: 'name,brand,price_range,variants.sku,variants.selling_price,variants.stock'
});

Performance Impact:

• Nested filtering excludes internal fields (threshold, last_restocked)
• Perfect for mobile apps and bandwidth-constrained environments
• Recommended for product cards and listing pages

Response

200

application/json

Successfully retrieved product with complete details.

Response Structure:

For Simple Products (has_variants=false): Returns flat structure with all data at root level:

• All product fields (name, description, brand, media, etc.)
• All variant fields (variant_id, sku, price, stock, etc.)
• No variants array

For Multi-Variant Products (has_variants=true): Returns hierarchical structure:

• Product-level fields at root (name, description, brand, media, etc.)
• Aggregate data: total_stock, price_range (using selling_price)
• Flags: has_variants=true, variant_count
• Clean variants array with only variant-specific fields:
  • variant_id, sku, price, sale_price, selling_price
  • stock, threshold, last_restocked
  • variant_attributes (color, size, etc.)
  • variant_name, is_default

Field Filtering:

• Root-level: Exclude unnecessary fields (~ 38% reduction)
• Nested: Filter variant fields using dot notation (~ 52% reduction)
• Example: fields=name,price_range,variants.sku,variants.selling_price,variants.stock

SDK Usage:

const product = await client.products.getProduct(productId);
  
if (product.has_variants) {
  console.log(`Price range: ${product.price_range.min} - ${product.price_range.max}`);
  console.log(`Total stock: ${product.total_stock}`);
  console.log(`Variants: ${product.variants.length}`);
} else {
  console.log(`Price: ${product.selling_price}`);
  console.log(`Stock: ${product.stock}`);
}

Represents a product in the catalog. Response structure varies based on endpoint and variant configuration:

List Endpoint (GET /v1/products):

• Returns flat structure with default variant data only
• No variants array (keeps payload small for browsing)
• Includes has_variants flag to indicate if detail fetch needed

Detail Endpoints (GET /v1/products/:id, GET /v1/products/by-slug/:slug):

• Multi-variant products: Hierarchical structure with product-level data at root + variants array
• Simple products: Flat structure with all data at root (no variants array)

Field Filtering:

• Root-level filtering: Reduce top-level fields
• Nested filtering: Filter specific variant fields using dot notation
• Example: fields=name,price_range,variants.sku,variants.selling_price,variants.stock

product_id · string<uuid>

Main product identifier

Example:

"d8cea277-9bb6-4942-b9e9-2f2ac351509f"

name · string

Product name (mapped from online_name or name)

Example:

"Sony WH-1000XM4"

description · string

Product description (mapped from online_description or description)

Example:

"Wireless noise-cancelling headphones"

category_id · string<uuid> | null

Category UUID

category_name · string | null

Category display name

Example:

"Electronics"

subcategory_id · string<uuid> | null

Subcategory UUID

subcategory_name · string | null

Subcategory display name

Example:

"Headphones"

brand · string | null

Product brand

Example:

"Sony"

thumbnail_url · string<uri> | null

Primary image URL for list views

Example:

"https://pub-...r2.dev/stores/.../primary-123.jpg"

media · object[]

Array of product media objects including images and videos

Show child attributes

product_slug · string | null

SEO-friendly URL slug

Example:

"sony-wh-1000xm4-abc123"

seo_title · string | null

SEO optimized title

seo_description · string | null

SEO optimized description

seo_keywords · string | null

SEO keywords

featured · boolean | null

Whether product is featured

featured_order · integer | null

Display order for featured products

online_category · string | null

Merged category/subcategory string

tags · string[] | null

Product tags

attributes · object

Product-level attributes (not variant-specific)

shipping_info · object

Shipping dimensions and weight

Show child attributes

created_at · string<date-time> | null

Product creation timestamp

updated_at · string<date-time> | null

Last update timestamp

is_active · boolean | null

Whether product is active

variant_id · string<uuid> | null

Variant identifier (only present for simple products or list endpoint)

Example:

"cc35d16b-fca5-4faa-8699-d3d5d3521bca"

sku · string | null

Stock Keeping Unit (only present for simple products or list endpoint)

Example:

"SNY-WH1000"

price · number | null

Base price in cents (only present for simple products or list endpoint)

Example:

36999

sale_price · number | null

Sale price in cents if on sale

selling_price · number | null

Actual customer-facing price (considers sale_price)

Example:

34999

stock · integer | null

Available stock quantity (only present for simple products or list endpoint)

Example:

40

threshold · integer | null

Low stock threshold

last_restocked · string<date> | null

Last restock date

variant_attributes · object

Variant-specific attributes (e.g., color, size)

Example:

{ "color": "Black" }

variant_name · string | null

Variant display name

is_default · boolean | null

Whether this is the default variant

total_stock · integer | null

Sum of stock across all variants (only present for multi-variant products)

Example:

85

price_range · object

Price range across variants using selling_price (only present for multi-variant products)

Show child attributes

has_variants · boolean

Whether product has multiple variants

Example:

true

variant_count · integer | null

Number of variants (only present for multi-variant products)

Example:

3

display_currency · string

Store's default currency code

Example:

"EUR"

currency_symbol · string

Currency symbol

Example:

"€"

variants · object[] | null

Array of product variants (only present for multi-variant products in detail endpoints)

Show child attributes