Delivables API

Build powerful delivery experiences with the Delivables API. Manage orders, optimize routes, and integrate seamlessly with your existing systems.

Simple Authentication

Secure API key authentication with tenant-scoped access control.

Order Management

Create, track, and manage orders with real-time updates.

Route Optimization

Intelligent routing algorithms to optimize delivery efficiency.

Enterprise Ready

Built for scale with robust security and reliability.

Base URL

https://api.delivables.com/v1

Getting Started

To start using the Delivables API, you'll need to generate an API key from your dashboard.

Visit the Delivables Dashboard

Go to delivables.com and sign up or log in to your account.

Access Developer Settings

Click your profile email at the bottom-left of the sidebar, then select Developer from the dropdown menu.

Generate Your API Key

Click Generate API Keyto create a new key. Store it securely—you won't be able to see it again.

Important Notes

API keys are branch-scoped and only work for the branch they were created in
Keep your API keys secret—never expose them in client-side code
API keys are required on every request

Authentication

All API requests require two headers for authentication. Both must be present on every request.

Required Headers

Every API request must include both the Authorization and X-Tenant-Domain headers. Requests missing either header will fail with a 401 Unauthorized error.

Authorization Header

Pass your API key as a Bearer token in the Authorization header.

Authorization: YOUR_API_KEY

X-Tenant-Domain Header

Specify your organization's subdomain to identify the tenant.

X-Tenant-Domain: your-organization-subdomain.delivables.com

Complete Example

curl -X GET "https://api.delivables.com/v1/health" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxx" \
  -H "X-Tenant-Domain: your-organization-subdomain.delivables.com"

Health Check

Use the health endpoint to validate your API key, tenant domain, and API availability.

Create Order

Create and manage delivery orders through the API.

Create Order Rules

Distance and time are always calculated server-side based on locations
Delivery fees come from branch rate settings unless explicitly overridden
Express fees are added automatically for EXPRESS service type
Maximum 4 orders can be created per request

Create Order - Request Body

Field	Type	Required	Description
serviceType	string (enum: "STANDARD" \| "EXPRESS")	No	Service type - affects delivery fee calculation
orders	array	Yes	Array of orders to be delivered. Distance and time will be calculated automatically.
orders[].location.address	string	Yes	Branch location will be used if not provided
orders[].location.lat	number	Yes	Branch location will be used if not provided
orders[].location.lng	number	Yes	Branch location will be used if not provided
orders[].location.placeId	string	No
orders[].location.utmCoordinates	string	No
orders[].destination.address	string	Yes
orders[].destination.lat	number	Yes
orders[].destination.lng	number	Yes
orders[].destination.placeId	string	No
orders[].destination.utmCoordinates	string	No
orders[].customerName	string	Yes	Recipient name
orders[].customerNumber	string	Yes	Recipient phone number
orders[].senderName	string	No	Sender name
orders[].senderNumber	string	No	Sender phone number
orders[].packageCost	number	Yes	Package/goods cost
orders[].deliveryFee	number	No	Custom delivery fee (optional - will be calculated from branch rates if not provided)
orders[].expressFee	number	No	Express delivery fee (optional)
orders[].paymentOption	string (enum: "Delivery Fee Only (T&T)" \| "Package Cost Only" \| "Delivery Fee & Package Cost" \| "No Payment Required")	Yes	What does customer pay for
orders[].paymentMethod	string (enum: "Cash On Delivery" \| "Mobile Money on Delivery" \| "Customer Already Paid" \| "Other" \| "No Payment Required")	Yes	How does customer pay for the delivery
orders[].otherMethod	string	No	Other payment method description
orders[].position	number	No	Item position in delivery sequence
orders[].notes	string	No	Delivery notes
orders[].reference	string	No	Your reference number
riderId	string	No	Rider ID to assign order to (optional - order will be UNASSIGNED if not provided)
deliveryType	string (enum: "SINGLE_DELIVERY" \| "MULTIPLE_DELIVERY" \| "MULTIPLE_PICKUPS")	No	Delivery type (auto-detected if not provided)
routeOption	string (enum: "MANUAL" \| "OPTIMIZED")	No	Route optimization option
useQueue	boolean	No	Force queue-based processing for higher success rate (default: false, uses hybrid with automatic fallback)

List Orders - Query Parameters

Field	Type	Required
startDate	string	No
endDate	string	No
search	string	No
page	string	No
limit	string	No
take	string	No
skip	string	No
customerNumber	string	No
riderId	string	No
status	string	No
serviceType	string	No
excludeCanceled	boolean	No
excludeCompleted	boolean	No

Get Order by ID - Path Parameters

Field	Type	Required	Description
id	string	Yes

Optimize Route - Request Body

Field	Type	Required
items	array	Yes
items[].id	string	Yes
items[].location.lat	number	Yes
items[].location.lng	number	Yes
items[].location.address	string	Yes
items[].location.utmCoordinates	string	No
items[].destination.lat	number	Yes
items[].destination.lng	number	Yes
items[].destination.address	string	Yes
items[].destination.utmCoordinates	string	No
deliveryType	string (enum: "MULTIPLE_PICKUPS" \| "MULTIPLE_DELIVERY")	Yes
branchId	string	No

Jobs

Track the status of asynchronous operations.

Get Job Status - Path Parameters

Field	Type	Required	Description
id	string	Yes

Error Handling

The API uses conventional HTTP response codes to indicate success or failure of requests.

Code	Description
200	Request succeeded
400	Bad request — Invalid parameters or malformed request body
401	Unauthorized — Missing or invalid API key
404	Not found — The requested resource doesn't exist
429	Rate limited — Too many requests
500	Internal server error — Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401
  }
}

Ready to get started?

Generate your API key and start integrating Delivables into your application today.

Go to Delivables