If you have a custom-built platform, mobile app, or any system that isn't covered by our Shopify or WooCommerce integrations, you can use the swftbox REST API to send orders directly into your Control Room. This is ideal for businesses that want full control over how and when orders are pushed to swftbox.
Before you start
Make sure you have:
An active swftbox account with access to your Control Room at controlroom.swftbox.com.
A developer or technical team member who can make HTTP requests from your system.
Your API key — available from the Integrations section in your Control Room.
How to get your API key
Log in to your Control Room at controlroom.swftbox.com.
Go to Integrations from the left sidebar.
Find the API section and click Generate API Key.
Copy your API key and store it securely — you'll need it for authentication.
Important: Keep your API key private. Do not share it publicly or expose it in client-side code.
Base URL and authentication
All API requests are made to the swftbox base URL using your API key for authentication. Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY
All requests and responses use JSON format, so include Content-Type: application/json in your headers.
Creating an order via the API
To create a new delivery order, send a POST request to the order creation endpoint. Your request body should include:
Customer details — name, phone number, and email (optional).
Delivery address — full street address, city, and area.
Package details — description, number of items, and weight (if applicable).
Order reference — your internal order ID for easy tracking.
Delivery type — same-day, next-day, or express.
Payment method — prepaid or cash on delivery (COD), and the COD amount if applicable.
Enhancements — optional features like OTP verification, signature confirmation, or oversized handling.
Your API documentation (available in the Integrations section of Control Room) contains the full list of fields, required vs. optional parameters, and example payloads.
Tracking order status
Once an order is created, you can:
Poll the status endpoint — make a GET request with your order ID to retrieve the current status at any time.
Use webhooks — set up a webhook URL in your Control Room to receive real-time status updates pushed to your system automatically (recommended).
Setting up webhooks
Webhooks let swftbox notify your system whenever an order status changes — no polling required. To set them up:
Go to Integrations → Webhooks in your Control Room.
Enter your webhook URL — the endpoint on your server that will receive status updates.
Select which events you want to subscribe to (e.g., order confirmed, out for delivery, delivered, failed).
Click Save.
swftbox will send a POST request to your webhook URL each time a subscribed event occurs, including the order ID, new status, and timestamp.
Common status values
Created — order received by swftbox.
Confirmed — order accepted and queued for dispatch.
Out for delivery — driver is en route to the customer.
Delivered — order successfully delivered.
Failed — delivery attempt was unsuccessful (includes failure reason).
Returned — package returned to origin after failed delivery.
Error handling
If your API request fails, the response will include an error code and message explaining what went wrong. Common issues include:
401 Unauthorized — invalid or missing API key.
400 Bad Request — missing required fields or invalid data format.
429 Too Many Requests — you've exceeded the rate limit; wait and retry.
Check the error message in the response body for specific guidance on how to fix the issue.
Rate limits
The swftbox API has rate limits to ensure reliable performance for all users. If you're sending a high volume of orders, consider batching your requests or spacing them out. The current rate limits are documented in your API reference within the Control Room.
Good to know
The API supports both single order creation and bulk order imports — check your API docs for the bulk endpoint.
Every order created via the API appears in your Control Room just like manually created or integration-synced orders.
Your customers still receive WhatsApp notifications and have access to the tracking page for API-created orders.
If you need help with your integration, contact your swftbox account manager or reach out to our customer support through chat on control room