Calculate a promotion's discount for a cart
Compute the discount a single promotion gives for a cart, server-side. The
result always matches the merchant’s own calculation, so your storefront never
reimplements the discount math (no subtotal × percentage on your side).
Send the cart you intend to charge — each line is the product, its quantity, and
the unit price you’re charging. How the discount is computed depends on the
promotion’s type:
discount(percentage) andfixed— a cart-wide discount applied to the eligible cart total.bundleandbogo— computed from the products present in the cart.
When the cart doesn’t qualify (the minimum purchase isn’t met, the promotion is
outside its active date/time window, or required products are absent), the
response is eligible: false with discount: 0 and a reason explaining why.
Marketplace storefronts: pass store_id (the merchant_store_id you
received with the promotion) to calculate against that merchant’s promotion.
curl --request POST \
--url https://api.tybritelabs.com/v1/promotions/{id}/calculate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cart": [
{
"product_id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
"quantity": 1,
"price": 349.99
}
]
}
'import requests
url = "https://api.tybritelabs.com/v1/promotions/{id}/calculate"
payload = { "cart": [
{
"product_id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
"quantity": 1,
"price": 349.99
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cart: [
{product_id: '7d425c0a-50e7-4e39-af79-6f7945f9dfa8', quantity: 1, price: 349.99}
]
})
};
fetch('https://api.tybritelabs.com/v1/promotions/{id}/calculate', 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/promotions/{id}/calculate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'cart' => [
[
'product_id' => '7d425c0a-50e7-4e39-af79-6f7945f9dfa8',
'quantity' => 1,
'price' => 349.99
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/promotions/{id}/calculate"
payload := strings.NewReader("{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/promotions/{id}/calculate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/promotions/{id}/calculate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"promotion_id": "df290d89-0400-4b2c-aa56-11fcc486150c",
"type": "discount",
"eligible": true,
"discount": 52.5,
"reason": null
}Authorizations
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) ortybrite_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) ortybrite_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.
Path Parameters
Query Parameters
The merchant whose promotion to calculate against. Required for marketplace
storefronts — pass the merchant_store_id you received with the promotion.
Ignored for single-store keys.
Body
The cart lines to calculate the discount against. Also accepted under the name items, which behaves identically; send whichever matches your storefront's own cart shape, and cart when both are present.
Show child attributes
Show child attributes
The shopper's country as an ISO 3166-1 alpha-2 code, used to decide whether a market-targeted promotion applies. Optional: when omitted the country is taken from the request's own network origin, so a storefront served through Galactic Core needs to send nothing. Pass it explicitly when your storefront resolves the destination itself, or to preview another market.
2"US"
The shopper's region or state, for a promotion narrowed within a market. Optional, and taken from the request's origin when omitted.
"California"
Alias of cart. Send one or the other, not both.
Show child attributes
Show child attributes
Response
Success
The result of calculating a single promotion against a cart. The discount is computed server-side so it always matches the merchant's own calculation — you never reimplement the math.
The promotion that was evaluated.
How the promotion works. discount (percentage) and fixed are cart-wide
discounts; bundle and bogo are computed from the products in the cart.
discount, fixed, bundle, bogo Whether the cart qualifies for the promotion.
The discount amount to subtract from the cart total. 0 when the cart is
not eligible.
When eligible is false, a short explanation of why the cart does not
qualify (for example: minimum purchase not met, the promotion is outside its
active date/time window, or required products are absent). null when
eligible.
curl --request POST \
--url https://api.tybritelabs.com/v1/promotions/{id}/calculate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cart": [
{
"product_id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
"quantity": 1,
"price": 349.99
}
]
}
'import requests
url = "https://api.tybritelabs.com/v1/promotions/{id}/calculate"
payload = { "cart": [
{
"product_id": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
"quantity": 1,
"price": 349.99
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cart: [
{product_id: '7d425c0a-50e7-4e39-af79-6f7945f9dfa8', quantity: 1, price: 349.99}
]
})
};
fetch('https://api.tybritelabs.com/v1/promotions/{id}/calculate', 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/promotions/{id}/calculate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'cart' => [
[
'product_id' => '7d425c0a-50e7-4e39-af79-6f7945f9dfa8',
'quantity' => 1,
'price' => 349.99
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/promotions/{id}/calculate"
payload := strings.NewReader("{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/promotions/{id}/calculate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/promotions/{id}/calculate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cart\": [\n {\n \"product_id\": \"7d425c0a-50e7-4e39-af79-6f7945f9dfa8\",\n \"quantity\": 1,\n \"price\": 349.99\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"promotion_id": "df290d89-0400-4b2c-aa56-11fcc486150c",
"type": "discount",
"eligible": true,
"discount": 52.5,
"reason": null
}