Dynamic Pricing

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.

Customer-specific prices need the shopper’s own credential. Pricing rules that target a customer segment, a customer tier or first-time buyers apply when a call carries customerId together with that shopper’s xAuthToken (a session token), xExternalAuth (a bring-your-own-auth assertion) or xIdpToken (a token from the store’s own identity provider) resolving to the same customer. The segment and tier are then read from the customer’s record, and the response is private to that shopper. A customerId without a matching credential returns the public price rather than an error.

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.

// 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'
});

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

Response

{
  "products": [
    {
      "name": "The 3p Fulfilled Snowboard",
      "display_price": 2997.43,
      "display_currency": "USD",
      "currency_symbol": "$",
      "has_variants": false,
      "thumbnail_url": "https://cdn.example.com/snowboard-main.jpg"
    }
  ],
  "pagination": { "limit": 20, "next_cursor": "MDI1MjVmZjUtMDkxNi00ZjAw", "has_more": true },
  "pricing_context": {
    "location": null,
    "region": "United States",
    "quantity": null,
    "currency": "USD",
    "exchange_rate": 1.13973
  }
}

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:

// 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'
});

The same catalog comes back priced in the detected currency — display_price converted, display_currency and currency_symbol changed, and pricing_context.exchange_rate showing the rate applied.

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

// 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}`);
}

A signed-in shopper’s price, with any segment, tier or first-purchase rule applied, comes from the same call with the shopper identified:

const pricing = await client.pricing.getProductPrice({
  id: '2b6a066a-25df-4238-9e90-50a4400fc21e',
  customerId: session.user.id,
  xAuthToken: session.access_token, // or xExternalAuth: signedAssertion, or xIdpToken: idpToken
});
// Same shape as above; resolved_price reflects the rules that match this customer.

`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: 'nebula-ceramic-mug-5c7f1-2b6a066a',
  latitude: 51.5074,  // London → GBP
  longitude: -0.1278
});
// Same shape as 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.

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

Direct Overrides: Manual price overrides set on specific product variants.
Customer Segments: Price rules targeting customer groups (Champions, Loyal, VIP, etc.), applied when the call identifies the shopper as described at the top of this page.
Regional Rules: Region-specific discounts or markups (e.g., a UK promotional discount, an EU regional rule). These match on the shopper’s country and region, which Galactic Core reads from the network edge when you don’t pass a location — a browser calling directly is located without you sending anything. Send placeName or coordinates to override that, which is what a server-rendered storefront and a market preview both need.
Volume Tiers: Price reductions triggered by the quantity parameter.
Order Value Rules: Discounts that depend on what the shopper is spending overall, such as “5% off orders over $100”, triggered by the orderTotal parameter.

An order-value rule can only be evaluated when orderTotal is present, so send the shopper’s current cart subtotal on pricing calls made once there is a cart. Without it those rules are skipped and the shopper sees the undiscounted price — the request still succeeds, which is why a missing orderTotal shows up as a discount that silently never applies rather than as an error.

display_price is the field to render as the shopper-facing price. It has already passed through the pricing engine, been converted to the detected currency, and been rounded according to that currency’s 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.

Get Started

Core Commerce

Discovery

Checkout & Logistics

Agents

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Integration Highlights

Methods

`getProductPrices`

`getProductPrice`

`getProductPriceBySlug`

🎨 Advanced Field Filtering

Pricing Engine Logic

Response Codes

​Integration Highlights

​Methods

​getProductPrices

​getProductPrice

​getProductPriceBySlug

​🎨 Advanced Field Filtering

​Pricing Engine Logic

​Response Codes

Integration Highlights

Methods

`getProductPrices`

`getProductPrice`

`getProductPriceBySlug`

🎨 Advanced Field Filtering

Pricing Engine Logic

Response Codes