Pricing

Get prices for multiple products with dynamic pricing and multi-currency support

Calculate dynamic prices for products based on customer segment, location, volume, and geographic currency detection.

Multi-Currency Support:

Automatically detects currency based on customer location (coordinates or place name)
Converts prices from store’s base currency to detected currency
Falls back to store’s default currency if no location provided
Works with both simple and multi-variant products

Multi-Variant Support:

Returns flat structure with default variant data (keeps payload small for browsing)
Use has_variants flag to determine if detail fetch needed
For full variant pricing, use GET /v1/prices/products/:id endpoint

Dynamic Pricing:

Customer segment-based pricing (RFM segmentation)
Customer tier-based pricing (Gold, Silver, Bronze)
Volume/quantity-based discounts
Region-specific pricing rules
Time-based promotions

Field Filtering:

Use fields parameter to reduce bandwidth by 50-90%
Supports nested fields with dot notation
Example: fields=name,display_price,display_currency,price_breakdown.base_price

GET

prices

products

Get prices for multiple products with dynamic pricing and multi-currency support

curl --request GET \
  --url https://api.tybritelabs.com/v1/prices/products \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/prices/products', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/prices/products",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/prices/products"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/prices/products")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "products": [
    {
      "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
      "name": "Apple MacBook Pro",
      "sku": "APP-MBP-13",
      "base_price": 1999,
      "base_currency": "USD",
      "resolved_price": 1999,
      "display_price": 1579.21,
      "display_currency": "GBP",
      "currency_symbol": "£",
      "exchange_rate": 0.79,
      "has_variants": false,
      "price_breakdown": {
        "base_price": 1999,
        "discounts": [],
        "final_price": 1999,
        "currency_conversion": {
          "from_currency": "USD",
          "to_currency": "GBP",
          "rate": 0.79,
          "converted_amount": 1579.21
        }
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "pricing_context": {
    "location": null,
    "region": "United Kingdom",
    "quantity": null,
    "currency": "GBP",
    "exchange_rate": 0.79
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

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.

Headers

x-auth-token

string

Galactic Core customer session access_token. Required, together with customer_id, for personalized pricing. Provide at most one of x-auth-token, x-external-auth or x-idp-token.

x-external-auth

string

Bring-your-own-auth assertion for personalized pricing, resolving to the customer_id supplied. Format: <base64url(JSON)>.<base64url(HMAC-SHA256(JSON))> where the JSON is { "external_id": "...", "iat": <unix>, "exp": <unix> } signed with the store's hmac_secret. Provide at most one of x-auth-token, x-external-auth or x-idp-token.

x-idp-token

string

A raw token from the store's own identity provider, verified by the store's configured Auth verifier, for personalized pricing; it must resolve to the customer_id supplied. Provide at most one of x-auth-token, x-external-auth or x-idp-token.

Query Parameters

string

Search by product name or SKU

category_id

string<uuid>

Filter by category UUID

subcategory_id

string<uuid>

Filter by subcategory UUID

limit

integer

default:50

Maximum number of products to return (1-200)

Required range: 1 <= x <= 200

cursor

string

Opaque pagination cursor. Pass the pagination.next_cursor value from the previous response to fetch the next page.

fields

string

Comma-separated list of fields to return (reduces bandwidth by 50-90%).

Allowed fields: product_id, variant_id, name, sku, description, price, selling_price, stock, image, category_name, brand, has_variants, variant_count, total_stock, base_price, resolved_price, display_price, base_currency, display_currency, currency_symbol, exchange_rate, price_breakdown, price_breakdown., pricing_context, pricing_context.

Example: fields=name,display_price,display_currency,currency_symbol,has_variants

place_name

string

City or region name for geographic currency detection (e.g., "New York, USA", "London, UK", "Nairobi, Kenya").

How it works:

Geocodes place name to coordinates
Matches coordinates to currency regions
Returns prices in detected currency

Examples:

place_name=New York → USD
place_name=London → GBP
place_name=Nairobi, Kenya → KES

latitude

number<double>

Customer latitude for precise geographic currency detection.

Priority: Coordinates take priority over place_name if both provided.

Accuracy: Uses geographic boundary matching for accurate region detection.

Works with variants: Currency detection applies to all product variants.

Example: latitude=40.7128&longitude=-74.0060 (New York) → USD

longitude

number<double>

Customer longitude for precise geographic currency detection.

Must be used with latitude parameter.

Example: latitude=51.5074&longitude=-0.1278 (London) → GBP

location

string

DEPRECATED: Use place_name instead for better geocoding support.

Location/country for location-based pricing rules.

region

string

Manual region override for pricing rules (bypasses automatic detection)

customer_id

string<uuid>

Customer UUID for personalized pricing.

Honored only together with that shopper's own credential: an x-auth-token session, an x-external-auth assertion or an x-idp-token that resolves to the same customer. The customer's segment, tier and first-purchase status then feed pricing rule evaluation, and the response is private to that shopper. Without a matching credential the request returns the public price; it is not rejected.

quantity

integer

Quantity for volume-based pricing discounts

Required range: x >= 1

order_total

number<float>

The shopper's current cart subtotal. Send it whenever you know the cart total: pricing rules that depend on order value ("spend over $100") can only be evaluated when it is present, and are skipped otherwise.

Required range: x >= 0

Response

Successfully retrieved products with dynamic pricing and currency conversion.

Response includes:

Products with converted prices in detected/default currency
Price breakdown showing base price, discounts, and final price
Pricing context with currency info and detection method
Pagination metadata

Note: List endpoint returns flat structure with default variant only. For full variant pricing, use GET /v1/prices/products/:id

products

object[]

Show child attributes

pagination

object

Cursor pagination metadata.

Show child attributes

pricing_context

object

Global pricing context for the request.

Show child attributes

Get prices for multiple products with dynamic pricing and multi-currency support

curl --request GET \
  --url https://api.tybritelabs.com/v1/prices/products \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.tybritelabs.com/v1/prices/products', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/prices/products",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/prices/products"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/prices/products")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "products": [
    {
      "product_id": "715b8c10-eb11-4289-8c0e-2966e78cf9a5",
      "name": "Apple MacBook Pro",
      "sku": "APP-MBP-13",
      "base_price": 1999,
      "base_currency": "USD",
      "resolved_price": 1999,
      "display_price": 1579.21,
      "display_currency": "GBP",
      "currency_symbol": "£",
      "exchange_rate": 0.79,
      "has_variants": false,
      "price_breakdown": {
        "base_price": 1999,
        "discounts": [],
        "final_price": 1999,
        "currency_conversion": {
          "from_currency": "USD",
          "to_currency": "GBP",
          "rate": 0.79,
          "converted_amount": 1579.21
        }
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "pricing_context": {
    "location": null,
    "region": "United Kingdom",
    "quantity": null,
    "currency": "GBP",
    "exchange_rate": 0.79
  }
}

Reference

System

Store

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Agent

Search

Authentication

Customers

Gift Cards

Promotions

Campaigns

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Feeds

Sandbox

Get prices for multiple products with dynamic pricing and multi-currency support

Authorizations

Headers

Query Parameters

Response