Quote a multi-merchant checkout
What POST /v1/cart/checkout will charge for this basket, per merchant, before the
shopper pays — including each merchant’s shipping line. It takes the same body and runs
the same computation as the checkout, but holds no stock, creates no order and starts no
payment, so it can be called as the shopper edits their basket or their address.
Each merchant’s items are priced for delivery separately: by that merchant’s own delivery
rates for the destination, or by the marketplace’s flat rate per merchant, and free when
the merchant’s items reach the marketplace’s free-shipping threshold. When the request
carries a street shipping_address and a parcel for a merchant in
shipping_selections, that merchant’s carrier options are listed in rates; send the
chosen option’s rate_id (and rate_source) to the checkout. Carrier options are not
offered for items the marketplace ships itself.
The quote never includes commission or what a merchant is paid.
Requires the marketplace operator key (a publishable key is enough).
curl --request POST \
--url https://api.tybritelabs.com/v1/cart/checkout/quote \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"variant_id": "22222222-2222-2222-2222-222222222222",
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"quantity": 2
},
{
"variant_id": "55555555-5555-5555-5555-555555555555",
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"quantity": 1
}
],
"currency": "USD",
"shipping_address": {
"line1": "350 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10118",
"country": "US"
},
"shipping_selections": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"parcel": {
"length": "10",
"width": "8",
"height": "4",
"distance_unit": "in",
"weight": "2",
"mass_unit": "lb"
}
}
]
}
'import requests
url = "https://api.tybritelabs.com/v1/cart/checkout/quote"
payload = {
"items": [
{
"variant_id": "22222222-2222-2222-2222-222222222222",
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"quantity": 2
},
{
"variant_id": "55555555-5555-5555-5555-555555555555",
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"quantity": 1
}
],
"currency": "USD",
"shipping_address": {
"line1": "350 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10118",
"country": "US"
},
"shipping_selections": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"parcel": {
"length": "10",
"width": "8",
"height": "4",
"distance_unit": "in",
"weight": "2",
"mass_unit": "lb"
}
}
]
}
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({
items: [
{
variant_id: '22222222-2222-2222-2222-222222222222',
merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
quantity: 2
},
{
variant_id: '55555555-5555-5555-5555-555555555555',
merchant_store_id: '7a8b9c0d-1111-2222-3333-444455556666',
quantity: 1
}
],
currency: 'USD',
shipping_address: {
line1: '350 5th Ave',
city: 'New York',
state: 'NY',
postal_code: '10118',
country: 'US'
},
shipping_selections: [
{
merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
parcel: {
length: '10',
width: '8',
height: '4',
distance_unit: 'in',
weight: '2',
mass_unit: 'lb'
}
}
]
})
};
fetch('https://api.tybritelabs.com/v1/cart/checkout/quote', 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/cart/checkout/quote",
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([
'items' => [
[
'variant_id' => '22222222-2222-2222-2222-222222222222',
'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
'quantity' => 2
],
[
'variant_id' => '55555555-5555-5555-5555-555555555555',
'merchant_store_id' => '7a8b9c0d-1111-2222-3333-444455556666',
'quantity' => 1
]
],
'currency' => 'USD',
'shipping_address' => [
'line1' => '350 5th Ave',
'city' => 'New York',
'state' => 'NY',
'postal_code' => '10118',
'country' => 'US'
],
'shipping_selections' => [
[
'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
'parcel' => [
'length' => '10',
'width' => '8',
'height' => '4',
'distance_unit' => 'in',
'weight' => '2',
'mass_unit' => 'lb'
]
]
]
]),
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/cart/checkout/quote"
payload := strings.NewReader("{\n \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\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/cart/checkout/quote")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/cart/checkout/quote")
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 \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"currency": "USD",
"subtotal": 124,
"discount_total": 0,
"shipping_total": 5.99,
"total_amount": 129.99,
"sellers": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"merchandise_total": 80,
"shipping": {
"amount": 0,
"pricing": "free",
"fulfilled_by": "seller",
"is_free": true,
"free_threshold": 75,
"description": "Free shipping",
"selected_rate_id": null,
"rates": []
}
},
{
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"merchandise_total": 44,
"shipping": {
"amount": 5.99,
"pricing": "seller_rate",
"fulfilled_by": "seller",
"is_free": false,
"free_threshold": 75,
"description": "Local (within 10 km)",
"selected_rate_id": null,
"rates": []
}
}
]
}{
"error": {
"code": "shipping_destination_required",
"message": "Add a shipping address (or shipping_destination) so shipping can be priced."
}
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "forbidden",
"message": "This operation requires a secret key. Publishable keys have read-only access."
}
}{
"error": {
"code": "not_found",
"message": "Resource not found"
}
}{
"error": {
"code": "provider_not_live",
"message": "This marketplace has not finished connecting its payment account."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests for this API key. Please slow down and try again shortly.",
"remaining": 0,
"reset": 1706198400
}
}{
"error": {
"code": "server_error",
"message": "An unexpected error occurred"
}
}{
"error": {
"code": "shipping_unavailable",
"message": "Shipping could not be priced right now. Please try again."
}
}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: write operations, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_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.
Body
1Show child attributes
Show child attributes
"USD"
Used as the recipient name on carrier options.
Where the order is going (line1, line2, city, state, postal_code, country). Located to price shipping when shipping_destination is omitted, and needed for carrier options.
Where the basket is going, used to price each merchant's delivery rates. Send coordinates, or a place name. When omitted, the shipping_address is located instead.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The same per-merchant discounts the checkout accepts.
Show child attributes
Show child attributes
Response
The basket's price, per merchant, including shipping.
What a unified checkout will charge, per merchant, before the shopper pays.
"USD"
The basket's merchandise before any discount.
130
0
Shipping across every merchant.
15
What the checkout will charge before any wallet balance: merchandise after discounts plus shipping.
145
Show child attributes
Show child attributes
curl --request POST \
--url https://api.tybritelabs.com/v1/cart/checkout/quote \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"variant_id": "22222222-2222-2222-2222-222222222222",
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"quantity": 2
},
{
"variant_id": "55555555-5555-5555-5555-555555555555",
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"quantity": 1
}
],
"currency": "USD",
"shipping_address": {
"line1": "350 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10118",
"country": "US"
},
"shipping_selections": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"parcel": {
"length": "10",
"width": "8",
"height": "4",
"distance_unit": "in",
"weight": "2",
"mass_unit": "lb"
}
}
]
}
'import requests
url = "https://api.tybritelabs.com/v1/cart/checkout/quote"
payload = {
"items": [
{
"variant_id": "22222222-2222-2222-2222-222222222222",
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"quantity": 2
},
{
"variant_id": "55555555-5555-5555-5555-555555555555",
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"quantity": 1
}
],
"currency": "USD",
"shipping_address": {
"line1": "350 5th Ave",
"city": "New York",
"state": "NY",
"postal_code": "10118",
"country": "US"
},
"shipping_selections": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"parcel": {
"length": "10",
"width": "8",
"height": "4",
"distance_unit": "in",
"weight": "2",
"mass_unit": "lb"
}
}
]
}
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({
items: [
{
variant_id: '22222222-2222-2222-2222-222222222222',
merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
quantity: 2
},
{
variant_id: '55555555-5555-5555-5555-555555555555',
merchant_store_id: '7a8b9c0d-1111-2222-3333-444455556666',
quantity: 1
}
],
currency: 'USD',
shipping_address: {
line1: '350 5th Ave',
city: 'New York',
state: 'NY',
postal_code: '10118',
country: 'US'
},
shipping_selections: [
{
merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
parcel: {
length: '10',
width: '8',
height: '4',
distance_unit: 'in',
weight: '2',
mass_unit: 'lb'
}
}
]
})
};
fetch('https://api.tybritelabs.com/v1/cart/checkout/quote', 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/cart/checkout/quote",
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([
'items' => [
[
'variant_id' => '22222222-2222-2222-2222-222222222222',
'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
'quantity' => 2
],
[
'variant_id' => '55555555-5555-5555-5555-555555555555',
'merchant_store_id' => '7a8b9c0d-1111-2222-3333-444455556666',
'quantity' => 1
]
],
'currency' => 'USD',
'shipping_address' => [
'line1' => '350 5th Ave',
'city' => 'New York',
'state' => 'NY',
'postal_code' => '10118',
'country' => 'US'
],
'shipping_selections' => [
[
'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
'parcel' => [
'length' => '10',
'width' => '8',
'height' => '4',
'distance_unit' => 'in',
'weight' => '2',
'mass_unit' => 'lb'
]
]
]
]),
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/cart/checkout/quote"
payload := strings.NewReader("{\n \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\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/cart/checkout/quote")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/cart/checkout/quote")
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 \"items\": [\n {\n \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"quantity\": 2\n },\n {\n \"variant_id\": \"55555555-5555-5555-5555-555555555555\",\n \"merchant_store_id\": \"7a8b9c0d-1111-2222-3333-444455556666\",\n \"quantity\": 1\n }\n ],\n \"currency\": \"USD\",\n \"shipping_address\": {\n \"line1\": \"350 5th Ave\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n },\n \"shipping_selections\": [\n {\n \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n \"parcel\": {\n \"length\": \"10\",\n \"width\": \"8\",\n \"height\": \"4\",\n \"distance_unit\": \"in\",\n \"weight\": \"2\",\n \"mass_unit\": \"lb\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"currency": "USD",
"subtotal": 124,
"discount_total": 0,
"shipping_total": 5.99,
"total_amount": 129.99,
"sellers": [
{
"merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
"merchandise_total": 80,
"shipping": {
"amount": 0,
"pricing": "free",
"fulfilled_by": "seller",
"is_free": true,
"free_threshold": 75,
"description": "Free shipping",
"selected_rate_id": null,
"rates": []
}
},
{
"merchant_store_id": "7a8b9c0d-1111-2222-3333-444455556666",
"merchandise_total": 44,
"shipping": {
"amount": 5.99,
"pricing": "seller_rate",
"fulfilled_by": "seller",
"is_free": false,
"free_threshold": 75,
"description": "Local (within 10 km)",
"selected_rate_id": null,
"rates": []
}
}
]
}{
"error": {
"code": "shipping_destination_required",
"message": "Add a shipping address (or shipping_destination) so shipping can be priced."
}
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "forbidden",
"message": "This operation requires a secret key. Publishable keys have read-only access."
}
}{
"error": {
"code": "not_found",
"message": "Resource not found"
}
}{
"error": {
"code": "provider_not_live",
"message": "This marketplace has not finished connecting its payment account."
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests for this API key. Please slow down and try again shortly.",
"remaining": 0,
"reset": 1706198400
}
}{
"error": {
"code": "server_error",
"message": "An unexpected error occurred"
}
}{
"error": {
"code": "shipping_unavailable",
"message": "Shipping could not be priced right now. Please try again."
}
}
