List Orders

This endpoint allows you to list all orders related to your store.

Tip

Also, the endpoint enables you to filter the orders using a set of optional parameters.

Deprecation Notice

All Apps created after 15th of August, 2024 will not be able to use the expanded query parameter.

Scopes

orders.read - Orders Read Only

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Query Params

keyword

enum<string>

optional

Listing the orders by keywords such as tag_name and shipping_number

Allowed values:

customer.mobilecustomer.nameshipping_numberreference_idtag_name

payment_method

array[string]

optional

Find orders for specific payment method. List of available payment methods can be found here

status

array[string]

optional

Find orders for specific status (array of ID integers). List of statuses can be found here

from_date

string <date>

optional

Find orders created after a specific date.

Example:

2024-01-01

Match pattern:

yyyy-mm-dd

to_date

string <date>

optional

Find orders created before a specific date.

Example:

2024-01-02

Match pattern:

yyyy-mm-dd

country

integer

optional

find orders for specific country. List of countries can be found here

city

string

optional

Find orders for specific city. List of cities can be found here

Example:

jeddah

product

string

optional

Find orders for specific product via its name variable. List of products can be found here

branch

array[string]

optional

Find orders for specific branch (array of integers). List of branches can be found here

tags

array[string]

optional

Find orders for specific tags (array of ID integers). List of tags can be found here

expanded

boolean

deprecated

Get full details of orders same as order details response by setting the value to true.

page

integer

optional

The Pagination page number

reference_id

integer

optional

This is the ID that appears to the store owner

coupon

string

optional

Discount code, extracted from discount.code

customer_id

number

optional

Customer ID

shipping_app_id

array[string]

optional

Number array of Shipping Application IDs

source

array[string]

optional

Order Source

sort_by

enum<string>

optional

Sort the retrieved orders based on one attribute from the enum values. For example, if we need to sort the order by the id in ascending or descending order. we will concatenate either asc or desc with one of the enum values; in this case, we will use id-asc or id-desc.

Allowed values:

idtotalupdated_atcreated_at

accounting_services

enum<string>

optional

To filter the orders that did not get sent to the accounting services.

Allowed values:

qoyoddaftrazoho_books

unread

boolean

optional

FInd the unread orders that merchant did not open yet.

assign_employee

array[string]

optional

Find the orders that are assigned to one or more employees. List of employees can be found here

selling_channel

array[string]

optional

The order-selling channel which can be one of the allowed enum values

Allowed values:

mobilemobile-appdesktopaffiliatemahly-app

created_by

integer

optional

Employee ID who created the order(s). List of employees can be found here

Responses

🟢200Success

application/json

Body

status

number

optional

Response status code, a numeric or alphanumeric identifier used to convey the outcome or status of a request, operation, or transaction in various systems and applications, typically indicating whether the action was successful, encountered an error, or resulted in a specific condition.

success

boolean

optional

Response flag, boolean indicator used to signal a particular condition or state in the response of a system or application, often representing the presence or absence of certain conditions or outcomes.

data

array[object (ListOrders) {15}]

optional

Detailed structure of the List Order model object showing its fields and data types.

number

required

A unique alphanumeric code or identifier assigned to a specific order.

reference_id

number

required

Order refrence ID, a specific alphanumeric code or identifier associated with an order, used for easy and precise reference and tracking of that particular order, this reference ID appears to customers in the store.

total

object

required

The cumulative monetary amount representing the total expense incurred for all the items in the order.

date

object (Date)

required

Date of the order.

status

object (NewOrderStatus)

required

Status of the order.

draft

boolean

required

Whether or not the order is a draft or no.

read

boolean

required

Whether or not the order is read by the merchant or not

can_cancel

boolean

required

Whether or not the order is allowed to be cancelled by store customers.
True value should be set if the order status is in under review and in progress, as according to the store settings.

can_reorder

boolean

required

Whether or not the order allowed to be re-order by customers.

payment_method

string

required

The order's payment method

is_pending_payment

boolean

required

Whether or not the order is waiting to be paid or the order status is payment_pending.

pending_payment_ends_at

string

required

The time untill the payment has to be made by the cusotmer

features

object

required

Order features details.

items

array [object {3}]

required

Order items (products)

customer

object (Customer)

required

Customer details.

pagination

object (Pagination)

optional

For a better response behavior as well as maintain the best security level, All retrieving API endpoints use a mechanism to retrieve data in chunks called pagination. Pagination working by return only a specific number of records in each response, and through passing the page number you can navigate the different pages.

count

number

required

Number of returned results.

total

number

required

Number of all results.

perPage

number

required

Number of results per page.

<= 65

currentPage

number

required

Number of current page.

totalPages

number

required

Number of total pages.

links

object

required

Array of linkes to next and previous pages.

Example

{
    "status": 200,
    "success": true,
    "data": [
        {
            "id": 1017120475,
            "reference_id": 40497536,
            "total": {
                "amount": 55,
                "currency": "SAR"
            },
            "exchange_rate": {
                "base_currency": "SAR",
                "exchange_currency": "USD",
                "rate": 0.266592
            },
            "date": {
                "date": "2022-06-16 14:48:20.000000",
                "timezone_type": 3,
                "timezone": "Asia/Riyadh"
            },
            "status": {
                "id": 566146469,
                "name": "بإنتظار المراجعة",
                "slug": "under_review",
                "customized": {
                    "id": 986688842,
                    "name": "بإنتظار المراجعة"
                }
            },
            "can_cancel": false,
            "can_reorder": true,
            "payment_method": "bank",
            "is_pending_payment": false,
            "pending_payment_ends_at": 0,
            "features": {
                "digitalable": true,
                "shippable": true
            },
            "items": [
                {
                    "name": "تي شيرت بلاك",
                    "quantity": 1,
                    "thumbnail": "https://salla-dev.s3.eu-central-1.amazonaws.com/Mvyk/c151972a-c2d1-4a4d-b374-b46fd0bca79e-500x333.33333333333-WfHaI7WVXTosOlksBhesYbWlxhMFf9fJVDK6JlJj.jpg"
                }
            ]
        },
        {
            "id": 1013578136,
            "reference_id": 40497469,
            "total": {
                "amount": 0,
                "currency": "SAR"
            },
            "date": {
                "date": "2022-06-16 14:46:42.000000",
                "timezone_type": 3,
                "timezone": "Asia/Riyadh"
            },
            "status": {
                "id": 525144736,
                "name": "ملغي",
                "slug": "canceled",
                "customized": {
                    "id": 1718741844,
                    "name": "ملغي"
                }
            },
            "can_cancel": false,
            "can_reorder": true,
            "is_pending_payment": true,
            "pending_payment_ends_at": 0,
            "items": [
                {
                    "name": "Custom Shirt",
                    "quantity": 3
                }
            ]
        }
    ],
    "pagination": {
        "count": 2,
        "total": 2,
        "perPage": 15,
        "currentPage": 1,
        "totalPages": 1,
        "links": {}
    }
}

🟠401Unauthorized

Request

Request samples

Responses