Dynamic Pricing

Reference for the PricingService class in the Tybrite SDK.

The PricingService class (accessed via client.pricing) provides high-performance price calculations using a Service Binding Architecture. It acts as a single source of truth, enriching product data with real-time regional discounts, tax adjustments, and multi-currency conversion.

Customer Segment & Tier are server-derived. customer_segment and customer_tier are not accepted as request parameters — they are resolved server-side from customer_id using internal RFM/loyalty data. Sending them as parameters has no effect. To apply segment-specific pricing, pass customerId only.

Integration Highlights

• Service Binding: Leverages the Products API directly for consistent data structures.
• Media Integration: Automatically proxies and whitelists thumbnail_url and media (including variant-level media) from the Products API.
• Multi-Variant Support: Automatically calculates prices, discounts, and breakdowns for every variant in a product.
• Geographic Detection: Accurate currency retrieval using PostGIS boundary matching with a 100% success rate across global locations.

---

Methods

getProductPrices

Retrieve resolved prices for a list of products. Optimized for catalog browsing, this returns a flat structure using the default variant for each product. Includes thumbnail_url for fast rendering.

const { products, pagination, pricing_context } = await client.pricing.getProductPrices({
  categoryId: 'electronics-uuid',
  placeName: 'London, UK',
  limit: 20,
  fields: 'name,display_price,display_currency,currency_symbol,has_variants,thumbnail_url'
});

// Access global pricing context
console.log(`Region: ${pricing_context.region}`);
console.log(`Has more: ${pagination.has_more}`);

---

getProductPrice

Retrieve an ultra-detailed price breakdown for a single item. Handles both simple and multi-variant products with hierarchical responses. Each priced product already includes media gallery arrays.

• Aggregate Pricing: For products with variants, it provides an accurate price_range (min/max) in the customer’s currency.
• Per-Variant Breakdown: Each item in the variants array contains its own base_price, resolved_price, and display_price.
• Media Resolution: Includes both root-level gallery media and variant-specific media proxies.

const pricing = await client.pricing.getProductPrice({
  id: 'sony-wh-1000xm4-uuid',
  placeName: 'Paris, France', // Detects EUR (€)
  fields: 'name,thumbnail_url,media,price_range,variants.sku,variants.display_price,variants.media'
});

if (pricing.has_variants) {
  console.log(`Range: €${pricing.price_range.min} - €${pricing.price_range.max}`);
  
  // Access specific variant's isolated media and price
  const v1 = pricing.variants[0];
  console.log(`Sku: ${v1.sku} | Price: €${v1.display_price}`);
  console.log(`Images for this variant: ${v1.media.length}`);
}

---

getProductPriceBySlug

Retrieve pricing using an SEO-friendly slug. Identical to getProductPrice but uses slugs for cleaner URL routing in frontend applications.

const pricing = await client.pricing.getProductPriceBySlug({
  slug: 'sony-wh-1000xm4-a089d',
  latitude: 51.5074,
  longitude: -0.1278
});

---

🎨 Advanced Field Filtering

The Pricing Service supports dot notation for filtering variant pricing data, enabling significant bandwidth savings for complex product pages.

# Optimized variant pricing request including media
fields=name,thumbnail_url,price_range,variants.sku,variants.display_price,variants.stock,variants.media

---

Pricing Engine Logic

Tybrite calculates prices in a specific waterfall priority:

1. Direct Overrides: Manual price overrides set on specific product variants.
2. Customer Segments: Price rules targeting groups like “Wholesalers” (Champions, Loyal, etc.).
3. Regional Rules: Tax adjustments or regional discounts (e.g., UK 8% discount, France 10% discount).
4. Volume Tiers: Price reductions triggered by the quantity parameter.

Pro Tip: Always use display_price for the final price shown to the user. This field has already been processed through the pricing engine, converted to the detected currency, and rounded according to currency rules.

---

Response Codes

All pricing endpoints are GET and accept both publishable and secret keys.

Code	Meaning
200	Success.
400	Invalid request — bad UUID, invalid coordinates, unknown placeName, or invalid fields selector.
401	Invalid or missing API key.
404	Product or variant not found (single-resource endpoints only). List endpoints return 200 with an empty array.
429	Rate limit exceeded.
500	Internal server error — including upstream currency-resolution failures.