Promotions

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) and fixed — a cart-wide discount applied to the eligible cart total.
bundle and bogo — 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.

POST

promotions

{id}

calculate

Calculate a promotion's discount for a cart

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

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: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

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)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Path Parameters

string<uuid>

required

Query Parameters

store_id

string<uuid>

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

application/json

cart

object[]

required

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

items

object[]

Alias of cart. Send one or the other, not both.

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.

promotion_id

string<uuid>

The promotion that was evaluated.

type

enum<string>

How the promotion works. discount (percentage) and fixed are cart-wide discounts; bundle and bogo are computed from the products in the cart.

Available options:

discount,

fixed,

bundle,

bogo

eligible

boolean

Whether the cart qualifies for the promotion.

discount

number

The discount amount to subtract from the cart total. 0 when the cart is not eligible.

reason

string | null

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.

Calculate a promotion's discount for a cart

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
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Calculate a promotion's discount for a cart

Authorizations

Path Parameters

Query Parameters

Body

Response