Calculate shipping fee
Calculate the delivery fee for a customer based on their location and order total.
Location Input Options:
- Option 1: Provide
latitudeandlongitude(GPS coordinates) - Option 2: Provide
place_name(e.g., “Brooklyn, New York”) - automatically geocoded
Calculation Logic:
- If
place_nameprovided, geocode to coordinates internally - Check if customer is within any active delivery zone (by priority)
- If in zone: Apply zone fee (unless order reaches free_delivery_threshold)
- If not in zone: Calculate distance and match to pricing tier
- Apply tier fee (unless order reaches free_delivery_threshold)
- Return detailed breakdown with applied rule and coordinates
Response Fields:
- applied_rule: Indicates which pricing system was used (zone, distance, or default)
- zone_name: Populated if zone-based, null otherwise
- tier_name: Populated if distance-based, null otherwise
- distance_meters: Calculated distance (null if zone-based)
- is_free: Whether free delivery was applied
- coordinates: Always returned (latitude/longitude) for frontend caching
This is a read-only operation (safe for publishable keys).
Authorizations
API Key Authentication
Use your API key in the Authorization header:
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
- Option 1
- Option 2
Input for a shipping fee calculation. Provide either GPS coordinates (latitude + longitude) or a place_name to geocode.
Customer's GPS latitude
-90 <= x <= 90-1.106583
Customer's GPS longitude
-180 <= x <= 18037.013954
Total order value (before shipping)
x >= 05000
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[]).
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[]).
Parcel dimensions + weight for live carrier rating.
Response
Shipping fee calculated successfully
Calculated delivery fee based on customer location and order total
Calculated delivery fee
x >= 0100
Name of delivery zone if customer is in a zone
null
Name of pricing tier if distance-based pricing was applied
"Within Manhattan"
Distance from store to customer in meters (null if zone-based)
29556.31
Whether delivery is free due to order threshold
false
Human-readable explanation of the fee
"29.6 km away"
Pricing rule that was applied:
- zone: Customer is within a custom delivery zone
- distance: Distance-based tier pricing was used
- default: Fallback pricing (no zone or tier matched)
zone, distance, default "distance"
Customer coordinates (geocoded if place_name was provided)
Which source produced the result — the store's delivery zone/tier rules, live carrier shippo rates, a custom carrier the store has connected, or none (unconfigured).
zone, tier, shippo, custom, none "shippo"
Live multi-carrier rate options, present only when the store has carrier shipping connected AND a destination address + parcel were supplied. Each entry is a real carrier quote; pass a chosen rate_id to buy a label or place an order with that rate.