Get shipping zones and pricing tiers
The store’s delivery rates and pickup locations: its active distance-based pricing tiers, its active delivery zones, its “everywhere else” rate, and the locations where shoppers can collect an order.
How an address is priced (see POST /v1/shipping/calculate):
- The first zone that contains it — lowest
priorityfirst, then the zone created first. Anareazone contains the addresses inside the area drawn on its map; aregionzone contains the addresses in one of itscountries, narrowed topostcodesthat start with one of the listed prefixes when it has any. - Otherwise, the tier whose range contains its distance from the store. A range includes its
min_distance_metersand stops just before itsmax_distance_meters. - Otherwise,
everywhere_else. When it is null, orrefuseis true, and the store has zones or tiers, an address outside them is not delivered to.
Every amount is in currency. A store with no tiers, zones or everywhere_else rate charges
nothing for delivery through these rates.
Pickup: each entry in pickup_locations is a location where an order can be collected
instead of delivered, with its own pickup_fee and, when set, a minimum_order. The store’s
primary location is listed first.
Caching: the response is cached for up to 60 seconds and carries an ETag (send
If-None-Match for a 304). Changes to the store’s rates appear here within that window;
POST /v1/shipping/calculate and order creation always read the current rates.
curl --request GET \
--url https://api.tybritelabs.com/v1/shipping/zones \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tybritelabs.com/v1/shipping/zones"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tybritelabs.com/v1/shipping/zones', 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/shipping/zones",
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/shipping/zones"
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))
}HttpResponse<String> response = Unirest.get("https://api.tybritelabs.com/v1/shipping/zones")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/shipping/zones")
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{
"currency": "USD",
"pricing_tiers": [
{
"tier_name": "Local (within 10 km)",
"min_distance_meters": 0,
"max_distance_meters": 10000,
"delivery_fee": 5.99,
"free_delivery_threshold": 75,
"is_active": true,
"priority": 1
},
{
"tier_name": "Metro (10–50 km)",
"min_distance_meters": 10000,
"max_distance_meters": 50000,
"delivery_fee": 9.99,
"free_delivery_threshold": 150,
"is_active": true,
"priority": 2
},
{
"tier_name": "Regional (50–500 km)",
"min_distance_meters": 50000,
"max_distance_meters": 500000,
"delivery_fee": 14.99,
"free_delivery_threshold": 250,
"is_active": true,
"priority": 3
}
],
"delivery_zones": [
{
"zone_name": "Lower 48 states",
"delivery_fee": 12.99,
"free_delivery_threshold": 200,
"is_active": true,
"priority": 1,
"color": "#3B82F6",
"match_kind": "region",
"countries": [
"US"
],
"postcodes": []
}
],
"everywhere_else": {
"refuse": false,
"delivery_fee": 29.99,
"free_delivery_threshold": null
},
"pickup_locations": [
{
"id": "3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
"name": "Brooklyn store",
"address": {
"line1": "145 Atlantic Avenue",
"city": "Brooklyn",
"state": "NY",
"postal_code": "11201",
"country": "US"
},
"latitude": 40.6907,
"longitude": -73.9956,
"hours": "Mon–Sat 10:00–19:00",
"pickup_fee": 0,
"minimum_order": null,
"ready_text": "Ready in 2 hours",
"instructions": "Collect from the counter at the back of the store."
}
]
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "forbidden",
"message": "This operation requires a secret key. Publishable keys cover catalogue reads and the actions a shopper takes for themselves."
}
}{
"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"
}
}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.
Response
The store's delivery rates
The currency every fee and threshold here is in — the store's own.
"USD"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The rate for any address outside the zones and tiers. Null when the store has not set one. When refuse is true the store has chosen not to deliver outside its zones and distance rates, and both amounts are null.
Show child attributes
Show child attributes
The store's locations that offer pickup, primary location first. Empty when the store does not offer pickup.
Show child attributes
Show child attributes
curl --request GET \
--url https://api.tybritelabs.com/v1/shipping/zones \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tybritelabs.com/v1/shipping/zones"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tybritelabs.com/v1/shipping/zones', 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/shipping/zones",
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/shipping/zones"
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))
}HttpResponse<String> response = Unirest.get("https://api.tybritelabs.com/v1/shipping/zones")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/shipping/zones")
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{
"currency": "USD",
"pricing_tiers": [
{
"tier_name": "Local (within 10 km)",
"min_distance_meters": 0,
"max_distance_meters": 10000,
"delivery_fee": 5.99,
"free_delivery_threshold": 75,
"is_active": true,
"priority": 1
},
{
"tier_name": "Metro (10–50 km)",
"min_distance_meters": 10000,
"max_distance_meters": 50000,
"delivery_fee": 9.99,
"free_delivery_threshold": 150,
"is_active": true,
"priority": 2
},
{
"tier_name": "Regional (50–500 km)",
"min_distance_meters": 50000,
"max_distance_meters": 500000,
"delivery_fee": 14.99,
"free_delivery_threshold": 250,
"is_active": true,
"priority": 3
}
],
"delivery_zones": [
{
"zone_name": "Lower 48 states",
"delivery_fee": 12.99,
"free_delivery_threshold": 200,
"is_active": true,
"priority": 1,
"color": "#3B82F6",
"match_kind": "region",
"countries": [
"US"
],
"postcodes": []
}
],
"everywhere_else": {
"refuse": false,
"delivery_fee": 29.99,
"free_delivery_threshold": null
},
"pickup_locations": [
{
"id": "3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
"name": "Brooklyn store",
"address": {
"line1": "145 Atlantic Avenue",
"city": "Brooklyn",
"state": "NY",
"postal_code": "11201",
"country": "US"
},
"latitude": 40.6907,
"longitude": -73.9956,
"hours": "Mon–Sat 10:00–19:00",
"pickup_fee": 0,
"minimum_order": null,
"ready_text": "Ready in 2 hours",
"instructions": "Collect from the counter at the back of the store."
}
]
}{
"error": {
"code": "unauthorized",
"message": "Missing or invalid Authorization header"
}
}{
"error": {
"code": "forbidden",
"message": "This operation requires a secret key. Publishable keys cover catalogue reads and the actions a shopper takes for themselves."
}
}{
"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"
}
}
