Shipping & Logistics

Reference for the ShippingService class in the Tybrite SDK.

The ShippingService class (accessed via client.shipping) handles delivery fee calculations, zone checking, and shipping configuration retrieval for your commerce storefront.

Methods

getShippingZones

Retrieve all active delivery zones and distance-based pricing tiers. This is useful for displaying delivery availability or potential costs to users early in the shopping journey.

const { pricing_tiers, delivery_zones } = await client.shipping.getShippingZones();

// Display zones on a map or list tiers
console.log(`Configured ${delivery_zones.length} custom delivery zones.`);

---

calculateShipping

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

Via Place Name

// Calculate using a human-readable address or landmark
// Tybrite internally geocodes this to find the best matching zone or tier.
const shipping = await client.shipping.calculateShipping({
  requestBody: {
   place_name: "Westlands, Nairobi, Kenya",
   order_total: 100000
  }
});

Response Fields:

Field	Description
fee	The final calculated delivery cost.
applied_rule	Indicates calculation logic: 'zone', 'distance', or 'default'.
is_free	Boolean indicating if a free delivery threshold was reached.
coordinates	Returns the resolved [lat, lng] even if you searched via place_name.

How Fees Are Calculated

Tybrite uses a priority-based logic to determine the shipping fee:

1. Custom Zones: If the location falls within a defined polygon, the specific zone fee is applied.
2. Distance Tiers: If the customer is outside all zones, the system calculates the distance from your store and matches it to a pricing tier (e.g., 5-10km).
3. Free Delivery: If the order_total exceeds the threshold for that zone/tier, the fee is waived.

---

Precision Tip: For the best user experience, use the browser’s Geolocation API to get high-precision coordinates for the calculateShipping method.

---

Input Flexibility: calculateShipping accepts either { latitude, longitude, order_total } or { place_name, country_code?, order_total }. When place_name is supplied, the worker geocodes via Nominatim. The response shape is identical regardless of input mode: { fee, zone_name, tier_name, distance_meters, is_free, reason, applied_rule, coordinates }.

Response Codes

Both methods accept publishable and secret keys. calculateShipping uses POST purely to carry a structured request body — it is read-only.

getShippingZones (GET /v1/shipping/zones)

Code	Meaning
200	Zones and pricing tiers returned.
401	Invalid or missing API key.
403	Forbidden (e.g., key disabled or store suspended).
429	Rate limit exceeded.
500	Internal server error.

This method has no 400 because it takes no input to validate.

calculateShipping (POST /v1/shipping/calculate)

Code	Meaning
200	Fee calculated and returned.
400	Invalid coordinates (out-of-range lat/lng), missing order_total, or geocoding_failed when a place_name could not be resolved.
401	Invalid or missing API key.
403	Forbidden (e.g., key disabled or store suspended).
404	Store has no shipping configuration (no zones and no distance tiers).
429	Rate limit exceeded.
500	Internal server error — including upstream Nominatim or PostGIS failure.