Storefront & Orders

Public checkout quote calculation, cart dimension aggregation, directory discovery, and order placement.

POST

Calculate public delivery quotes for consumer checkout. Aggregates dimensions and weights across cart products, computes volumetric weight and size class, validates merchant delivery radius, and evaluates multiple SLAs (Express, Saver, Standard), pickup points, and carrier linehaul options.

Authentication: Public / None

Request Body Fields

Field	Type	Requirement	Description
store_slug	string	Required	Merchant store identifier slug (e.g. "konga-yaba").
dropoff_address	string	Optional	Customer street address for forward geocoding.
dropoff_latitude	decimal	Optional	Destination dropoff latitude.
dropoff_longitude	decimal	Optional	Destination dropoff longitude.
items	array	Optional	Cart items array of { product_id: string, quantity: number } to aggregate weight and dimensions.
destination_mode	string	Optional	Destination fulfillment mode. Allowed:`"DOOR""PICKUP_POINT"` Default: `DOOR`
pickup_point_id	string (uuid)	Optional	Target pickup point UUID when destination_mode is PICKUP_POINT.
declared_value	decimal	Optional	Total declared cart value.

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/storefront/quote/ \
  -H "Content-Type: application/json" \
  -d '{
    "store_slug": "urban-threads",
    "dropoff_address": "15 Adeola Odeku St, Victoria Island, Lagos",
    "dropoff_latitude": 6.4298,
    "dropoff_longitude": 3.4184,
    "items": [
      { "product_id": "89301290-4821-4910-b910-481902849102", "quantity": 2 }
    ]
  }'

Response Payload

201 Created

application/json

{
  "store_id": "42",
  "store_name": "Urban Threads",
  "distance_km": "4.82",
  "destination_mode": "DOOR",
  "delivery_fee": "1800.00",
  "protection_fee": "0.00",
  "platform_fee": "100.00",
  "total_payable": "1900.00",
  "subtotal": "12500.00",
  "currency": "NGN",
  "estimated_duration_min": 25,
  "service_levels": [
    {
      "service_level": "EXPRESS",
      "label": "Express",
      "delivery_fee": "2200.00",
      "total_payable": "2300.00",
      "estimated_duration_min": 18,
      "saver_eligible": true
    },
    {
      "service_level": "SAVER",
      "label": "Saver",
      "delivery_fee": "1450.00",
      "total_payable": "1550.00",
      "estimated_duration_min": 35,
      "saver_eligible": true
    }
  ],
  "pickup_points": [],
  "package_dimensions": {
    "weight_kg": "1.20",
    "billable_weight_kg": "1.20",
    "size_class": "SMALL"
  }
}

POST

Place an order through the public store checkout. Creates the shipment manifest, calculates exact platform and delivery charges, and binds Paystack or manual payment credentials. Supports idempotency keys.

Authentication: Public / None

Request Headers

Idempotency-Key

Prevents duplicate order creation on network retries.

Request Body Fields

Field	Type	Requirement	Description
store_slug	string	Required	Store slug identifier.
customer_name	string	Required	Customer full name.
customer_phone	string	Required	Customer phone number.
customer_email	string	Optional	Customer receipt email.
dropoff_address	string	Required	Dropoff delivery address string.
dropoff_latitude	decimal	Optional	Dropoff latitude.
dropoff_longitude	decimal	Optional	Dropoff longitude.
items	array	Required	Array of { product_id, quantity } items ordered.
delivery_type	string	Optional	Order fulfillment type. Allowed:`"DELIVERY""PICKUP"` Default: `DELIVERY`
service_level	string	Optional	Chosen shipping velocity. Allowed:`"STANDARD""EXPRESS""SAVER"` Default: `STANDARD`
payment_provider	string	Optional	Payment provider for the order. Allowed:`"paystack""manual"` Default: `paystack`
payment_reference	string	Optional	Paystack transaction reference after client checkout.

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/storefront/orders/place/ \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_chk_9948123" \
  -d '{
    "store_slug": "urban-threads",
    "customer_name": "Tunde Bakare",
    "customer_phone": "+2348031234567",
    "dropoff_address": "15 Adeola Odeku St, Victoria Island, Lagos",
    "dropoff_latitude": 6.4298,
    "dropoff_longitude": 3.4184,
    "items": [{"product_id": "89301290-4821-4910-b910-481902849102", "quantity": 1}],
    "service_level": "EXPRESS",
    "payment_reference": "T19284910249"
  }'

Response Payload

201 Created

application/json

{
  "order_number": "ORD-774910",
  "public_token": "vX9k2mPqR7tN4wLzB8cF3hJ6yU1aS0dG",
  "status": "PLACED",
  "payment_status": "PAID",
  "delivery_fee": "1800.00",
  "protection_fee": "0.00",
  "total": "14300.00",
  "mode": "ORDERING",
  "tracking_url": "/order/vX9k2mPqR7tN4wLzB8cF3hJ6yU1aS0dG"
}

GET

Public directory for discovering active merchant stores. Supports GPS bounding-box distance filtering (25km), business category chips, open-now filtering, and SLA precedence sorting.

Authentication: Public / None

Query Parameters

Field	Type	Requirement	Description
category	string	Optional	Store category filter. Allowed:`"FOOD""GROCERY""PHARMACY""RETAIL""ALL"`
city	string	Optional	City name text filter.
lat	decimal	Optional	User GPS latitude for distance sorting.
lng	decimal	Optional	User GPS longitude for distance sorting.
open_now	boolean	Optional	Filter stores currently open for ordering.
limit	integer	Optional	Page size limit (max 50). Default: `20`
offset	integer	Optional	Pagination offset. Default: `0`

Request ExampleHTTPS Live Endpoint

curl -X GET "https://api.tumr.app/api/v1/storefront/directory/?category=FOOD&city=Lagos&open_now=true"

Response Payload

200 OK

application/json

{
  "count": 42,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "id": 412,
      "name": "Example Kitchen",
      "slug": "example-kitchen-yaba",
      "business_category": "FOOD",
      "city": "Lagos",
      "is_open": true,
      "distance_km": 1.4
    }
  ]
}

POST

Forward geocode structured or freeform African address queries into precise GPS coordinates and standardized address components.

Authentication: Public / None

Request Body Fields

Field	Type	Requirement	Description
query	string	Optional	Freeform search query or street text.
house_number	string	Optional	House or building number.
street	string	Optional	Street name.
landmark	string	Optional	Nearby landmark or bus stop.
area	string	Optional	Neighborhood / Area.
city	string	Optional	City name.
country	string	Optional	Two-letter ISO country code. Default: `NG`

Request ExampleHTTPS Live Endpoint

curl -X POST https://api.tumr.app/api/v1/storefront/geocode/ \
  -H "Content-Type: application/json" \
  -d '{"query": "Admiralty Way, Lekki Phase 1", "city": "Lagos"}'

Response Payload

201 Created

application/json

{
  "latitude": 6.4474,
  "longitude": 3.4084,
  "formatted_address": "Admiralty Way, Lekki Phase 1, Lagos, Nigeria",
  "place_id": "osm_32212324",
  "components": {
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria"
  }
}

Previous TopicShipments & Bookings

Next TopicLive Tracking & OTP Verification