> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tybritelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Pricing

> Reference for the PricingService class in the Tybrite SDK.

The `PricingService` class (accessed via `client.pricing`) provides high-performance price calculations. It acts as a single source of truth, enriching product data with real-time regional discounts, segment/volume pricing rules, and multi-currency conversion.

<Note>
  **Customer Segment & Tier are determined automatically.** `customer_segment` and `customer_tier` are **not** accepted as request parameters — they are resolved automatically from the `customer_id` you provide. Sending them as parameters has no effect. To apply segment-specific pricing, pass `customerId` only.
</Note>

## Integration Highlights

* **Consistent with the catalog**: Returns the same product and variant data structures as the Products API, so you can use one shape across discovery and checkout.
* **Media included**: Returns `thumbnail_url` and `media` (including variant-level media) alongside pricing.
* **Multi-Variant Support**: Automatically calculates prices, discounts, and breakdowns for every variant in a product.
* **Geographic Detection**: Accurate currency selection based on the customer's location, worldwide.

***

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

```typescript theme={null}
// New York shopper → prices resolve to USD (the store's base currency, rate 1.0)
const { products, pagination, pricing_context } = await client.pricing.getProductPrices({
  latitude: 40.7128,
  longitude: -74.006,
  limit: 20,
  fields: 'name,display_price,display_currency,currency_symbol,has_variants,thumbnail_url'
});

// → { name: "Samsung Galaxy Watch 6", display_price: 299, display_currency: "USD", currency_symbol: "$", ... }

// Access global pricing context
console.log(`Currency: ${pricing_context.currency}`); // "USD"
console.log(`Has more: ${pagination.has_more}`);
```

Pass a non-US location to convert into that region's currency — Galactic Core detects the currency
from the coordinates (or a `placeName` like `'London, UK'`) and applies the exchange rate:

```typescript theme={null}
// London shopper → same catalog, prices converted to GBP
const uk = await client.pricing.getProductPrices({
  placeName: 'London, UK',
  fields: 'name,display_price,display_currency,currency_symbol'
});
// → { name: "Samsung Galaxy Watch 6", display_price: 236.21, display_currency: "GBP", currency_symbol: "£", ... }
```

***

### `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.

```typescript theme={null}
// Multi-variant product (the "Nebula Ceramic Mug"), Berlin shopper → detects EUR (€)
const pricing = await client.pricing.getProductPrice({
  id: '2b6a066a-25df-4238-9e90-50a4400fc21e',
  placeName: 'Berlin, Germany',
  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}`); // €13.79 - €14.31

  // Access a specific variant's isolated media and converted price
  const v1 = pricing.variants[0];
  console.log(`Sku: ${v1.sku} | Price: €${v1.display_price}`); // API-MUG-WHT-2b6a | €13.79
  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.

```typescript theme={null}
const pricing = await client.pricing.getProductPriceBySlug({
  slug: 'nebula-ceramic-mug-5c7f1-2b6a066a',
  latitude: 51.5074,  // London → GBP
  longitude: -0.1278
});
// → identical shape to getProductPrice: root metadata + price_range + variants[], each variant
//   carrying base_price, resolved_price, display_price, and a price_breakdown with the
//   currency_conversion applied. For a London shopper display_currency is "GBP" (symbol "£").
```

***

## 🎨 Advanced Field Filtering

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

```bash theme={null}
# 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**: Region-specific discounts or markups (e.g., a UK promotional discount, an EU regional rule).
4. **Volume Tiers**: Price reductions triggered by the `quantity` parameter.

<Note>
  **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.
</Note>

***

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