All requests must be authenticated using one of your organization’s API keys.
The HTTP request must include a header field in the form of Authorization: Basic {API-KEY}, where {API-KEY} should be replaced with your API key string.
Returns the [Model] object after a successful request.
Returns an error if request is invalid (for example, an invalid parameter or invalid api key).
Welcome! The WooDelivery API is a RESTful web service designed for developers and integrations to interact programmatically with WooDelivery’s data and real-time delivery management features.
It supports creating, reading, updating, and deleting data using JSON-formatted requests. The current version of the API is v2.
Request/Response Format
All data exchanged between clients and the API is in JSON format over HTTPS.
Please note that only application/json is accepted as the content type, and any request body must be JSON-encoded.
API Testing Tools
You can use third-party tools to test API endpoints before integrating them into your application. For example, Postman is a GUI tool that allows you to make API requests. It is very useful for learning the WooDelivery API or testing requests while building your implementation.
JSON Date-time Format
All date-time strings in the API payload and response messages are in the JSON ISO 8601 format and are in the UTC time zone. You may need to convert these values to your local time on your system.
Support
If you have questions about using the API, or have come across a bug you'd like to report, submit a ticket through your WooDelivery admin dashboard.
Terms of Service
By accessing or using our APIs, you agree to the WooDelivery APIs Terms of Service.
API Key
All requests must be authenticated with an API key from your organization. You can generate API key on the "Settings - Integration" page in your admin dashboard. Ensure your API key is kept secure: do not share it with anyone outside your organization and avoid including it in publicly accessible source code.
Authentication
The API is secured with HTTP Basic authentication. While making a HTTP request, you must put your 'API_KEY' value with Authorization attribute in the request header.
The HTTP request must include a header field in the form of Authorization: Basic {API-KEY}, where {API-KEY} should be replaced with your API key string.
Testing Your API Key
The HTTP GET request must include a header field in the form of Authorization: Basic {API-KEY}, where {API-KEY} should be replaced with your API key string.
General Quota Limits
The following quota limits are set for Web API and Webhook integration per organization account:
| Subscription | Quota Limits |
|---|---|
| Starter Plan | API integration is unavailable. |
| Professional Plan | Maximum 150 requests per minute; Maximum 10,000 requests per day. |
| Enterprise Plan | Unlimited requests for clients with dedicated web server and database. |
Exceeding Quota Limits
If you exceed the quota limits, you will first receive a 429 error. Failure to slow down your request rate may result in a temporary ban. If your application consistently make a high volume of API requests (for example, exceeding 10,000 requests per hour), it will take additional necessary actions to protect our system’s stability and reliability from the impact of excessive API polling. For example, the IP address of your system may be temporarily blocked from accessing our public API server.
API Throttling
To stay within the API limit, we strongly recommend that you use a library to help you orchestrate your request rate. Few guidelines on how to avoid making too many API requests:
- If possible, use webhooks instead of polling for state changes. (Webhooks can be set up on the admin dashboard under settings – notification page)
- When creating many tasks, use the batch endpoint if possible.
- If it seems like you’re making many requests for a simple operation or finding many entities to locally scan for a single one, it’s possible you’re using the API in an inefficient way.
When a request is successful, you will receive an HTTP 200 response code or another 2xx code. The response body will contain the JSON data for your request. When a request encounters an issue, the API will respond with a non-200 status code. To provide better insight into the problem, the API uses various HTTP error codes. Additionally, it may include JSON data in the response body, offering your application detailed information on what went wrong.
HTTP Response Codes
Our API uses standard HTTP response codes to indicate whether a request has been successfully completed or encountered an error.
| Error Code | Meaning |
|---|---|
| 200 OK | The request has succeeded. |
| 400 Bad Request | Invalid request or other errors. |
| 401 Unauthenticated | Missing API key or invalid API key. |
| 429 Too Many Requests | Too many requests within a given time frame or reached the daily quota limit. |
| 5XX Service Unavailable | The server is not able to handle the request or other errors. |
All date-time strings in the payload and response messages are in the JSON ISO 8601 format and are in the UTC time zone. You may need to convert these values to your local time on your system.
All date-time strings in the payload and response messages are in the JSON ISO 8601 format and are in the UTC time zone. You may need to convert these values to your local time on your system.
To search for historical completed tasks, you must set "taskStatusId": "50" in your payload body. The status ID 50 indicates the task status is completed.
Webhooks are one way that our system can send automated messages or information to other apps when something happens. It is designed for your application to be notified of important system events, as soon as these take place within WooDelivery. For example, when driver complete a delivery job on WooDelivery platform, it sends a real-time JSON message to your in-house system to update the order status to completed status.
How to set up webhooks?
To use the webhook feature, your system needs an endpoint to receive real-time delivery task updates from our system. This endpoint is known as the Webhook Callback URL. You can also use a third-party system to receive webhook messages if needed.
To create a webhook in our system, log in to your admin dashboard and navigate to the "Settings - Notifications" page. Click on the "Add Notification Rule" button at the top-right side of the page, then select the webhook method (HTTP GET or HTTP POST) from the drop-down menu.
Webhook Trigger Events
The following events can be used to trigger a webhook message to be sent to your system:
| Webhook Event |
|---|
| When new task is created (unassigned status) |
| When task is assigned to a driver |
| When task is processed |
| When packages loaded to vehicle or picked up |
| When driver starts task (transit status) |
| When driver arrived at destination |
| When item ready for collection |
| When task completed successfully |
| When task is failed |
| When item returned to sender |
| When task is cancelled |
Webhook Message Sample
If you choose the "Standard Task JSON Data" option on your webhook setup, the webhook will send the Task object to your system. Here is a sample JSON data structure:
To stay within the API quota limit, we recommend using webhooks instead of API polling for monitoring state changes of delivery tasks.
To stay within the API quota limit, we recommend using webhooks instead of API polling for monitoring state changes of delivery tasks.