Calculate shipping fee
The ways a shopper can receive an order — the store’s delivery options and pickup locations — priced for their location and basket, plus carrier options when a destination address and parcel are sent.
Location: latitude + longitude, or a place_name (geocoded). country_code and
postal_code may accompany either; they match zones defined by country and postcode, and a value
sent here takes precedence over the one found by geocoding. With no location, address_to +
parcel returns carrier options only, with fee null.
Basket: order_total is the merchandise after discounts, before tax and shipping; free-delivery
thresholds and minimum orders are measured against it. items lists the basket’s variants and
quantities. It is optional, and is what lets the store apply rates that depend on the parcel’s
weight and rules it sets for particular product categories — a surcharge, delivery only to nearby
addresses (restriction: local_only), or collection only (restriction: pickup_only).
Pricing: the first zone containing the location — a zone drawn on a map, or a zone covering
whole countries or postcode prefixes; otherwise the distance tier matching its distance from the
store (a range includes its start and stops just before its end); otherwise the store’s
“everywhere else” rate. A matched rate is free when order_total reaches its free-delivery
threshold. A store with no rates at all charges nothing (applied_rule: none).
Options: options[] lists everything the shopper can choose between. The first delivery
option, id: place, is the matched rate itself (“Standard delivery”); its fee is also returned as
fee. The store may add named options to the same rate — Express, Next day — with ids of the form
opt:<id>, each with its own fee and estimate. Pickup options (method: pickup, ids of the form
pickup:<location id>) follow, nearest first when the location is known. An option with
available: false exists but does not apply to this basket yet, usually because order_total is
below its minimum_order. To order with an option, pass its id as shipping_option_id on
POST /v1/orders.
No delivery to the address: when the store does not deliver there but does offer pickup, the
response is 200 with deliverable: false, fee: null and only the pickup options. When it offers
neither, the answer is 400 shipping_not_deliverable.
Multiple locations: when the store delivers from whichever of its locations is nearest the
shopper, fulfilled_from names that location, and distance tiers are measured from it.
Carrier options (rates[]) come from the store’s connected carrier account and its custom
shipping extension. To order with one, pass its rate_id and source on POST /v1/orders as
shipping_rate_id and shipping_rate_source.
This is a read-only operation (safe for publishable keys).
curl --request POST \
--url https://api.tybritelabs.com/v1/shipping/calculate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"latitude": 40.6782,
"longitude": -73.9442,
"order_total": 50
}
'{
"fee": 5.99,
"currency": "USD",
"zone_name": null,
"tier_name": "Local (within 10 km)",
"distance_meters": 8547.99,
"is_free": false,
"free_threshold": 75,
"configured": true,
"reason": "Local (within 10 km)",
"applied_rule": "distance",
"coordinates": {
"latitude": 40.6782,
"longitude": -73.9442,
"country_code": "US",
"postal_code": "11225"
},
"rate_source": "tier",
"deliverable": true,
"restriction": "none",
"options": [
{
"id": "place",
"method": "delivery",
"name": "Standard delivery",
"fee": 5.99,
"currency": "USD",
"is_free": false,
"estimate": null,
"available": true,
"free_threshold": 75
},
{
"id": "opt:9a1f3c2e-5b7d-4e8a-a2c4-6d8e0f1a3b5c",
"method": "delivery",
"name": "Express",
"fee": 14.99,
"currency": "USD",
"is_free": false,
"estimate": "Next business day",
"available": true
},
{
"id": "pickup:3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
"method": "pickup",
"name": "Pickup at Brooklyn store",
"fee": 0,
"currency": "USD",
"is_free": true,
"estimate": "Ready in 2 hours",
"available": true,
"location": {
"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",
"instructions": "Collect from the counter at the back of the store.",
"distance_meters": 3412.57
}
}
],
"fulfilled_from": 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.
Body
- Option 1
- Option 2
- Option 3
Input for a shipping fee calculation. Provide GPS coordinates (latitude + longitude), a place_name to geocode, or — for carrier options only — address_to with a parcel.
Customer's GPS latitude
-90 <= x <= 9040.6782
Customer's GPS longitude
-180 <= x <= 180-73.9442
ISO 3166-1 alpha-2 country code of the destination. Matches zones defined by country; a value sent here takes precedence over the one found from the location.
^[A-Za-z]{2}$"US"
Postcode of the destination. Matches zones narrowed to postcode prefixes; a value sent here takes precedence over the one found from the location.
16"11225"
The basket's lines. Optional; with it, the store's weight-based rates and its rules for product categories (surcharges, local-only delivery, collection only) apply. A rate that depends on weight applies only when every line's variant has a weight.
500Show child attributes
Show child attributes
The order's merchandise after discounts, before tax and shipping. A free-delivery threshold is compared against this figure. Must be a number of zero or more; defaults to 0.
x >= 050
A shipping address for live carrier rating. Supplied alongside a parcel to ALSO get live carrier rates from a connected carrier account (returned as rates[]).
Show child attributes
Show child attributes
A shipping address for live carrier rating. Supplied alongside a parcel to ALSO get live carrier rates from a connected carrier account (returned as rates[]).
Show child attributes
Show child attributes
Parcel dimensions + weight for live carrier rating.
Show child attributes
Show child attributes
Response
The delivery charge for the location
The store's delivery charge for a location and order total. An address is priced by the first zone that contains it, otherwise by the distance rate for its distance from the store, otherwise by the store's "everywhere else" rate. A store with no delivery rates at all charges nothing (applied_rule: none). options lists every delivery option and pickup location the shopper can choose between. When the store does not deliver to the address but offers pickup, deliverable is false, fee is null and options holds the pickup locations only; when it offers neither, the answer is 400 shipping_not_deliverable instead.
The standard delivery charge (the place option's fee), in currency. Null on a carrier-options-only request (no location was sent) and when the store does not deliver to the address but offers pickup (deliverable: false).
x >= 05.99
The currency of fee and free_threshold — the store's own currency.
"USD"
The zone that priced the address, when a zone did.
null
The distance rate that priced the address, when one did.
"Local (within 10 km)"
Distance from the store to the address in meters, when it was measured.
8547.99
True when no delivery charge applies to this order (fee is 0).
false
The order total from which the matched rate delivers free, or null when it has none.
75
Whether the store has any delivery rates. False means delivery is not charged through the store's rates at all.
true
A short, shopper-readable explanation of the charge.
"Local (within 10 km)"
Which of the store's rates priced the address:
- zone: a delivery zone contains it
- distance: a distance rate matched its distance from the store
- fallback: the store's "everywhere else" rate
- none: the store has no delivery rates (fee 0), or a carrier-options-only request
zone, distance, fallback, none "distance"
The address's coordinates (geocoded when a place_name was sent), with the country and postcode used to match zones when known.
Show child attributes
Show child attributes
Whether the store delivers to the address. False when only pickup is offered for it — because the address is outside the store's delivery area, or because an item in the basket can only be collected.
true
A limit the basket's items place on how the order can be received, from the store's rules for product categories:
- none: no limit
- local_only: delivered only within the store's map zones and distance tiers, not to country or postcode zones or the "everywhere else" rate
- pickup_only: collection only; no delivery option is offered
none, local_only, pickup_only "none"
Every way the shopper can receive the order: the delivery options first (place, then any named options), then the pickup locations, nearest first when the location is known. Absent on a carrier-options-only request.
Show child attributes
Show child attributes
When the store delivers from whichever of its locations is nearest the shopper, the location this order would leave from; distance tiers are measured from it. Null otherwise.
Show child attributes
Show child attributes
Which source produced the result — the store's zone, distance tier or fallback rate, a connected carrier account (shippo), the store's custom shipping extension (custom), or none.
zone, tier, fallback, shippo, custom, none "tier"
Carrier options, present when the store has a carrier account or a custom shipping extension AND a destination address + parcel were sent. Each is a real quote. To order with one, pass its rate_id and source as shipping_rate_id / shipping_rate_source on createOrder, where the option is fetched again from its source before it is charged.
Show child attributes
Show child attributes
curl --request POST \
--url https://api.tybritelabs.com/v1/shipping/calculate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"latitude": 40.6782,
"longitude": -73.9442,
"order_total": 50
}
'{
"fee": 5.99,
"currency": "USD",
"zone_name": null,
"tier_name": "Local (within 10 km)",
"distance_meters": 8547.99,
"is_free": false,
"free_threshold": 75,
"configured": true,
"reason": "Local (within 10 km)",
"applied_rule": "distance",
"coordinates": {
"latitude": 40.6782,
"longitude": -73.9442,
"country_code": "US",
"postal_code": "11225"
},
"rate_source": "tier",
"deliverable": true,
"restriction": "none",
"options": [
{
"id": "place",
"method": "delivery",
"name": "Standard delivery",
"fee": 5.99,
"currency": "USD",
"is_free": false,
"estimate": null,
"available": true,
"free_threshold": 75
},
{
"id": "opt:9a1f3c2e-5b7d-4e8a-a2c4-6d8e0f1a3b5c",
"method": "delivery",
"name": "Express",
"fee": 14.99,
"currency": "USD",
"is_free": false,
"estimate": "Next business day",
"available": true
},
{
"id": "pickup:3d5c7a10-8b2e-4f61-9c4d-1a2b3c4d5e6f",
"method": "pickup",
"name": "Pickup at Brooklyn store",
"fee": 0,
"currency": "USD",
"is_free": true,
"estimate": "Ready in 2 hours",
"available": true,
"location": {
"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",
"instructions": "Collect from the counter at the back of the store.",
"distance_meters": 3412.57
}
}
],
"fulfilled_from": null
}