Orders

As a Seller, you can create, view, update, and delete orders via the API.

Bulk Create Orders

POST/orders Bearer Token — create orders

Create up to 100 orders in a single request (sync for ≤10). Each order can contain up to 10 products.

Request Body:

{
  "data": [
    {
      "full_name": "John Doe",
      "phone": "0612345678",
      "city": "Casablanca",
      "address": "Hay Salam",
      "note": "Call before delivery",
      "second_phone": "0712345678",
      "products": [
        {
          "sku": "TSHIRT-RED-M",
          "quantity": 2,
          "price": 120
        }
      ]
    }
  ]
}

Field	Type	Required	Description	Rules
data	array	Yes	Array of order objects	max 100 items
data.*.full_name	string	Yes	Customer name	min 1, max 100 characters
data.*.phone	string	Yes	Primary phone	min 1, max 100 characters
data.*.city	string	Yes	City name	must be a valid city
data.*.address	string	Yes	Delivery address	min 1, max 100 characters
data.*.products	array	Yes	Product items	min 1, max 10 items
data.*.products.*.sku	string	Yes	Product SKU	min 1, max 100 characters, must exist in your account
data.*.products.*.quantity	number	Yes	Quantity	min 1, max 9999
data.*.products.*.price	number	Yes	Unit price	min 1, max 9999
data.*.note	string	No	Notes	max 500 characters
data.*.second_phone	string	No	Secondary phone	max 100 characters

Response

Sync success (201):

{
  "data": {
    "created_refs": ["WDKJHGFHJ"],
    "failed_count": 0
  },
  "meta": {
    "mode": "sync",
    "total": 1
  }
}

Async queued (202):

{
  "data": {
    "batch_id": "batch_550e8400-e29b-41d4-a716-446655440000",
    "queued": true
  },
  "meta": {
    "mode": "async",
    "total": 25
  }
}

Validation failure (422):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "fields": {
      "data.0.city": ["The city field is required."],
      "data.1.products.0.sku": ["The selected SKU does not exist in your account."]
    }
  }
}

List Orders

GET/orders Bearer Token — view orders

Retrieve a paginated list of your orders.

Parameter	Type	Required	Description
per_page	number	No	Results per page
status	string	No	Filter by status
search	string	No	Search by reference, name, or phone

Response

Success (200):

{
  "data": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "reference": "ORD-00001",
      "full_name": "John Doe",
      "phone": "0612345678",
      "city": "Casablanca",
      "address": "Hay Salam",
      "status": "NEW",
      "note": "Call before delivery",
      "products": [
        {
          "sku": "TSHIRT-RED-M",
          "name": "T-Shirt Red M",
          "quantity": 2,
          "price": 120
        }
      ],
      "created_at": "2025-01-16T10:00:00Z",
      "updated_at": "2025-01-16T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 320,
      "pages": 7
    }
  }
}

Show Order

GET/orders/{id}/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",
    "second_phone": "0712345678",
    "city": "Casablanca",
    "address": "Hay Salam",
    "status": "NEW",
    "note": "Call before delivery",
    "products": [
      {
        "sku": "TSHIRT-RED-M",
        "name": "T-Shirt Red M",
        "quantity": 2,
        "price": 120
      }
    ],
    "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 Orders (Bulk)

PUT/orders Bearer Token — update orders

Bulk update orders. Each item must include the order reference and the new status.

Request Body:

{
  "data": [
    {
      "reference": "ORD-00001",
      "status": "PACKED"
    }
  ]
}

Field	Type	Required	Description	Rules
data	array	Yes	Array of order update objects	max 50 items
data.*.reference	string	Yes	Order reference	min 1, max 100 characters
data.*.status	string	Yes	New status	must be a valid order status

Response

Success (200):

{
  "data": {
    "updated": 1,
    "failed": 0
  },
  "meta": {}
}

Validation error (422):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "fields": {
      "data.0.status": ["The selected status is invalid."]
    }
  }
}

Delete Orders (Bulk)

DELETE/orders Bearer Token — delete orders

Bulk delete orders by ID. Deletion is only allowed when the system permits it based on business conditions (e.g., order status).

Request Body:

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

Field	Type	Required	Description	Rules
ids	array	Yes	Array of order IDs	max 100 items
ids.*	string	Yes	Order ID	must exist

Response

Success (200):

{
  "data": {
    "deleted": 2
  },
  "meta": {}
}

Forbidden (403):

{
  "error": {
    "code": "HTTP_ERROR",
    "message": "This action is unauthorized."
  }
}

WARNING

Orders can only be deleted when system conditions allow it, depending on the current order status and business rules.

---

Order Statuses

GET/order-statuses Bearer Token

List all available order statuses.

Response

Success (200):

{
  "data": [
    {
      "key": "NEW",
      "label": "New"
    },
    {
      "key": "PACKED",
      "label": "Packed"
    },
    {
      "key": "WAITING_FOR_SHIPPING_COMPANY",
      "label": "Waiting for Shipping Company"
    },
    {
      "key": "SHIPPED",
      "label": "Shipped"
    },
    {
      "key": "DELIVERED",
      "label": "Delivered"
    },
    {
      "key": "RETURNED",
      "label": "Returned"
    },
    {
      "key": "CANCELED",
      "label": "Canceled"
    },
    {
      "key": "CHANGED",
      "label": "Changed"
    },
    {
      "key": "ROLLBACK",
      "label": "Rollback"
    },
    {
      "key": "OUT_OF_STOCK",
      "label": "Out of Stock"
    }
  ],
  "meta": {}
}

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

---

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"
    },
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "name": "Rabat"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 100,
      "pages": 2
    }
  }
}