Skip to main content
GET
Get promotion details

Authorizations

Authorization
string
header
required

API Key Authentication

Use your API key in the Authorization header:

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: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

  • Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
  • Catalogue reads, plus the actions a shopper takes for themselves
  • ✅ Safe for client-side JavaScript, mobile apps, and public code
  • Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents

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)
  • Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
  • All other 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>
required

Query Parameters

store_id
string<uuid>

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.

expand
enum<string>

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.

Available options:
products
fields
string

Comma-separated list of fields to include in the response.

Allowed Fields:

  • id, name, type, display_type, value, min_purchase
  • start_date, end_date, status, conditions, image, image_mobile, video
  • bundle_products, bogo_required_products, bogo_free_products, free_products
  • has_time_restrictions, start_time, end_time, time_zone, apply_to_days
  • created_at, updated_at

Response

Success

id
string<uuid>
name
string
type
enum<string>

Promotion mechanic.

Available options:
fixed,
discount,
bundle,
bogo
display_type
string

Human-readable label derived from type (e.g. "Percentage Discount").

value
string

The discount amount or percentage for this promotion, depending on type.

min_purchase
number | null

Minimum order total required for the promotion to apply.

start_date
string<date>
end_date
string<date>
status
string

Lifecycle status. Only active promotions (within their date window) apply.

Example:

"active"

conditions
string | null

Optional human-readable conditions for the promotion.

image
string<uri> | null

URL of the promotion banner image. This is the default banner — used on desktop and as the fallback whenever image_mobile is not set.

video
string<uri> | null

Optional URL of a short video for this banner (MP4, H.264 with AAC audio). Null when none is set. image stays the poster and the fallback, so a storefront that shows only images keeps working unchanged.

image_mobile
string<uri> | null

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.

bundle_products
object[]

Products that make up a bundle promotion (present for bundle type).

bogo_required_products
object[]

Products that must be purchased to unlock a BOGO promotion (present for bogo type).

bogo_free_products
object[]

Products given free under a BOGO promotion (present for bogo type).

bundle_products_resolved
object[]

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.

bogo_required_products_resolved
object[]

Present only when the promotion is fetched with expand=products. The same entries as bogo_required_products, each enriched with an embedded product object.

bogo_free_products_resolved
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.

target_countries
string[]

ISO 3166-1 alpha-2 codes this promotion applies in. An EMPTY array means it applies everywhere, which is the default. When codes are present the promotion is only applied to shoppers in those markets, and is refused when the shopper's location cannot be determined — applying a market-limited offer to an unknown visitor would give it to everyone.

Required string length: 2
Example:
target_regions
string[]

Region or state names this promotion applies in, matched case-insensitively. Empty means everywhere. Use alongside target_countries to narrow within a market.

Example:
has_time_restrictions
boolean

Whether the promotion only applies during specific times/days.

start_time
string | null

Daily start time (when has_time_restrictions is true).

end_time
string | null

Daily end time (when has_time_restrictions is true).

time_zone
string | null

Time zone the time restrictions are evaluated in.

apply_to_days
string[] | null

Days of the week the promotion applies to (when has_time_restrictions is true).

created_at
string<date-time>
updated_at
string<date-time>