Get promotion details
Get a single promotion’s details, including the products it applies to.
The type field tells you how the promotion works and which product fields
to read:
discount(percentage) /fixed— a cart-level discount. There are no promotion products; rendervalueand anymin_purchase.bundle— readbundle_products: a list of{ productId, quantity, discountedPrice }.bogo— readbogo_required_products(buy these) andbogo_free_products(get these free): lists of{ productId, quantity }.
These fields contain product ids — fetch each product’s full detail with
the Products API to render it. Alternatively, pass expand=products to get the
promotion’s bundle/BOGO products resolved with their details in one call, so you
don’t need a second lookup (see the expand parameter below).
Marketplace storefronts: when a sponsored ad placement or a curated
collection gives you a promotion_id, fetch its detail here by passing
store_id (the merchant_store_id you received alongside the promotion).
A marketplace key may read a single promotion this way; it cannot list
promotions.
Authorizations
API Key Authentication
Use your API key in the Authorization header:
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_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) ortybrite_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
Query Parameters
The merchant whose promotion to read. Required for marketplace
storefronts — pass the merchant_store_id you received with the
promotion. Ignored for single-store keys.
Pass expand=products to get the promotion's bundle/BOGO products resolved
with their details, so you don't need a second lookup. The response then
additionally includes bundle_products_resolved,
bogo_required_products_resolved, and bogo_free_products_resolved — the
same entries as the corresponding id arrays, but each with an embedded
product object (product_id, name, price, image, category), or
null for any product that is unavailable.
products Comma-separated list of fields to include in the response.
Allowed Fields:
id,name,type,display_type,value,min_purchasestart_date,end_date,status,conditions,image,image_mobilebundle_products,bogo_required_products,bogo_free_products,free_productshas_time_restrictions,start_time,end_time,time_zone,apply_to_dayscreated_at,updated_at
Response
Success
Promotion mechanic.
fixed, discount, bundle, bogo Human-readable label derived from type (e.g. "Percentage Discount").
The discount amount or percentage for this promotion, depending on type.
Minimum order total required for the promotion to apply.
Lifecycle status. Only active promotions (within their date window) apply.
"active"
Optional human-readable conditions for the promotion.
URL of the promotion banner image. This is the default banner — used on desktop and as the fallback whenever image_mobile is not set.
Optional banner image sized for mobile viewports. When set, render this on small screens and fall back to image on larger ones (e.g. a <picture> element with a mobile <source>). When absent, use image everywhere.
Products that make up a bundle promotion (present for bundle type).
Products that must be purchased to unlock a BOGO promotion (present for bogo type).
Products given free under a BOGO promotion (present for bogo type).
Present only when the promotion is fetched with expand=products. The same
entries as bundle_products, each enriched with an embedded product object
so you can render the bundle without a second lookup.
Present only when the promotion is fetched with expand=products. The same
entries as bogo_required_products, each enriched with an embedded product
object.
Present only when the promotion is fetched with expand=products. The same
entries as bogo_free_products, each enriched with an embedded product
object.
Whether the promotion only applies during specific times/days.
Daily start time (when has_time_restrictions is true).
Daily end time (when has_time_restrictions is true).
Time zone the time restrictions are evaluated in.
Days of the week the promotion applies to (when has_time_restrictions is true).

