List orders

GET/v1/orders

Returns orders, newest first. Filter by member for an order history, or by external_order_id to check whether an order was credited before you retry it.

Permissions: Secret key with checkout:write.

Guide

Checkout and orders

Query parameters#

member_idstring (uuid)
Orders for one member.
external_order_idstring
Exact match. Returns zero or one order.
limitinteger
1 to 100. Default 25.
Min 1Max 100Default 25
cursorstring
next_cursor from the previous page. See Pagination.

items is shortened above; the response has the full lines.

Response fields#

Returns 200 with list of Order

dataarray of Order
Show attributesOrder
- idstring (uuid)
  unPLUG's id for the order.
- external_order_idstringNullable
  Your order id. Unique in your brand, forever.
- statusstring
  credited, partially_refunded or refunded. See Order statuses.
  One of credited, partially_refunded, refunded
- member_idstring (uuid)Nullable
  null for a guest order, which earns nothing.
- location_idstring (uuid)
- channelstring
  app or web for orders you send. Points earned at the register also show up, as orders with in_store. May grow.
  One of app, web, in_store
- fulfillmentstringNullable
  pickup, delivery, curbside or dine_in.
- placed_atstring (date-time)
  When the guest placed the order. The earn rate and bonuses in force at this time apply.
- currencystring
  USD.
- subtotal_centsinteger
  Sum of the lines, before discounts, tax and tip.
  Min 0
- discount_centsinteger
  All discounts on the order, including the unPLUG redemption.
  Min 0
- tax_centsinteger
  Recorded for reports. They never earn.
  Min 0
- tip_centsinteger
  Recorded for reports. They never earn.
  Min 0
- total_centsinteger
  What the guest paid: subtotal minus discount, plus tax and tip.
  Min 0
- itemsarray of CartItem
  The cart lines, same shape as preview.
  Show attributesCartItem
  - line_idstring
    Your id for the line, unique within the cart.
  - pos_item_idstring
    Square catalog item variation id.
  - namestring
  - quantityinteger
    Min 1
  - unit_price_centsinteger
    Integer cents.
    Min 0
  - pos_category_idsarray of string
  - modifiersarray of object
    Show attributesHide attributes
    pos_modifier_idstring
    namestring
    price_centsinteger
    Integer cents.
    Min 0
- points_earnedinteger
  Points from the earn rate, on the subtotal after discounts, rounded down.
- bonus_pointsinteger
  Extra points from promotions in force at placed_at.
- redemptionsarray of object
  [{ "id", "status" }] for each redemption the order used.
  Show attributesHide attributes
  - idstring (uuid)
  - statusstring
- memberobjectNullable
  { "points_balance", "tier" } right after the order was credited. Only on the create response and the order.credited webhook.
  Show attributesHide attributes
  - points_balanceinteger
  - tierTierRef
    Show attributesTierRef
    idstring (uuid)
    namestring
- created_atstring (date-time)
  When unPLUG recorded the order.
has_moreboolean
True when another page exists.
next_cursorstringNullable
Pass as cursor to get the next page.

GET/v1/orders

1
2curl "$UNPLUG_API/orders?external_order_id=app-30417" \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6const response = await fetch(`${process.env.UNPLUG_API}/orders?external_order_id=app-30417`, {
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
  },
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10import os
import requests

response = requests.get(
    f"{os.environ['UNPLUG_API']}/orders?external_order_id=app-30417",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27{
  "data": [
    {
      "id": "c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24",
      "external_order_id": "app-30417",
      "status": "credited",
      "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
      "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
      "channel": "app",
      "fulfillment": "pickup",
      "placed_at": "2026-11-05T14:08:49Z",
      "currency": "USD",
      "subtotal_cents": 1250,
      "discount_cents": 350,
      "tax_cents": 74,
      "tip_cents": 150,
      "total_cents": 1124,
      "items": [ ... ],
      "redemptions": [ { "id": "4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59", "status": "captured" } ],
      "points_earned": 90,
      "bonus_points": 0,
      "created_at": "2026-11-05T14:08:52Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Error descriptions#

400Bad request

invalid_param

limit is outside 1 to 100, or the cursor is not one we issued.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#invalid_param",
  "title": "Bad request",
  "status": 400,
  "code": "invalid_param",
  "detail": "limit is outside 1 to 100, or the cursor is not one we issued."
}