List orders

GET

/orders

const url = 'https://sandbox.partners.loops.sa/v1/orders?location_id=loc_2Xf9K&status=placed&limit=50';
const options = {
  method: 'GET',
  headers: {'Loops-Merchant-Id': 'mer_7Hq2Lw8Z', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://sandbox.partners.loops.sa/v1/orders?location_id=loc_2Xf9K&status=placed&limit=50' \
  --header 'Authorization: Bearer <token>' \
  --header 'Loops-Merchant-Id: mer_7Hq2Lw8Z'

Orders from all channels at the locations you can access, newest update first. For incremental sync, pass the updated_at of the last order you processed as updated_since.

Authorizations

bearerAuth
orders:read

Parameters

Header Parameters

Loops-Merchant-Id

string

The merchant you are acting for (mer_…). Required for platform applications; optional for direct integrations, which have a single merchant.

Query Parameters

location_id

string

Only orders for this location.

channel

string

Only orders from this channel (an ID from GET /channels).

status

Channel-neutral order status.

string

Allowed values: placed accepted preparing ready picked_up delivered rejected cancelled

Only orders in this status.

updated_since

string format: date-time

Only orders updated at or after this time (ISO 8601, UTC).

created_from

string format: date-time

Only orders created at or after this time.

created_to

string format: date-time

Only orders created before this time.

limit

integer

default: 50 >= 1 <= 100

Page size, 1–100.

cursor

string

The next_cursor from the previous page.

Responses

200

A page of orders.

application/json

object

data

required

Array<object>

object

required

string

version

required

Increases on every change. Use it to discard stale updates.

integer

merchant_id

required

string

location_id

required

string

channel

required

Channel ID from GET /channels.

string

channel_connection_id

string

channel_ref

required

The order number shown on the channel, for staff and support.

string

type

required

string

Allowed values: delivery pickup dine_in

status

required

Channel-neutral order status.

string

Allowed values: placed accepted preparing ready picked_up delivered rejected cancelled

status_history

Array<object>

object

status

required

Channel-neutral order status.

string

Allowed values: placed accepted preparing ready picked_up delivered rejected cancelled

required

string format: date-time

scheduled_for

string | null format: date-time

items

required

Array<object>

object

name

required

Text in the languages the merchant provided.

object

string | null

sku

string | null

quantity

required

integer

unit_price

required

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

modifiers

Array<object>

object

name

Text in the languages the merchant provided.

object

string | null

quantity

integer

unit_price

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

notes

string | null

totals

required

object

subtotal

required

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

discount

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

delivery_fee

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

tax

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

total

required

An amount in minor units (halalas for SAR).

object

amount

required

integer

currency

required

ISO 4217 code.

string

payment

object

method

string

Allowed values: online cash card_on_delivery

paid

boolean

notes

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

extensions

Channel-specific fields, keyed by channel ID. Safe to ignore.

object

key

additional properties

any

next_cursor

required

Pass as cursor to get the next page; null on the last page.

string | null

Example

{
  "data": [
    {
      "id": "ord_01J9QW3T8M",
      "version": 3,
      "channel_ref": "CH-88213",
      "type": "delivery",
      "status": "placed",
      "status_history": [
        {
          "status": "placed"
        }
      ],
      "items": [
        {
          "sku": "CB-01",
          "quantity": 2,
          "unit_price": {
            "amount": 4550,
            "currency": "SAR"
          },
          "modifiers": [
            {
              "unit_price": {
                "amount": 4550,
                "currency": "SAR"
              }
            }
          ]
        }
      ],
      "totals": {
        "subtotal": {
          "amount": 4550,
          "currency": "SAR"
        },
        "discount": {
          "amount": 4550,
          "currency": "SAR"
        },
        "delivery_fee": {
          "amount": 4550,
          "currency": "SAR"
        },
        "tax": {
          "amount": 4550,
          "currency": "SAR"
        },
        "total": {
          "amount": 4550,
          "currency": "SAR"
        }
      },
      "payment": {
        "method": "online"
      }
    }
  ]
}

400

The request is invalid.

application/problem+json

RFC 9457 Problem Details with a stable code.

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

Stable machine-readable error code. Switch on this, not on title.

string

Allowed values: invalid_request merchant_required unauthorized insufficient_scope scope_not_granted connection_not_active application_suspended channel_not_permitted not_found merchant_not_found rate_limited upstream_unavailable

detail

string

request_id

required

string

errors

Field errors, for invalid_request.

Array<object>

object

field

string

message

string

Example

{
  "type": "https://docs.partners.loops.sa/errors/scope_not_granted",
  "title": "Scope not granted",
  "status": 403,
  "code": "invalid_request",
  "detail": "The merchant has not granted orders:read to this application.",
  "request_id": "req_01J9X7P2QK"
}

401

The access token is missing, expired or invalid.

application/problem+json

RFC 9457 Problem Details with a stable code.

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

Stable machine-readable error code. Switch on this, not on title.

string

detail

string

request_id

required

string

errors

Field errors, for invalid_request.

Array<object>

object

field

string

message

string

Example

{
  "type": "https://docs.partners.loops.sa/errors/scope_not_granted",
  "title": "Scope not granted",
  "status": 403,
  "code": "invalid_request",
  "detail": "The merchant has not granted orders:read to this application.",
  "request_id": "req_01J9X7P2QK"
}

403

Not allowed: the scope isn’t approved or granted, the connection is not active, or your application is suspended. See code.

application/problem+json

RFC 9457 Problem Details with a stable code.

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

Stable machine-readable error code. Switch on this, not on title.

string

detail

string

request_id

required

string

errors

Field errors, for invalid_request.

Array<object>

object

field

string

message

string

Example

{
  "type": "https://docs.partners.loops.sa/errors/scope_not_granted",
  "title": "Scope not granted",
  "status": 403,
  "code": "invalid_request",
  "detail": "The merchant has not granted orders:read to this application.",
  "request_id": "req_01J9X7P2QK"
}

429

Too many requests. Wait for the number of seconds in Retry-After.

application/problem+json

RFC 9457 Problem Details with a stable code.

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

Stable machine-readable error code. Switch on this, not on title.

string

detail

string

request_id

required

string

errors

Field errors, for invalid_request.

Array<object>

object

field

string

message

string

Example

{
  "type": "https://docs.partners.loops.sa/errors/scope_not_granted",
  "title": "Scope not granted",
  "status": 403,
  "code": "invalid_request",
  "detail": "The merchant has not granted orders:read to this application.",
  "request_id": "req_01J9X7P2QK"
}

Headers

Retry-After

integer

Seconds to wait before retrying.