We’re excited to have you here. Our API is built for seamless integration and powerful functionality to help you reach your goals.
Whether you're developing a new application, enhancing an existing one, or just exploring what our API offers — everything you need is right here.
We've added a new webhook specifically for order status updates.
Now, you can automatically receive real-time updates whenever the status of an order changes
in our system.
check it out.
API Rate Limit :
To ensure fair usage and optimal performance of our API, we have implemented a rate limit of
60 requests per 30 seconds
for each user.
This limit is enforced across all endpoints.
If the rate limit is exceeded, the API will return a JSON-formatted error response, consistent with all other returned errors, containing the appropriate error message.
Endpoints :
Before delving into our endpoints, please import our collection to your postman via the
following URL:
Response :
A list of cities in the format
[{id: 1, city_name: 'name'}].
Request Sample :
Query Parameters : No parameters
Request Body : No body
Response Sample :
Response body on success :
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "1", // the id of the city (string)
"city_name": "name" // the text of the city (string)
}
]
}
Parameter :city_id
(int)
[Required] :
Specifies the city for which regions
are retrieved.
Response :
A list of regions within the specified city in the format
[{id: 1, region_name: 'name'}].
Request Sample :
Query Parameters :
"city_id":"ID"
Request Body: No body
Response Sample :
Response body on success:
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "1", // the id of the region (string)
"region_name": "name" // the text of the region (string)
}
]
}
Response :
A list of available package sizes in the format
[{id: 1 ,size: 'name'}].
Request Sample :
Query Parameters : No parameters
Request Body : No body
Response Sample :
Response body on success :
{
"status": true,
"errNum": "S000", // On success "S000" will be returned "msg": "ok", // Success message
"data": [
{
"id": "1", // the id of the package size (string)
"size": "name" // the text of the package size (string)
}
]
}
After preparing all the order info (city-id, region-id, package-size, customer-phone, price, client-name, location description etc.) you can proceed and submit your order-creation info to the API.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"client name", // (the name of the client)
"client_mobile":"+9647700000000", // (client phone number)
"client_mobile2":"+9647700000000",//(client second phone number)
"city_id":"5", // (the city id of the client)
"region_id":"2", // (the region id of the client)
"type_id": 1, // (the type id of the order, this is set automatically by the system)
"merchant_mobile":"07700000000", // (set from merchant info)
"items_number":"1", // (number of items in the order)
"price":"25000", // (price of the order including delivery fee)
"package_size":"1", // (the size of the order)
"cash_fee":0, // (set if order price exceeds 1'000'000 IQD)
"location":"market", // (client delivery location description)
"merchant_id":"5", // (set from merchant info)
"current_city":"1", // (set automatically by the system)
"merchant_city":"1", // (set from merchant info)
"company_price":4000, // (the delivery fee of this order)
"merchant_price":21000, // (the order price without delivery fee)
"type_name":"ملابس", // (orders goods type)
"merchant_created_at":"2024-08-10 23:59:59", // (set automatically by the system)
"merchant_notes":"عدم فتح القطعة", // (set by the merchant)
"qr_id": 38799216, // (the QR id of this order, this will be the main identifier of the order)
"pickup_id": "1", // (the pickup driver assigned to this order)
"pickup_created_at": "2024-08-10 04:30:10pm", // (set automatically by the system)
"id": "ID", // (set automatically by the system)
"qr_link": "https://modon-express.net/merchant/print-single-tcpdf?id=ID&token=Merchant_Token" // (the receipt PDF link)
}
]
}
Now with your order being alive in our system. You might want to inquire about order details/status.
To do so, the APIs below have been provided (basically returns a list of order(s) with their status).
Alternatively you can retrieve orders by their ids using this API (Retrieve Specific Orders by IDs).
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"client name", // (name of the client)
"client_mobile":"+9647700000000", // (client mobile number)
"items_number":"1", // (number of items in this order)
"created_at":"2023-08-13 22:12:18", // (the date and time of when the order was created)
"city_name":"بغداد", // (city name of client)
"region_name":"شارع فلسطین", // (region name of the client)
"status_id":"2", // (the status id of the order)
"status":"تم استلام الطلب من قبل المندوب", // (the status text of the order)
"price":"20000", // (the order price including delivery fee)
"location":"market", // (the description of the client location)
"issue_notes":"لا یوجد", // (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", // (a note written by the merchant)
"client_mobile2":"+9647700000000", // (client second mobile number)
"updated_at":"2024-06-22 11:28:53", // (the last date and time the order data was updated)
"city_id":"13", // (client city number)
"region_id":"1043", // (client region number)
"replacement":"0", // (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", // (order goodes type)
"id":"103", // (order id)
"has_merchant_fin_record": 0, // OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0, // OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", // (the delivery fee of this order)
"package_size":"عادي", // (the order size)
"merchant_invoice_id":"-1", // (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
"urgent": "0", // (indicates if the order is urgent: 1 = urgent, 0 = not urgent)
"urgent_datetime_to_deliver": "0000-00-00 00:00:00", // (Deadline for delivering the order if it is marked as urgent)
"deliver_estimation_datetime": "0000-00-00 00:00:00" // (Estimated delivery time, automatically set by the system)
}
]
}
In scenarios where the order needs to be deleted and the order is still in the merchant's
possession, this endpoint provides the ability to do so.
Note : Order status must be equal to 1 (new order) to be deleted.
This endpoint allows you to retrieve specific orders by providing a comma-separated list of order IDs.
Unlike the "Retrieve Orders" endpoint, which returns all orders,
this batch retrieval is limited to a maximum of 25 order IDs per request.
A comma-separated string of order IDs to retrieve.
A maximum of 25 IDs is allowed—any additional IDs beyond this limit will be discarded.
Response :
Details of the selected orders.
Request Sample :
Query Parameters :
"token":"token"
Request Body :
"ids":"11,23,75,29" // (string of comma separated values, max 25 ids)
Response Sample :
Response body on success :
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"client name", // (name of the client)
"client_mobile":"+9647700000000", // (client mobile number)
"items_number":"1", // (number of items in this order)
"created_at":"2023-08-13 22:12:18", // (the date and time of when the order was created)
"city_name":"بغداد", // (city name of client)
"region_name":"شارع فلسطین", // (region name of the client)
"status_id":"2", // (the status id of the order)
"status":"تم استلام الطلب من قبل المندوب", // (the status text of the order)
"price":"20000", // (the order price including delivery fee)
"location":"market", // (the description of the client location)
"issue_notes":"لا یوجد", // (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", // (a note written by the merchant)
"client_mobile2":"+9647700000000", // (client second mobile number)
"updated_at":"2024-06-22 11:28:53", // (the last date and time the order data was updated)
"city_id":"13", // (client city number)
"region_id":"1043", // (client region number)
"replacement":"0", // (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", // (order goodes type)
"id":"103", // (order id)
"has_merchant_fin_record": 0, // OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0, // OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", // (the delivery fee of this order)
"package_size":"عادي", // (the order size)
"merchant_invoice_id":"-1" // (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
"urgent": "0", // (indicates if the order is urgent: 1 = urgent, 0 = not urgent)
"urgent_datetime_to_deliver": "0000-00-00 00:00:00", // (Deadline for delivering the order if it is marked as urgent)
"deliver_estimation_datetime": "0000-00-00 00:00:00" // (Estimated delivery time, automatically set by the system)
}
]
}
Several APIs are available for managing merchant invoices:
Authentication Requirements for Invoice APIs
To use the Invoice APIs, only the Merchant token is accepted for authentication. If a Merchant user token is used instead, an authentication error will be returned.
Please ensure that the correct token is used to avoid authentication issues.
To inquire about invoices, you can use the get merchant invoices API and retrieve invoices.
Then get invoice orders from the following APIs.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"id": "3", // (invoice id)
"merchant_price": "170000", // (total price to be received from this invoice)
"delivered_orders_count": "7", // (number of delivered orders for this invoice)
"replacement_delivered_orders_count": "0", // (number of replacement delivered orders)
"status": "تم الاستلام من قبل التاجر", // (invoice status text)
"merchant_id": "5", // (merchant id)
"updated_at": "2023-12-20 17:01:46" // (last date and time the invoice was updated)
}
]
}
Returns all orders associated with a particular invoice.
Request Sample :
Query Parameters :
"token":"token"
"invoice_id":"ID"
Request Body : No body
Response Sample :
Response body on success :
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data":
"invoice" : [
{
"id": "3", // (invoice id)
"merchant_price": "170000", // (total price to be received from this invoice)
"delivered_orders_count": "7", // (number of delivered orders for this invoice)
"replacement_delivered_orders_count": "0", // (number of replacement delivered orders)
"status": "تم الاستلام من قبل التاجر", // (invoice status text)
"merchant_id": "5", // (merchant id)
"updated_at": "2023-12-20 17:01:46" // (last date and time the invoice was updated)
}
] ,
"orders" : [
{
"client_name":"محمد", // (name of the client)
"client_mobile":"+9647704723599", // (client mobile number)
"items_number":"1", // (number of items in this order)
"created_at":"2023-08-13 22:12:18", // (the date and time of when the order was created)
"city_name":"بغداد", // (city name of client)
"region_name":"شارع فلسطین", // (region name of the client)
"status_id":"2", // (the status id of the order)
"status":"تم استلام الطلب من قبل المندوب", // (the status text of the order)
"price":"20000", // (the order price including delivery fee)
"location":"market", // (the description of the client location)
"issue_notes":"لا یوجد", // (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", // (a note written by the merchant)
"client_mobile2":"07", // (client second mobile number)
"updated_at":"2024-06-22 11:28:53", // (the last date and time the order data was updated)
"city_id":"13", // (client city number)
"region_id":"1043", // (client region number)
"replacement":"0", // (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", // (order goodes type)
"id":"103", // (order id)
"delivery_price":"9000", // (the delivery fee of this order)
"package_size":"عادي", // (the order size)
"merchant_invoice_id":"8" // (the merchant invoice number)
}
]
}
When the invoice is sent to the merchant he has to confirm the receipt by scanning the invoice's QR-code via the merchant-app.
Alternatively, the invoice can be confirmed (received) by the API below.
At our company, we understand the importance of
real-time updates and seamless integration between systems. That's why we offer webhooks as a
powerful feature to keep your system automatically in sync with key events in our platform.
With webhooks, you no longer need to constantly check for updates. Instead, we’ll send real-time
updates directly to your system whenever specific events occur, such as changes to an order’s
status. This allows your system to react immediately, whether it’s updating databases,
triggering workflows, or sending notifications, all without manual intervention.
By leveraging webhooks, you can streamline your processes, reduce overhead, and ensure that your
system stays up-to-date with minimal effort. In this section, we’ll walk you through how to
configure and use our webhooks to receive order status updates, so you can take advantage of
this feature for a more efficient and automated experience.
01
Order Status Update :
This web Hook sends updates regarding order status changes to the API endpoint you provide.
The updates are triggered whenever an order transitions through different stages.
You'll need to provide the API endpoint URL where we should send the order status update
data. The webhook will send a POST request with the status update data to this URL.
URL :
The order status update information will be sent to the API endpoint that you provided.
Method :
POST
Content-Type :
application/json
Purpose :
To automatically send updates about order status changes to your system.
Key Points :
Max Failed Attempts Limit: If an update fails 4 times, it will be marked as failed
and will not be retried.
Request Timeout: If a request does not receive a response within 3 seconds, it will be marked as
failed.
Authentication Token: You can provide an authentication token to be
included in the request headers. Share the token and header name with our system
administrator in the following format: "auth-key-name:token"
Data Retention:
Successful requests: Logs will be deleted 3 days after they are sent.
Failed requests: Logs will be deleted 21 days after they are sent.
Request Samples :
Headers: If an authentication token is provided, it will be included in the request headers.
Query Parameters : No parameters
Request Body :
{
"client_name":"محمد", (name of the client)
"client_mobile":"+9647712345678", (client mobile number)
"items_number":"1", (number of items in this order)
"created_at":"2023-08-13 22:12:18", (the date and time of when the order was created)
"city_name":"بغداد", (city name of client)
"region_name":"شارع فلسطین", (region name of the client)
"status_id":"2", (the status id of the order)
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order)
"price":"20000", (the order price including delivery fee)
"location":"market", (the description of the client location)
"issue_notes":"لا یوجد", (a note written by the delivery driver when there is an issue with the order)
"merchant_notes":"لا یوجد", (a note written by the merchant)
"client_mobile2":"+9647712345678", (client second mobile number)
"updated_at":"2024-06-22 11:28:53", (the last date and time the order data was updated)
"city_id":"13", (client city number)
"region_id":"1043", (client region number)
"replacement":"0", (indicate if the order is a replacement or not, 1 for replacement 0 for not)
"type_name":"ملابس", (order goodes type)
"id":"103", (order id)
"has_merchant_fin_record": 0 OR 1, (indicates whether the merchant has requested accounting for the invoice this order is included in, 1 if the merchant has requsted accounting.)
"deliver_confirmed_fin":0 OR 1, (if 1 then the order has been delivered, and the company has received payment from the delivery driver. At this stage, the merchant is eligible to request accounting for this order.)
"delivery_price":"9000", (the delivery fee of this order)
"package_size":"عادي" (the order size)
"merchant_invoice_id":"-1" (the merchant invoice number, if the value is "-1" then this order is not included in a merchant invoice and the merchant can not request accounting for this order.)
}