Simulate an in-store order

POST/v1/test/in_store_orders

Credits a visit as if the member paid at a Square register at the location. Use it to see how points earned at the register show up in your app: the balance, an activity entry, and the order.credited and points.changed webhooks with channel: "in_store".

Permissions: Sandbox secret key.

Guide

Sandbox

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Request body#

member_idstring (uuid)Required
The member who visits.
location_idstring (uuid)Required
A location in your sandbox brand.
subtotal_centsintegerRequired
The visit's subtotal. It earns at the program's rate.
Min 0

$8.00 at 10 Beans per dollar is 80 Beans, so Maya goes from 420 to 500 and can now afford Free drip coffee. The response above is trimmed; it is an order object.

Response fields#

Returns 201 with Order

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.

POST/v1/test/in_store_orders

1
2
3
4
5
6
7
8curl -X POST $UNPLUG_API/test/in_store_orders \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    "subtotal_cents": 800
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13const response = await fetch(`${process.env.UNPLUG_API}/test/in_store_orders`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    member_id: "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
    location_id: "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
    subtotal_cents: 800,
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import os
import requests

response = requests.post(
    f"{os.environ['UNPLUG_API']}/test/in_store_orders",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
    json={
        "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
        "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
        "subtotal_cents": 800,
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "id": "6a2d9f4b-8e1c-4b73-a5d0-3f7c1e9b2a48",
  "status": "credited",
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
  "channel": "in_store",
  "currency": "USD",
  "subtotal_cents": 800,
  "points_earned": 80,
  "bonus_points": 0,
  "member": {
    "points_balance": 500,
    "tier": { "id": "2b9e4f7a-1c3d-4e6b-8a5f-9d0c2e7b4a13", "name": "Green" }
  },
  "created_at": "2026-11-05T16:41:09Z"
}

Error descriptions#

404Not found

member_not_found

, 404 location_not_found An id doesn't exist in your sandbox brand.

404Not found

not_found

Called on production.

Any endpoint can also return the common errors.

404 Not found

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#member_not_found",
  "title": "Not found",
  "status": 404,
  "code": "member_not_found",
  "detail": ", 404 location_not_found An id doesn't exist in your sandbox brand."
}