Get product by SEO-friendly slug

Retrieve product information using a human-readable, SEO-friendly slug.

Response Structure: Same as GET /v1/products/:

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

Field Filtering: Supports root-level and nested variant filtering for bandwidth optimization.

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/by-slug/{slug}

Get product by SEO-friendly slug

cURL

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

200

simple_product_with_seo

{
  "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": [],
  "product_slug": "apple-macbook-pro-d8cea",
  "variant_id": "cc35d16b-fca5-4faa-8699-d3d5d3521bca",
  "sku": "APP-MBP-13",
  "price": 189999,
  "selling_price": 189999,
  "stock": 39,
  "has_variants": false,
  "display_currency": "USD",
  "currency_symbol": "$",
  "seo_title": "Apple MacBook Pro 13\" M2 - Premium Laptop",
  "seo_description": "13-inch MacBook Pro with M2 chip, perfect for professionals",
  "seo_keywords": "macbook, apple, laptop, m2",
  "featured": true,
  "featured_order": 0,
  "tags": [
    "laptop",
    "apple",
    "m2"
  ],
  "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

slug · string · default: apple-macbook-pro-d8cea · required

SEO-friendly product slug in the format {product-name}-{short-id}.

Slug Format:

• Lowercase product name with hyphens
• Short unique identifier appended
• Example: apple-macbook-pro-d8cea

Where to Get Slugs:

• From product_slug field in product list responses
• From product URLs in your e-commerce site
• Generated automatically when products are created

Validation:

• Must match an existing product slug
• Case-sensitive (use lowercase)
• Returns 404 if slug not found

SDK Usage:

// Use slug from product listing
const products = await client.products.listProducts({ limit: 10 });
const firstProductSlug = products.products[0].product_slug;
  
// Get full product details by slug
const product = await client.products.getProductBySlug(firstProductSlug);

SEO Benefits:

• Readable URLs: /products/apple-macbook-pro-d8cea vs /products/d8cea277-9bb6-4942-b9e9-2f2ac351509f
• Better click-through rates in search results
• Improved social media sharing
• Enhanced user trust and memorability

Required string length: 1 - 200

Pattern: ^[a-z0-9][a-z0-9-]{0,199}$

Query Parameters

fields · string

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

Recommended Fields for PDPs:

• SEO: seo_title, seo_description, seo_keywords, product_slug
• Core: product_id, name, description
• Pricing: price, selling_price, price_range (for multi-variant)
• Media: media, thumbnail_url
• Metadata: brand, category_name, attributes, tags
• Inventory: stock, total_stock (for multi-variant)
• Variants: variants or nested filtering (e.g., variants.sku,variants.selling_price)

Nested Variant Filtering: For multi-variant products, use dot notation to filter variant fields:

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

Example:

const product = await client.products.getProductBySlug(slug, {
  fields: 'product_id,name,description,price_range,media,seo_title,seo_description,variants.sku,variants.selling_price,variants.stock'
});

Response

200

application/json

Successfully retrieved product by slug with complete details including SEO metadata.

Response Structure: Same as GET /v1/products/{id}:

For Simple Products: Flat structure with all data at root level including SEO fields.

For Multi-Variant Products: Hierarchical structure with:

• Product-level data at root (including SEO fields)
• Aggregate data (total_stock, price_range)
• Clean variants array with only variant-specific fields

SEO Fields Included:

• product_slug: The SEO-friendly slug used in the request
• seo_title: Optimized title for search engines
• seo_description: Optimized description for search engines
• seo_keywords: Keywords for SEO
• featured: Whether product is featured
• featured_order: Display order for featured products

SDK Usage:

const product = await client.products.getProductBySlug(slug);
  
// Use SEO fields for page metadata
document.title = product.seo_title || product.name;
document.querySelector('meta[name="description"]').content = 
  product.seo_description || product.description;
  
// Handle variants
if (product.has_variants) {
  console.log(`${product.variant_count} variants available`);
  console.log(`Price range: €${product.price_range.min/100} - €${product.price_range.max/100}`);
}

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