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: 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>
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
  • 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.

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.

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>