Integrating Our API with Your Delivery Platform

A practical guide for developers and product teams

Our RESTful API gives you end-to-end control of the locker workflow—from locker discovery to driver drop-off and user pickup. Below you’ll find the complete integration flow, broken into Instant Delivery and Grocery (Nominated-Day) Delivery use-cases. Each step references key endpoints, required payloads, and decision logic so you can build quickly and confidently.

🗺️ Shared Core Flow (Applies to Both Use-Cases)

  • Interactive API Flow Diagram
    Visualize each step from locker selection to user pickup.
  • Live Testing Console
    Try real-time API requests in a built-in sandbox.
  • Code Snippet Library
    Ready-made examples in Python, JavaScript, and more.
API-driven Compartment Match Accuracy 85%
Faster Order-to-Locker Assignment vs. manual routing 76%
Reduction in failed deposits after auto-assign rollout 92%
Driver satisfaction on QR-code locker access 65%

 

 

 

Step Purpose Primary Endpoints
Locker Discovery  Capture user coordinates or postcode → fetch lockers in radius. GET /lockers/search?lat={}&lng={}
Range Validation & Filtering Capture user coordinates or postcode → fetch lockers in radius. POST /lockers/filter
Availability & Queue Check Check real-time compartment availability + queue length. GET /lockers/{id}/availability
Checkout Confirmation / Address Switch Check real-time compartment availability + queue length. (client-side)
Basket Submission & Age/Space Verification Partner posts basket JSON (items, dims, temp, age flag). API returns pass/fail and size match. POST /orders/validate
Locker Reservation & Code Assignment Reserve compartments, receive pickup + driver codes. POST /orders/reserve
Driver Drop-Off Driver opens locker via QR / PIN; API logs event. POST /orders/{id}/deposit
User Pickup / Expiry Logic User opens locker; expiry timers and reminders trigger. POST /orders/{id}/pickup
Man Drawing on Whiteboard
Person Working on a Laptop
Man Working on a Laptop

⚡ Instant Delivery Flow

  • Real-Time Locker Scoring
    Use the optional &eta= parameter in /lockers/search to rank lockers by driver travel time.

  • Auto-Assignment Endpoint
    POST /orders/auto-assign lets your dispatch engine send multiple orders; our AI returns optimal locker IDs + compartment types in <300 ms.

  • Driver App Integration
    Embed GET /orders/{id}/driver-token to pull a one-time QR code for seamless door-to-locker routing.

  • Exception Handling
    If a locker becomes full en-route, call POST /orders/{id}/reassign to receive the next-best locker recommendation.

🛒 Grocery (Nominated-Day) Delivery Flow

  • Time-Slot Reservation
    Pass delivery_window_start and delivery_window_end in /orders/validate. The API blocks compartments for that slot only.

  • Bulk Basket Validation
    Send an array of up to 200 orders to /orders/bulk-validate for carton-level temperature and volume checks.

  • Split-Basket Logic
    If frozen + ambient items can’t fit one compartment, the API returns split:true with compartment IDs per temperature zone.

  • Route Export
    Call GET /routes/download?date=YYYY-MM-DD to pull a CSV/JSON of all lockers, compartments, and driver codes for your nightly line-haul.

🛠️ Developer Best Practices

  • Metadata Matters – Always include item_dimensions, temp_requirement, and age_check flags; they drive AI accuracy.

  • Idempotent Calls – Use the X-Request-ID header to safely retry network-flaky calls.

  • Webhooks – Subscribe to locker.status, order.expiring, and order.picked_up events for real-time UI updates.

  • Sandbox First – Generate keys at dashboard → Developers → Create Sandbox Token before hitting production.

🚀 Next Steps

  • Time-Slot Reservation
    Pass delivery_window_start and delivery_window_end in /orders/validate. The API blocks compartments for that slot only.

  • Bulk Basket Validation
    Send an array of up to 200 orders to /orders/bulk-validate for carton-level temperature and volume checks.

  • Split-Basket Logic
    If frozen + ambient items can’t fit one compartment, the API returns split:true with compartment IDs per temperature zone.

  • Route Export
    Call GET /routes/download?date=YYYY-MM-DD to pull a CSV/JSON of all lockers, compartments, and driver codes for your nightly line-haul.