Calculate shipping fee

Calculate the delivery fee for a customer based on their location and order total.

Location Input Options:

• Option 1: Provide latitude and longitude (GPS coordinates)
• Option 2: Provide place_name (e.g., “Westlands, Nairobi, Kenya”) - automatically geocoded using Nominatim

Calculation Logic:

1. If place_name provided, geocode to coordinates internally
2. Check if customer is within any active delivery zone (by priority)
3. If in zone: Apply zone fee (unless order reaches free_delivery_threshold)
4. If not in zone: Calculate distance and match to pricing tier
5. Apply tier fee (unless order reaches free_delivery_threshold)
6. 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).

POST /v1/shipping/calculate

cURL

short_distance

curl --request POST \
  --url https://api.tybritelabs.com/v1/shipping/calculate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "latitude": -1.106583,
  "longitude": 37.013954,
  "order_total": 1500
}
'

200

distance_based

{
  "fee": 100,
  "zone_name": null,
  "tier_name": "Within Nairobi",
  "distance_meters": 19.23,
  "is_free": false,
  "reason": "19 m away",
  "applied_rule": "distance"
}

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.

Body

application/json

Option 1

Option 2

latitude · number<double> · required

Customer's GPS latitude

Required range: -90 <= x <= 90

Example:

-1.106583

longitude · number<double> · required

Customer's GPS longitude

Required range: -180 <= x <= 180

Example:

37.013954

order_total · number<float>

Total order value (before shipping)

Required range: x >= 0

Example:

5000

Response

200

application/json

Shipping fee calculated successfully

Calculated delivery fee based on customer location and order total

fee · number<float>

Calculated delivery fee

Required range: x >= 0

Example:

100

zone_name · string | null

Name of delivery zone if customer is in a zone

Example:

null

tier_name · string | null

Name of pricing tier if distance-based pricing was applied

Example:

"Within Nairobi"

distance_meters · number<float> | null

Distance from store to customer in meters (null if zone-based)

Example:

29556.31

is_free · boolean

Whether delivery is free due to order threshold

Example:

false

reason · string

Human-readable explanation of the fee

Example:

"29.6 km away"

applied_rule · enum<string>

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)

Available options: zone, distance, default

Example:

"distance"

coordinates · object

Customer coordinates (geocoded if place_name was provided)

Show child attributes