An interactive console for the merchant API: pick an endpoint, fill in the data, get ready-made code in four languages and see the documented response instantly.
A list of cities in the format [{id: 1, city_name: 'name'}].
Request samples (documented)
Query Parameters: No parameters
Request Body: No body
Response samples (documented)
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)
}
]
}
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 samples (documented)
Request Body: No body
Query Parameters
"city_id":"ID"
Response samples (documented)
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)
}
]
}
A list of available package sizes in the format [{id: 1,size: 'name'}].
Request samples (documented)
Query Parameters: No parameters
Request Body: No body
Response samples (documented)
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.
Parameters
Name
Type
In
Required
Description
client_name
string
body
Required
Name of the client.
client_mobile
string
body
Required
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
client_mobile2
string
body
Optional
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
city_id
int
body
Required
ID of the client’s city (from the Cities API).
region_id
int
body
Required
ID of the client’s region (from the Regions API).
location
string
body
Required
Description of the client’s location.
type_name
string
body
Required
Description of the type of goods in the order.
items_number
int
body
Required
Number of items in the order.
price
int
body
Required
Total price of the order, including delivery.
package_size
int
body
Required
The size of the order package (from the Package Sizes API).
merchant_notes
string
body
Optional
A general note or instruction about the order.
replacement
0 or 1
body
Required
Specifies if the order is a replacement.
company_order_id
string
body
Optional*
The order ID from the external company's system. This parameter allows you to track which order ID in our system corresponds to the order ID in your system.
*Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined. If you don't have a registered prefix and would like to add your own, please check this section.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name":"محمد" (the name of the client),
"client_mobile":"+9647704723599" (client phone number),
"client_mobile2":"+9647704723599"(client second phone number),
"city_id":"5" (the city id of the client),
"region_id":"2" (the region id of the client),
"merchant_mobile":"07704723599" (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),
"city_fees":0 (set automatically by the system),
"merchant_price":21000 (the order price without delivery fee),
"type_name":"ملابس" (orders goods type),
"merchant_created_at":"2024-08-10 16:30:10" (set automatically by the system),
"merchant_notes":"عدم فتح القطعة" (set by the merchant),
"qr_id": 38799216 (the QR id of this order, thi will be the main identifier of the order),
"pickup_id": "1" (the pickup drier assigned to this order),
"pickup_created_at": "2024-08-10 04:30:10pm" (set automatically by the system),
"id": 38799216 (set automatically by the system),
"company_order_id":"123", (The order ID from the company's system.),
"qr_link": "https://agg-iq.net/operation/merchant/print-single-tcpdf?id=orderQr&token=merchantToken" (the receipt PDF link)
}
]
}
In scenarios where the order info needs to be updated and the order is still at the merchant possession, this endpoint provides the ability to do so:
Parameters
Name
Type
In
Required
Description
qr_id
string
body
Required
Order number
client_name
string
body
Required
Name of the client.
client_mobile
string
body
Required
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
client_mobile2
string
body
Optional
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
city_id
int
body
Required
ID of the client’s city (from the Cities API).
region_id
int
body
Required
ID of the client’s region (from the Regions API).
location
string
body
Required
Description of the client’s location.
type_name
string
body
Required
Description of the type of goods in the order.
items_number
int
body
Required
Number of items in the order.
price
int
body
Required
Total price of the order, including delivery.
package_size
int
body
Required
The size of the order package (from the Package Sizes API).
merchant_notes
string
body
Optional
A general note or instruction about the order.
replacement
0 or 1
body
Required
Specifies if the order is a replacement.
company_order_id
string
body
Optional*
The order ID from the external company's system. This parameter allows you to track which order ID in our system corresponds to the order ID in your system.
*Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined. If you don't have a registered prefix and would like to add your own, please check this section.
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.
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). Use Retrieve Active Orders for a lighter list that excludes old completed or returned orders.
Alternatively you can retrieve orders by their ids using this API.
Parameters
Name
Type
In
Required
Description
token
string
query
Requiredfrom the URL example
The login token.
Response
A list of orders related to the merchant.
Request samples (documented)
Request Body: no body
Query Parameters
"token":"token"
Response samples (documented)
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"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)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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)
"company_order_id": "123", (The order ID from the company's system.),
"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.)
}
]
}
Returns the merchant's currently relevant orders. Unlike merchant-orders in Retrieve Orders, which returns the full order history, this endpoint excludes stale final-state orders — delivered orders and orders returned to the merchant — that have not been updated in the last month.
All in-progress orders are always included, and recently completed or returned orders (updated within the last month) are also included.
Parameters
Name
Type
In
Required
Description
token
string
query
Requiredfrom the URL example
The login token.
Response
A filtered list of the merchant's active and recently updated orders.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"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)
"send_to_store": (0 OR 1 OR 2),
"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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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)
"company_order_id": "123", (The order ID from the company's system.),
"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.)
}
]
}
Retrieve Specific Orders by IDs (batch) Unlike the "Retrieve Orders" endpoint with returned all the orders, this endpoint allows you to inquire about a specific id(s) by specifying them into a comma-separated string of order IDs to retrieved. The maximum number of ids to be retrieved is 25.
Parameters
Name
Type
In
Required
Description
ids
string
body
Required
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.
token
string
query
Requiredfrom the URL example
The login token.
Response
Details of the selected orders.
Request samples (documented)
Query Parameters
"token":"token"
Request Body
"ids":"11,23,75,29" (string of comma separated values, max 25 ids)
Response samples (documented)
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"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)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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)
"company_order_id": "123", (The order ID from the company's system.),
"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.)
}
]
}
Returns the chronological snapshots of a single merchant order from the order log. Each item in the list is a saved copy of the order at a given point in time (oldest first).
Unlike Retrieve Orders, which returns the current state of many orders, this endpoint is for one order identified by qr_id. Archived orders are included. If the order has no log entries, an empty list is returned.
Parameters
Name
Type
In
Required
Description
token
string
query
Required
The merchant login token.
qr_id
number
query
Required
The order ID to retrieve the story for. The order must belong to the authenticated merchant.
Response
A chronological list of order-log snapshots for the requested order.
Request samples (documented)
Request Body: no body
Query Parameters
"token":"token"
"qr_id":"103"
Response samples (documented)
Same order fields as Retrieve Orders. updated_at is the time of that snapshot, not the current order update time.
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "تم", // Success message
"data": [
{
"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 at this snapshot)
"send_to_store": (0 OR 1 OR 2),
"deliver_done":(0 OR 1), (if 1 then the order has been delivered)
"status":"تم استلام الطلب من قبل المندوب", (the status text of the order at this snapshot)
"price":"20000", (the order price including delivery fee)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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 date and time of this snapshot)
"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)
"company_order_id": "123", (The order ID from the company's system.),
"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.)
}
]
}
In some cases, orders may encounter issues during delivery. These orders are handled by our team, but you can retrieve a list of them using this API. If you prefer to resolve the issues yourself, you can use the Resolve Order API.
Parameters
Name
Type
In
Required
Description
token
string
query
Requiredfrom the URL example
The login token.
Response
Returns all orders that have a reported issue.
Request samples (documented)
Request Body: No body
Query Parameters
"token":"merchant-token"
Response samples (documented)
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": [
{
"client_name": "cutomer name",
"client_mobile": "+9647700000000",
"items_number": "2",
"created_at": "2025-12-30 23:59:59",
"city_name": "بغداد",
"region_name": "شارع فلسطين",
"status": "مغلق",
"package_size": "متوسط",
"status_id": "35",
"price": "15000",
"old_price": "18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"location": "location discription",
"issue_notes": "لا يوجد",
"deliver_done": "0",
"merchant_notes": "merhcant note",
"client_mobile2": "+9647700000000",
"updated_at": "2025-12-30 23:59:59",
"city_id": "1",
"region_id": "1",
"replacement": "1",
"type_name": "ملابس",
"id": "102",
"company_order_id": "AGG_12345",
"has_merchant_fin_record": "0",
"deliver_confirmed_fin": "0",
"delivery_price": "6750",
"merchant_invoice_id": "-1"
}
]
}
Your merchants can now resolve order issues using the following API. This API allows them to provide an order ID and the new customer phone number, and it will reset the order status to 'On its way to the client'.
Note: The issue can only be resolved once the order is with the delivery driver. If the order is returned to the warehouse, it cannot be resolved.
Instead of returning the order to the original merchant, you can use this API to resend the order to a new or the same client. This endpoint functions similarly to the Edit Order API, with the key difference being that it only supports orders currently in specific statuses. Allowed Status IDs:
12 – In province warehouse
13 – In Baghdad warehouse
15 – Returned to merchant
44 – Sent to sorting center for resending
Ensure the order is in one of the above statuses before attempting to use this API.
Parameters
Name
Type
In
Required
Description
qr_id
string
body
Required
Order number
client_name
string
body
Required
Name of the client.
client_mobile
string
body
Required
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
client_mobile2
string
body
Optional
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
city_id
int
body
Required
ID of the client’s city (from the Cities API).
region_id
int
body
Required
ID of the client’s region (from the Regions API).
location
string
body
Required
Description of the client’s location.
type_name
string
body
Required
Description of the type of goods in the order.
items_number
int
body
Required
Number of items in the order.
price
int
body
Required
Total price of the order, including delivery.
package_size
int
body
Required
The size of the order package (from the Package Sizes API).
merchant_notes
string
body
Optional
A general note or instruction about the order.
replacement
0 or 1
body
Required
Specifies if the order is a replacement.
company_order_id
string
body
Optional*
The order ID from the external company's system. This parameter allows you to track which order ID in our system corresponds to the order ID in your system.
*Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined. If you don't have a registered prefix and would like to add your own, please check this section.
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 samples (documented)
Request Body: No body
Query Parameters
"token":"token"
"invoice_id":"ID"
Response samples (documented)
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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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.
Parameters
Name
Type
In
Required
Description
invoice_id
string
query
Not stated
The ID of the invoice.
token
string
query
Requiredfrom the URL example
The login token.
Response
Marks the invoice as received.
Request samples (documented)
Request Body: No body
Query Parameters
"token":"token"
"invoice_id":"ID"
Response samples (documented)
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
}
This API allows the merchant to resend a returning order with a new customer phone number. The order status must be Send to Returns Warehouse (status ID = 23) AND the send_to_store = 0 to be eligible for resending. Only the customer phone number can be changed — the destination address must remain the same.
While the previous endpoints were designed to handle the orders on the merchant level, this set of API endpoints is designed to provided merchant(s) management i.e., to enable the aggregator to handle his merchant(s).
01Aggre APIs
Login Endpoint
POSThttps://agg-iq.net/operation/v1/aggre/login
Content-Typemultipart/form-data
Purpose: To authenticate the comapny account and receive a token.
All aggre APIs requier an authentication token to be included in the request parameters, username and password are submitted to the endpoint, aggregator token is returned.
Parameters
Name
Type
In
Required
Description
username
string
body
Required
The company's account username.
password
string
body
Required
The company's account password.
Response
On success: Returns a token to be used for future API calls.
On failure: Provides an error code and message.
Login token expires after 15 days.
Login credentials for the company are the same for the company dashboard (https://agg-iq.net/operation/city_office).
Request samples (documented)
Query Parameters: No parameters
Request Body
"username":"username"
"Password":"password"
Response samples (documented)
Response body on success
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "ok", // Success message
"data": {
"token": "aggre-token", // the login token (string)
"user-data": { // company information
"name": "company name",
"username": "company username",
"mobile": "company mobile"
}
}
}
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "Done Successfully.", // Success message
"data": {
"merchant_id": 123 // the created merchant ID (int)
"token": "merchantToken" // the created merchant token (string)
}
}
In certain situations, you may need to quickly create multiple orders for different merchants. With this API, you can send a JSON array string containing the orders data, and you'll receive a response that provides success and error messages for each individual order.
Please provide a JSON string with the order data. Note that each request can include a maximum of 30 orders, so make sure not to exceed this limit. With the current limits, you can create up to 900 orders every 30 seconds — this is based on a rate limit of 30 requests per 30 seconds, with each request allowing up to 30 orders. The order data should contain the following keys and values.
data[].client_name
string
data[ ]
Required
Name of the client.
data[].client_mobile
string
data[ ]
Required
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
data[].client_mobile2
string
data[ ]
Required
The client’s mobile number. Must be in this format “+9647000000000“, iraq country code followed by 10 numbers
data[].city_id
int
data[ ]
Required
ID of the client’s city (from the Cities API).
data[].region_id
int
data[ ]
Required
ID of the client’s region (from the Regions API).
data[].location
string
data[ ]
Required
Description of the client’s location.
data[].type_name
string
data[ ]
Required
Description of the type of goods in the order.
data[].items_number
int
data[ ]
Required
Number of items in the order.
data[].price
int
data[ ]
Required
Total price of the order, including delivery.
data[].package_size
int
data[ ]
Required
The size of the order package (from the Package Sizes API).
data[].merchant_notes
string
data[ ]
Required
A general note or instruction about the order.
data[].replacement
0 or 1
data[ ]
Required
Specifies if the order is a replacement.
data[].merchant_id
int
data[ ]
Required
Merchant ID associated with this order.
data[].company_order_id
string
data[ ]
Optional*
The order ID from the external company's system. This parameter allows you to track which order ID in our system corresponds to the order ID in your system.
*Note: This parameter is [Required] if a Company Order ID prefix is activated for the company. The provided Order ID must begin with the registered prefix and must include the full prefix as defined. If you don't have a registered prefix and would like to add your own, please check this section.
data[].metadata
string
data[ ]
Optional
The metadata includes any information that helps you identify the order more easily. It is not part of the order creation data, but it will be returned in the response as the same string.
token
string
query
Requiredfrom the URL example
The login token.
Response
On success: There will be two arrays: one containing all the successfully created orders and the other with the failed orders. Each failed order will include a "failed" variable that holds the error message explaining the failure.
{
"status": true,
"errNum": "S000", // On success "S000" will be returned
"msg": "Done Successfully.", // Success message
"data": {
"succeed": [], // an array with all the successfuly created orders
"failed": [] // an array with all the filed orders with an error message for each order
}
}
To print stickers for your orders, you can send the order ID(s) to this endpoint, and it will generate a PDF file containing the stickers for the order(s) and return a link to that file.
Parameters
Name
Type
In
Required
Description
token
string
query
Requiredfrom the URL example
The login token.
orders-ids
-
query
Not statedfrom the URL example
Response
A link to printed orders file
Limits
You can submit a maximum of 100 orders per request.
Orders Criteria
Orders should have a status of 1 (new order).
Order must belong to a merchant who is associated with your company.
Request samples (documented)
Request Body: No body
Query Parameters
"token":"aggre-token",
"orders-ids":"1,2,3" // comma separated values of orders IDs we want to print
POSTThe order status update information will be sent to the API endpoint that you provided.
Content-Typeapplication/json
Purpose: To automatically send updates about order status changes to your system.
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.
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.
Additional Info
Price Change: In some cases, the order price may change while the status remains unchanged. This indicates the full order is being delivered at a new price (not due to a return). A price change can be detected when the status is "With delivery driver" (3) and the old price is not -1.
Request samples (documented)
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)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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)
"company_order_id": "123", (The order ID from the company's system.)
"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.)
}
Guides
Guides
Using Company Order ID in Our System
You can now use your own company-specific order IDs within our system, subject to certain conditions. This feature enables better alignment between your internal systems and our order processing workflow. It also allows your company to use its own order manifest (order information sticker) when delivering orders.
Requirements for Order ID Prefix: To enable this feature, you must first register a unique order ID prefix that adheres to the following rules:
The prefix must consist of at least three letters and be unique in our system.
The prefix must not contain any special characters except for an underscore (_).
The prefix must not contain any spaces.
The prefix letters must be capital letters.
The prefix must not contain any Numbers.
The prefix must not contain any Arabic letters.
examples for the accepted format: ABC1000, ABC_1000.
How to Register Your Order ID Prefix: To register your order ID prefix:
Contact our customer service team.
Provide the prefix you want to use.
Once approved and registered, the prefix will be associated with your account.
After Registration: Once your prefix is registered, the Company Order ID field becomes required in the order creation APIs.
All submitted Company Order IDs must begin with your registered prefix.
This setup ensures proper tracking and uniqueness of orders from different clients.
Order statuses
The order journey, as documented
Every status here is named in the documentation, together with the endpoints that act on it. The order is illustrative; the full list for your account comes from Get Order Statuses, and every change reaches you through the webhook.
1The order is in transit to the Baghdad warehouse.
2The order has been received at the Baghdad warehouse.
Where does each status come from?
1status must be equal to 1 (new order)documentation text
2تم استلام الطلب من قبل المندوبresponse sample
3"With delivery driver" (3)documentation text
1212 – In province warehousedocumentation text
1313 – In Baghdad warehousedocumentation text
1515 – Returned to merchantdocumentation text
23status_id = 23 (Returning to Returned Warehouse)documentation text
4444 – Sent to sorting center for resendingdocumentation text
Webhooks
Stop polling - let status changes come to you
On every order status change the system sends a JSON POST request to the URL you provide. Its key rules, as documented:
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.
{
"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)
"send_to_store": (0 OR 1 OR 2),
This flag is relevant when status_id = 23 (Returning to Returned Warehouse). It indicates the current stage of the return process:
0 – The order is still in the city warehouse.
1 – The order is in transit to the Baghdad warehouse.
2 – The order has been received at the Baghdad warehouse.
This flag is primarily used in the Resolve Returned Order API.
"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)
"old_price":"18000" OR -1, (the OLD order price including delivery fee, if it is set to -1 then the price did not change)
"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)
"company_order_id": "123", (The order ID from the company's system.)
"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.)
}
The documentation's introduction to webhooks
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.
Changelog
What is new in the API
The changelog as published by the platform operator, newest first.
V1.11.4
Added Retrieve Order Story API
A new endpoint — Retrieve Order Story — returns the chronological snapshots of a single merchant order from the order log.
Use this API when you need the full status and data history of one order, rather than the current order list returned by Retrieve Orders.
V1.11.3
Added Retrieve Active Orders API
A new endpoint — Retrieve Active Orders — returns the merchant's currently relevant orders while excluding stale completed or returned orders that have not been updated in the last month.
Use this API when you need an up-to-date order list without loading the full order history returned by Retrieve Orders.
A new API enabling merchants to resend orders once they have been returned to the designated returns warehouse. check the new api here
V1.9.0
Added Request returned order API
Added new api that allows you to request returned orders on behalf of the merchant. check the new api here
Added get orders with issue API
Added a new api that allows you to get orders with issue on behalf of the merchant. check the new api here
Added resend returnd order API
Added a new api that allows you to resend a returned order to a new or the same customer. check the new api here
V1.8.0
Added company order ID prefix
Added support for company-specific order ID prefixes to improve system integration and order tracking. check the registrations process here
V1.7.0
Added Receive Returned Order API
Now you can receive returned orders on behalf of the merchant using the new API. check it out
Added Resolve Order Issue API
Your merchants may want to resolve order issues on their own. With this new API, you can enable them to do so. check it out
V1.6.1
Added "deliver_done" flag to retreive orders APIs and webhook
We’ve added a new deliver_done flag to the following APIs and webhook 'Retrieve Orders' API, 'Retrieve Orders by IDs' API and the webhook. This flag enables you to filter orders by their delivery status.
Added additional info to the webhook
We’ve updated the webhook by adding new flags. The following flags have been introduced 'merchant_invoice_id', 'deliver_confirmed_fin' and 'has_merchant_fin_record' flags have been added to the webhook. For more details, please refer to the Flags in the 'Request Sample' in the webhook section.
V1.6
Added Creating Multiple Orders API
We’ve introduced a powerful new API that allows you to create multiple orders in a single, streamlined request. This update simplifies the order creation process, enhancing efficiency and saving valuable time when managing large volumes of orders. check it out.
V1.5
Added Webhooks
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.
V1.4
Added Company Order Id
In the 'Create Order', 'Edit Order', 'Retrieve All Orders', and 'Retrieve Orders by IDs' APIs, a 'Company Order ID' field has been added. This allows you to track which order ID in our system corresponds to the order ID in your system.
V1.3
Changed create order API name
Renamed the "Create Order" API to "Order Creation". Note: The functionality of the API remains unchanged.
Added clearer explanations for each endpoint
- Added clearer explanations for each endpoint, providing more detailed information on their usage and expected responses. - Clarified the authentication requirements for the Invoice API to ensure proper integration.
Added Delete Order API
With this API, you can delete specific orders.
V1.2
Added Print order and get printed orders APIs
This new APIs allows you to print orders and retrieve the printed orders as a PDF file.
V1.1
Edit an Order
With this API, you can edit specific information about an order, such as the customer's name, phone number, and address.
Speed improvement
Over all endpoint optimization and lower latency
About this documentation
The technical content is taken word for word from the documentation of the operations platform the company runs on, organised here to be easier to use. If anything differs, the original source is the reference.
We’re thrilled to have you here. Our API is designed to provide seamless integration and powerful functionality to help you achieve your goals. Whether you’re building a new application, integrating an existing one, or just exploring what our API can do, you’ll find everything you need right here.
To ensure fair usage and optimal performance of our API, we have implemented a rate limit of 200 requests per 30 seconds for each user. This limit is enforced across all endpoints.
You need a merchant account to start
Login credentials (and so the token) come with a merchant account. Request yours, and contact us for any help with the integration.
