Orders

As a Seller, you manage orders through list/show/update endpoints, bulk status actions, import/export, and follow-up workflows.

INFO

There is no POST /orders bulk-create endpoint on the REST API. Orders are created from confirmed leads or through dashboard/import flows.

List Orders (All Statuses)

GET/orders/ Bearer Token — view orders

Retrieve a paginated list of orders across all statuses.

Supports the common list parameters (page, per_page, keyword, search_by, match_type, start_at, end_at, date_from, date_to, id, ids).

Parameter	Type	Required	Description
status	string	No	Filter by status key
mobile_status	array	No	Filter by one or more status values
other_status	integer	No	Additional status filter (1–3)
stale_shipped_days	integer	No	Shipped orders older than N days (1–30)
balanced	string	No	yes or no
date_type	string	No	Date column to filter on
product	string	No	Filter by product
city_id	string	No	Filter by city ID
agent_id	string	No	Filter by agent (when permitted)
team_id	string	No	Filter by team (when permitted)
shipping_company_id	string	No	Filter by carrier (when permitted)
creation_type	string	No	lead_based or direct_order (when permitted)
conversion_action	number	No	Conversion action filter (when permitted)

Response

Success (200): standard paginated { data, meta.pagination } envelope.

List Orders by Status

GET/orders/{status} Bearer Token — view orders

Retrieve a paginated list of orders for a specific status tab.

Uses the same query parameters as List Orders (All Statuses). The {status} path segment selects the order status context (same keys as in Order statuses below).

Show Order

GET/orders/{order}/show Bearer Token — view orders

Retrieve a single order by ID.

Response

Success (200):

{
  "data": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "reference": "ORD-00001",
    "full_name": "John Doe",
    "phone": "0612345678",
    "city": "Casablanca",
    "address": "Hay Salam",
    "status": "NEW",
    "products": [],
    "created_at": "2025-01-16T10:00:00Z",
    "updated_at": "2025-01-16T10:00:00Z"
  },
  "meta": {}
}

Not found (404):

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "Resource not found."
  }
}

Update Order

PATCH/orders/{status}/{item} Bearer Token — update orders

Update a single order in the given status context.

Request body: order fields and products[] (same shape as dashboard update). On success the API returns a legacy message payload:

{
  "message": "Order updated successfully"
}

Validation failures may return { "message": "..." } with HTTP 422.

Delete Orders (Bulk)

DELETE/orders/ Bearer Token — delete orders

Bulk delete orders by ID. Deletion is only allowed when policy and business rules permit it.

Request Body:

{
  "ids": [
    "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "01ARZ3NDEKTSV4RRFFQ69G5FAW"
  ]
}

Field	Type	Required	Description	Rules
ids	array	Yes	Order IDs to delete	each ID: string, 1–100 chars
ids.*	string	Yes	Order ID	must exist

Response

Success (200): legacy message envelope (not { data, meta }):

{
  "message": "2 order(s) deleted"
}

WARNING

Only orders the authenticated token is allowed to delete are removed. Orders that fail policy checks are skipped silently.

Bulk Status Actions

All bulk actions below use POST under /orders/ and accept an ids array of order IDs unless noted.

Method	Path	Description
POST	/orders/push-to-shipping-company	Push orders to shipping company
POST	/orders/assign-to-delivery-boy	Assign to delivery agent
POST	/orders/mark-as-shipped	Mark as shipped (ids, date, warehouseId)
POST	/orders/mark-as-shipped-by-scanner	Mark shipped via scanner
POST	/orders/mark-as-returned	Mark as returned
POST	/orders/mark-as-returned-by-scanner	Mark returned via scanner
POST	/orders/mark-as-returned-by-import	Mark returned via import
POST	/orders/mark-as-delivered	Mark as delivered
POST	/orders/mark-as-delivered-by-import	Mark delivered via import
POST	/orders/mark-as-canceled	Cancel orders
POST	/orders/renew	Renew orders
POST	/orders/generate-tracking-labels	Generate tracking labels
POST	/orders/import	Import orders from file
POST	/orders/export/{status?}	Export orders (optional status filter)

Mark as shipped example body:

{
  "ids": ["01ARZ3NDEKTSV4RRFFQ69G5FAV"],
  "date": "2025-01-16",
  "warehouseId": "01ARZ3NDEKTSV4RRFFQ69G5FAW"
}

Most action endpoints return a { "message": "..." } payload on success.

Follow-up & Products

Method	Path	Description
GET	/orders/{order}/follow-up	Get follow-up details
PATCH	/orders/{item}/follow-up	Update follow-up
GET	/orders/{order}/products	List products on an order

---

Order Statuses

Reference values for {status} path segments and filters. There is no GET /order-statuses endpoint.

Status	Description
NEW	Freshly created order
PACKED	Packed and ready for shipping
WAITING_FOR_SHIPPING_COMPANY	Pushed to shipping company, waiting for pickup
SHIPPED	In transit
DELIVERED	Successfully delivered to customer
RETURNED	Returned by customer or courier
CANCELED	Order canceled
CHANGED	Order has been modified
ROLLBACK	Order rolled back to previous state
OUT_OF_STOCK	Product was out of stock

---

Cities

List Cities

GET/cities Bearer Token

Retrieve a paginated list of available cities.

Parameter	Type	Required	Description
per_page	number	No	Results per page

Response

Success (200):

{
  "data": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "name": "Casablanca"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 100,
      "pages": 2
    }
  }
}

Show City

GET/cities/{item}/show Bearer Token

Retrieve a single city by ID.