Products

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

products

{id}

Get product by ID or variant ID

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

import requests

url = "https://api.tybritelabs.com/v1/products/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/products/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/products/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/products/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tybritelabs.com/v1/products/{id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/products/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
  "name": "Apple MacBook Pro",
  "category_id": "49f084e5-9ded-429c-aeb7-5918a2234953",
  "category_name": "Laptops",
  "brand": "Apple",
  "thumbnail_url": "https://images.unsplash.com/photo-1517336714731-489689fd1ca8",
  "media": [],
  "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
  "sku": "APP-MBP-13",
  "price": 1999,
  "selling_price": 1999,
  "stock": 42,
  "has_variants": false,
  "display_currency": "USD",
  "currency_symbol": "$",
  "is_active": true,
  "created_at": "2026-06-20T10:12:03.673701+00:00",
  "updated_at": "2026-06-20T10:12:03.673701+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

string<uuid>

default:715b8c10-eb11-4289-8c0e-2966e78cf9a5

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., 715b8c10-eb11-4289-8c0e-2966e78cf9a5)
Variant ID: A specific variant identifier (e.g., 15ca5a86-4b1b-47c3-8762-a1aa43941565)

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:

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, last_restocked (last_restocked is not in the default response — request it explicitly)
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:

Performance Impact:

Nested filtering excludes non-default fields like last_restocked
Perfect for mobile apps and bandwidth-constrained environments
Recommended for product cards and listing pages

Response

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 (last_restocked available via fields=variants.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:

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

string<uuid>

Product identifier. Identical to product_id.

Example:

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

product_id

string<uuid>

Product identifier. Identical to id.

Example:

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

name

string

Product name

Example:

"Sony WH-1000XM4"

description

string

Product 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://cdn.tybritelabs.com/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 title for the product detail page

Example:

"Sony WH-1000XM4 Wireless Noise-Cancelling Headphones"

seo_description

string | null

SEO meta description for the product detail page

Example:

"Industry-leading noise cancellation with 30-hour battery life. Shop the Sony WH-1000XM4 today."

seo_keywords

string[] | null

SEO keywords for the product

Example:

[
  "wireless headphones",
  "noise cancelling",
  "sony"
]

featured

boolean | null

Whether product is featured

featured_order

integer | null

Display order for featured products

tags

string[] | null

Product tags

attributes

object | null

Product-level attributes (not variant-specific)

shipping_info

object | null

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

last_restocked

string<date> | null

Last restock date. Not included in the default list response — request it explicitly with fields=last_restocked.

variant_attributes

object | null

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 | null

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

List brands

Get product by SEO-friendly slug

Get product by ID or variant ID

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

import requests

url = "https://api.tybritelabs.com/v1/products/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/products/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/products/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/products/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tybritelabs.com/v1/products/{id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/products/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
  "name": "Apple MacBook Pro",
  "category_id": "49f084e5-9ded-429c-aeb7-5918a2234953",
  "category_name": "Laptops",
  "brand": "Apple",
  "thumbnail_url": "https://images.unsplash.com/photo-1517336714731-489689fd1ca8",
  "media": [],
  "variant_id": "15ca5a86-4b1b-47c3-8762-a1aa43941565",
  "sku": "APP-MBP-13",
  "price": 1999,
  "selling_price": 1999,
  "stock": 42,
  "has_variants": false,
  "display_currency": "USD",
  "currency_symbol": "$",
  "is_active": true,
  "created_at": "2026-06-20T10:12:03.673701+00:00",
  "updated_at": "2026-06-20T10:12:03.673701+00:00"
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Get product by ID or variant ID

Authorizations

Path Parameters

Query Parameters

Response