Data models

Every object the App API returns and every request body it accepts, field by field. Each model links to the endpoints that use it. The same models are in openapi.yaml, so you can generate types from them.

Model names are what you'll see in the OpenAPI file and in generated code. Fields marked required are always present in responses and must be sent in requests. nullable fields can be null.

Common#

Problem#

RFC 9457 problem details, served as application/problem+json.

typestring (uri)Required
Link to the docs for this error.
titlestringRequired
statusintegerRequired
codeErrorCodeRequired
Show valuesHide values
- invalid_request
- invalid_param
- missing_param
- invalid_api_key
- token_expired
- missing_scope
- not_found
- member_not_found
- member_deleted
- external_id_taken
- phone_in_use
- idempotency_key_required
- idempotency_key_reused
- request_in_progress
- rate_limited
- insufficient_points
- reward_not_found
- reward_not_applicable
- reward_expired
- reward_already_used
- code_invalid
- code_expired
- code_limit_reached
- redemption_expired
- redemption_not_reserved
- one_redemption_per_order
- order_already_exists
- refund_exceeds_order
- location_not_found
- challenge_not_joinable
- invalid_state
- internal_error
- service_unavailable
detailstring
A sentence about this occurrence.
paramstringNullable
The request field at fault, when there is one.
order_idstring (uuid)
Only on order_already_exists: the order that was already credited.
request_idstringRequired
Same as the Request-Id header.

ErrorCode#

Machine-readable error code. May grow.

One of invalid_request, invalid_param, missing_param, invalid_api_key, token_expired, missing_scope, not_found, member_not_found, member_deleted, external_id_taken, phone_in_use, idempotency_key_required, idempotency_key_reused, request_in_progress, rate_limited, insufficient_points, reward_not_found, reward_not_applicable, reward_expired, reward_already_used, code_invalid, code_expired, code_limit_reached, redemption_expired, redemption_not_reserved, one_redemption_per_order, order_already_exists, refund_exceeds_order, location_not_found, challenge_not_joinable, invalid_state, internal_error, service_unavailable

ReasonCode#

Why a reward or code doesn't apply. May grow.

One of below_minimum_subtotal, wrong_channel, wrong_location, wrong_fulfillment, outside_available_times, item_not_in_cart, tier_required, not_enough_points, per_member_limit_reached, budget_exhausted, not_started, expired, already_used

CursorList#

Cursor-paginated list. ?limit= (1 to 100, default 25) and ?cursor=.

dataarray of objectRequired
has_morebooleanRequired
True when another page exists.
next_cursorstringRequiredNullable
Pass as cursor to get the next page.

Address#

line1string
line2stringNullable
citystring
regionstring
postal_codestring
countrystring
ISO 3166-1 alpha-2.

Program and catalog#

Program#

Used by

GET/v1/programresponse

brand_idstring (uuid)Required
Your brand.
namestringRequired
The program name guests see, for example Rewards.
point_nameobjectRequired
singular and plural, for example Bean and Beans. Use these in your UI instead of the word "points".
Show attributesHide attributes
- singularstringRequired
- pluralstringRequired
earningobjectRequired
Show attributesHide attributes
- typestringRequired
  One of spend, visit
- points_per_dollarinteger
  When type is spend.
- points_per_visitinteger
  When type is visit.
- roundingstringRequired
  One of down
- earn_onstringRequired
  Points are earned on the subtotal after discounts.
  One of subtotal
tiersarray of TierRequired
Tiers from lowest to highest. Each has id, name, min_lifetime_points and, when the tier gives one, upgrade_bonus_points (points added once when a member moves up into it). Tiers are based on lifetime points, so spending points never drops a member's tier.
Show attributesTier
- idstring (uuid)Required
- namestringRequired
- min_lifetime_pointsintegerRequired
- upgrade_bonus_pointsinteger
  Points added when a member reaches this tier.
default_time_zonestringRequired
IANA time zone used for anything that has no location, such as birthdays.
currencystringRequired
ISO 4217 code. USD.
points_expiryobjectNullableComing soon
Coming soon { "days_inactive": 365 } when points expire after a period with no activity. Points don't expire at launch, and the field is absent.
Show attributesHide attributes
- days_inactiveinteger

Example

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
28
29{
  "brand_id": "e5a1c7d9-2f4b-4c8e-a3d6-8b0f1e9c2a57",
  "name": "Rewards",
  "point_name": {
    "singular": "Bean",
    "plural": "Beans"
  },
  "earning": {
    "type": "spend",
    "points_per_dollar": 10,
    "rounding": "down",
    "earn_on": "subtotal"
  },
  "tiers": [
    {
      "id": "2b9e4f7a-1c3d-4e6b-8a5f-9d0c2e7b4a13",
      "name": "Green",
      "min_lifetime_points": 0
    },
    {
      "id": "6f1a8c3d-9b2e-4d7a-b5c6-3e0f8a1d2b47",
      "name": "Gold",
      "min_lifetime_points": 2000,
      "upgrade_bonus_points": 200
    }
  ],
  "default_time_zone": "America/Chicago",
  "currency": "USD"
}

Tier#

idstring (uuid)Required
namestringRequired
min_lifetime_pointsintegerRequired
upgrade_bonus_pointsinteger
Points added when a member reaches this tier.

TierRef#

idstring (uuid)Required
namestringRequired

Location#

Used by

GET/v1/locationsresponse

idstring (uuid)Required
Send this as location_id on previews, redemptions and orders.
namestringRequired
For example South Congress.
addressAddress
line1, line2 (or null), city, region, postal_code, country (ISO 3166-1 alpha-2).
Show attributesAddress
- line1string
- line2stringNullable
- citystring
- regionstring
- postal_codestring
- countrystring
  ISO 3166-1 alpha-2.
time_zonestringRequired
IANA time zone. Reward times and visit days at this location use it.
posstring
The location's point of sale. square.
One of square
pos_location_idstring
The Square location id. Match it against your own ordering system's location ids.
statusstringRequired
live or not_live. Only offer ordering at live locations.
One of live, not_live

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
  "name": "South Congress",
  "address": {
    "line1": "1412 S Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78704",
    "country": "US"
  },
  "time_zone": "America/Chicago",
  "pos": "square",
  "pos_location_id": "LQ7H2XK9M3RTB",
  "status": "live"
}

Reward#

A reward is a discount a member can get. The catalog holds points rewards, which members buy with points at checkout. Rewards given to one member (from a tier, an offer, a birthday or support) have kind: "wallet" and appear only inside that member's wallet, in this same shape.

Used by

GET/v1/rewardsresponse
GET/v1/rewards/{id}response

idstring (uuid)Required
Send this as reward_id on previews and redemptions.
namestringRequired
For example Free drip coffee.
descriptionstring
Short text for the guest.
image_urlstring (uri)Nullable
HTTPS image URL.
kindstringRequired
points (catalog) or wallet (given to one member). May grow.
One of points, wallet
points_costinteger
Points the reward costs. Only on points rewards; wallet rewards don't have it.
discountDiscountRequired
Show attributesDiscount
- typestringRequired
  One of amount, percent, free_item, bogo
- amount_centsinteger
  For amount.
- percentnumber
  For percent.
- itemsarray of object
  Item scope, by Square variation id.
  Show attributesHide attributes
  - pos_item_idstring
  - namestring
- categoriesarray of object
  Category scope.
  Show attributesHide attributes
  - pos_category_idstring
  - namestring
- max_itemsinteger
rulesRulesRequired
Show attributesRules
- min_subtotal_centsinteger
  Integer cents.
  Min 0
- channelsarray of string
  One of app, web
- location_idsarray of string (uuid)
- fulfillmentarray of string
  One of pickup, delivery, curbside, dine_in
- available_timesarray of AvailableTime
  Show attributesAvailableTime
  - daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
  - startstring
    Local time, HH:MM.
  - endstring
    Local time, HH:MM.
- tier_idsarray of string (uuid)
starts_atstring (date-time)Nullable
When the reward becomes available. null means it already is.
ends_atstring (date-time)Nullable
When it stops being available. null means no end date.

An empty array in rules means no limit: "location_ids": [] works at every location. A reward limited to weekday mornings for pickup in the app looks like this:

Discount types#

`type`	Fields	What the guest gets
`amount`	`amount_cents`	A fixed amount off the subtotal, or off the matching items when the reward has an item scope.
`percent`	`percent`	A percentage off the subtotal, or off the matching items when the reward has an item scope.
`free_item`	`items` or `categories`, `max_items`	Up to `max_items` matching items free.
`bogo`	`items` or `categories`	Buy one matching item, get a second matching item free.

The API works out the actual discount on a given cart. Show the discount_cents from a checkout preview rather than calculating it yourself.

Example

1
2
3
4
5
6
7
8"rules": {
  "min_subtotal_cents": 0,
  "channels": ["app"],
  "location_ids": [],
  "fulfillment": ["pickup"],
  "available_times": [ { "days": ["mon", "tue", "wed", "thu", "fri"], "start": "07:00", "end": "11:00" } ],
  "tier_ids": []
}

Rules#

Empty arrays mean no limit.

min_subtotal_centsinteger
Integer cents.
Min 0
channelsarray of string
One of app, web
location_idsarray of string (uuid)
fulfillmentarray of string
One of pickup, delivery, curbside, dine_in
available_timesarray of AvailableTime
Show attributesAvailableTime
- daysarray of string
  Show valuesHide values
  - mon
  - tue
  - wed
  - thu
  - fri
  - sat
  - sun
- startstring
  Local time, HH:MM.
- endstring
  Local time, HH:MM.
tier_idsarray of string (uuid)

Discount#

typestringRequired
One of amount, percent, free_item, bogo
amount_centsinteger
For amount.
percentnumber
For percent.
itemsarray of object
Item scope, by Square variation id.
Show attributesHide attributes
- pos_item_idstring
- namestring
categoriesarray of object
Category scope.
Show attributesHide attributes
- pos_category_idstring
- namestring
max_itemsinteger

AvailableTime#

daysarray of string
Show valuesHide values
- mon
- tue
- wed
- thu
- fri
- sat
- sun
startstring
Local time, HH:MM.
endstring
Local time, HH:MM.

Members and tokens#

Member#

Used by

idstring (uuid)Required
unPLUG's id for the member. Store it next to your user record.
external_idstringNullable
Your id for the guest, up to 128 characters. null for a guest who has only earned at the register and isn't linked to your login yet.
Max Length 128
statusstringRequired
active. The member.deleted webhook carries deleted; after that, calls about the member return 410 member_deleted.
One of active, deleted
first_namestringNullable
last_namestringNullable
emailstring (email)Nullable
Saved in lowercase.
phonestringNullable
E.164, for example +15125550142.
phone_verifiedboolean
true when you confirmed the guest owns the number, for example with an SMS code. Only verified phones link to existing members.
birthdaystring (date)Nullable
YYYY-MM-DD.
points_balanceintegerRequired
Points the member has now. Never below zero.
lifetime_pointsintegerRequired
All points ever earned, used for tiers. Spending doesn't lower it.
tierTierRefRequired
id and name of the current tier.
Show attributesTierRef
- idstring (uuid)Required
- namestringRequired
next_tierobjectNullable
id, name and points_needed (lifetime points still to earn). null at the top tier.
Show attributesHide attributes
- idstring (uuid)
- namestring
- points_neededinteger
communication_preferencesobject
Marketing consent: email_marketing, sms_marketing, push_marketing. See communication preferences.
Show attributesHide attributes
- email_marketingboolean
- sms_marketingboolean
- push_marketingboolean
metadataobject
Your own string values. Up to 20 keys, 500 characters each. Don't put personal data here.
linked_existingboolean
Only on create: true when an existing member was linked by verified phone.
enrolled_atstring (date-time)
When the guest joined the program.
created_atstring (date-time)Required
updated_atstring (date-time)Required

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20{
  "id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "external_id": "usr_10482",
  "status": "active",
  "first_name": "Maya",
  "last_name": "Lopez",
  "email": "maya@example.com",
  "phone": "+15125550142",
  "phone_verified": true,
  "birthday": "1994-03-18",
  "points_balance": 420,
  "lifetime_points": 1880,
  "tier": { "id": "2b9e4f7a-1c3d-4e6b-8a5f-9d0c2e7b4a13", "name": "Green" },
  "next_tier": { "id": "6f1a8c3d-9b2e-4d7a-b5c6-3e0f8a1d2b47", "name": "Gold", "points_needed": 120 },
  "communication_preferences": { "email_marketing": true, "sms_marketing": false, "push_marketing": true },
  "metadata": { "favorite_store": "south-congress" },
  "enrolled_at": "2025-06-14T15:02:44Z",
  "created_at": "2025-06-14T15:02:44Z",
  "updated_at": "2026-11-01T16:12:41Z"
}

MemberCreate#

Used by

POST/v1/membersrequest body

external_idstringRequired
Max Length 128
first_namestring
last_namestring
emailstring (email)
phonestring
E.164.
phone_verifiedboolean
birthdaystring (date)
communication_preferencesobject
Show attributesHide attributes
- email_marketingboolean
- sms_marketingboolean
- push_marketingboolean
metadataobject

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "external_id": "usr_10482",
  "first_name": "Maya",
  "last_name": "Lopez",
  "email": "Maya@Example.com",
  "phone": "+15125550142",
  "phone_verified": true,
  "birthday": "1994-03-18",
  "communication_preferences": {
    "email_marketing": true,
    "sms_marketing": false,
    "push_marketing": true
  },
  "metadata": {
    "favorite_store": "south-congress"
  }
}

MemberUpdate#

Used by

PATCH/v1/members/{id}request body

first_namestring
last_namestring
emailstring (email)
phonestring
E.164. Secret key only.
phone_verifiedboolean
Secret key only.
birthdaystring (date)
Set once from the app; a secret key can correct it.
metadataobject

CommunicationPreferences#

Used by

GET/v1/members/{id}/communication_preferencesresponse
PATCH/v1/members/{id}/communication_preferencesresponse

email_marketingbooleanRequired
sms_marketingbooleanRequired
push_marketingbooleanRequired
updated_atstring (date-time)Required
sourcestringRequired
Set automatically.
One of app, web, api, unsubscribe_link

CommunicationPreferencesUpdate#

Used by

PATCH/v1/members/{id}/communication_preferencesrequest body

email_marketingboolean
sms_marketingboolean
push_marketingboolean

MemberTokenRequest#

Send member_id or external_id.

Used by

POST/v1/member_tokensrequest body

member_idstring (uuid)
external_idstring

MemberToken#

Used by

POST/v1/member_tokensresponse

tokenstringRequired
Opaque, starts with mt_.
expires_atstring (date-time)Required
member_idstring (uuid)Required

HostedTokenResponse#

Coming soon.

access_tokenstring
A member token, mt_....
token_typestring
expires_ininteger
refresh_tokenstring
Rotates on every use.
member_idstring (uuid)

IdentificationCode Coming soon#

Coming soon. Valid for 5 minutes.

codestringRequired
qr_payloadstringRequired
expires_atstring (date-time)Required

Activity and wallet#

ActivityEntry#

Used by

GET/v1/members/{id}/activityresponse

idstring (uuid)Required
typestringRequired
What happened. See the table below. May grow.
One of earn, bonus, redeem, adjust, reverse, expire
pointsintegerRequired
Signed change: 62 for an earn, -500 for a redeem.
balance_afterintegerRequired
The member's points_balance right after this entry.
descriptionstring
A short line you can show the guest, for example Visit at South Congress or Free drip coffee.
order_idstring (uuid)Nullable
The order that caused it, for earn, bonus, redeem and reverse.
reward_idstring (uuid)Nullable
The reward bought, for redeem.
adjustment_reasonstringNullable
For adjust: goodwill, correction, migration or other.
One of goodwill, correction, migration, other
created_atstring (date-time)Required

`type`	Meaning	Sign
`earn`	Points from an order, in your app or at the register.	+
`bonus`	Extra points from a promotion, a birthday or a tier upgrade.	+
`redeem`	Points spent on a reward, when the order is credited.	-
`adjust`	Points added or removed with a points adjustment.	+ or -
`reverse`	Points taken back or returned by a refund.	+ or -
`expire` Coming soon	Points that expired after a period with no activity.	-

Example

1
2
3
4
5
6
7
8
9
10
11{
  "id": "c2e8a4f1-6b3d-4e9a-8c7f-1d5b0e3a9c26",
  "type": "earn",
  "points": 62,
  "balance_after": 420,
  "description": "Visit at South Congress",
  "order_id": "5d9b3e7f-1a4c-4f8e-b2d6-0c7a9e1f3b58",
  "reward_id": null,
  "adjustment_reason": null,
  "created_at": "2026-11-01T16:12:40Z"
}

WalletItem#

Used by

GET/v1/members/{id}/walletresponse
POST/v1/test/members/{id}/walletresponse

idstring (uuid)Required
Send this as wallet_item_id on previews and redemptions.
rewardRewardRequired
The reward, in the same shape as the catalog, with kind: "wallet" and no points_cost. Its rules apply at checkout.
Show attributesReward
- idstring (uuid)Required
  Send this as reward_id on previews and redemptions.
- namestringRequired
  For example Free drip coffee.
- descriptionstring
  Short text for the guest.
- image_urlstring (uri)Nullable
  HTTPS image URL.
- kindstringRequired
  points (catalog) or wallet (given to one member). May grow.
  One of points, wallet
- points_costinteger
  Points the reward costs. Only on points rewards; wallet rewards don't have it.
- discountDiscountRequired
  Show attributesDiscount
  - typestringRequired
    One of amount, percent, free_item, bogo
  - amount_centsinteger
    For amount.
  - percentnumber
    For percent.
  - itemsarray of object
    Item scope, by Square variation id.
    Show attributesHide attributes
    pos_item_idstring
    namestring
  - categoriesarray of object
    Category scope.
    Show attributesHide attributes
    pos_category_idstring
    namestring
  - max_itemsinteger
- rulesRulesRequired
  Show attributesRules
  - min_subtotal_centsinteger
    Integer cents.
    Min 0
  - channelsarray of string
    One of app, web
  - location_idsarray of string (uuid)
  - fulfillmentarray of string
    One of pickup, delivery, curbside, dine_in
  - available_timesarray of AvailableTime
    Show attributesAvailableTime
    daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
    startstring
    Local time, HH:MM.
    endstring
    Local time, HH:MM.
  - tier_idsarray of string (uuid)
- starts_atstring (date-time)Nullable
  When the reward becomes available. null means it already is.
- ends_atstring (date-time)Nullable
  When it stops being available. null means no end date.
sourcestringRequired
How the member got it. See the table below. May grow.
One of tier, offer, challenge, journey, support, birthday
offer_idstring (uuid)Nullable
The offer, when source is offer.
statusstringRequired
available, reserved, used or expired.
One of available, reserved, used, expired
issued_atstring (date-time)Required
When it landed in the wallet.
expires_atstring (date-time)Nullable
After this time it can't be used. null means it doesn't expire.
used_atstring (date-time)Nullable
When an order used it.
order_idstring (uuid)Nullable
The order that used it.

Statuses#

`status`	Meaning	Moves to
`available`	The member can use it.	`reserved` when a redemption holds it, `expired` at `expires_at`.
`reserved`	Held by a redemption while the guest pays.	`used` when the order is credited, `available` when the redemption is canceled or its 15-minute hold expires.
`used`	An order used it.	`available` again if the order is fully refunded before `expires_at`.
`expired`	Past `expires_at` without being used.	Nothing. Final.

Sources#

`source`	Where it came from
`tier`	A reward that comes with the member's tier.
`offer`	A targeted offer sent to this member. `offer_id` is set.
`birthday`	The program's birthday reward.
`journey`	An unPLUG journey, for example a win-back message.
`support`	Given by your team in the unPLUG dashboard, or by unPLUG support.
`challenge` Coming soon	Completing a challenge.

A reward.issued webhook fires when an item lands in a wallet, and reward.expiring fires 3 days before it expires. See Webhook event types.

Example

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
28
29
30
31
32
33
34
35
36
37
38
39
40{
  "id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
  "reward": {
    "id": "d4c2e8a6-7b3f-4e1d-9a5c-1f8b6d3e0a92",
    "name": "Fall pastry on us",
    "description": "Any pastry, one per order.",
    "image_url": "https://cdn.unplugdining.com/rewards/d4c2e8a6.jpg",
    "kind": "wallet",
    "discount": {
      "type": "free_item",
      "categories": [
        {
          "pos_category_id": "P9MT2XQ6KZR4WLN8HCB3J7VD",
          "name": "Pastries"
        }
      ],
      "max_items": 1
    },
    "rules": {
      "min_subtotal_cents": 0,
      "channels": [
        "app",
        "web"
      ],
      "location_ids": [],
      "fulfillment": [],
      "available_times": [],
      "tier_ids": []
    },
    "starts_at": null,
    "ends_at": null
  },
  "source": "offer",
  "offer_id": "a8f2d6b4-3e9c-4a7f-8d1e-6c5b2a0f9e37",
  "status": "available",
  "issued_at": "2026-10-30T15:00:00Z",
  "expires_at": "2026-11-13T05:59:59Z",
  "used_at": null,
  "order_id": null
}

Checkout and orders#

Cart#

Checkout preview request. Omit member_id for a guest with a code.

Used by

POST/v1/checkouts/previewrequest body

member_idstring (uuid)
The member. Leave it out for a guest checkout with a code. With a member token it is always the token's member.
location_idstring (uuid)Required
From GET /v1/locations.
channelstringRequired
app or web.
One of app, web
fulfillmentstringRequired
pickup, delivery, curbside or dine_in. May grow.
One of pickup, delivery, curbside, dine_in
currencystringRequired
USD.
subtotal_centsintegerRequired
The sum of every line (unit price plus modifiers, times quantity), before discounts, tax and tip.
Min 0
itemsarray of CartItemRequired
The cart lines. See below.
Show attributesCartItem
- line_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  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
codesarray of string
reward_idsarray of string (uuid)
wallet_item_idsarray of string (uuid)

Cart line#

Example

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48{
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
  "channel": "app",
  "fulfillment": "pickup",
  "currency": "USD",
  "subtotal_cents": 1250,
  "items": [
    {
      "line_id": "1",
      "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
      "name": "Oat latte",
      "quantity": 1,
      "unit_price_cents": 575,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "2",
      "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
      "name": "Drip coffee",
      "quantity": 1,
      "unit_price_cents": 325,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "3",
      "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C",
      "name": "Butter croissant",
      "quantity": 1,
      "unit_price_cents": 350,
      "pos_category_ids": [
        "P9MT2XQ6KZR4WLN8HCB3J7VD"
      ],
      "modifiers": []
    }
  ],
  "codes": [
    "WELCOME10"
  ],
  "reward_ids": [],
  "wallet_item_ids": []
}

CartItem#

line_idstringRequired
Your id for the line, unique within the cart.
pos_item_idstring
Square catalog item variation id.
namestringRequired
quantityintegerRequired
Min 1
unit_price_centsintegerRequired
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

Preview#

Used by

POST/v1/checkouts/previewresponse

member_idstring (uuid)Nullable
points_balanceintegerNullable
points_to_earninteger
applicablearray of PreviewEntryRequired
Show attributesPreviewEntry
- typestringRequired
  One of reward, wallet_item, code
- reward_idstring (uuid)
- wallet_item_idstring (uuid)
- codestring
- namestringRequired
- points_costinteger
  For reward.
- discount_centsinteger
  Applicable entries only.
- affected_line_idsarray of string
  Applicable entries only.
- reasonReasonCode
  Show valuesHide values
  - below_minimum_subtotal
  - wrong_channel
  - wrong_location
  - wrong_fulfillment
  - outside_available_times
  - item_not_in_cart
  - tier_required
  - not_enough_points
  - per_member_limit_reached
  - budget_exhausted
  - not_started
  - expired
  - already_used
- messagestring
  Not-applicable entries only. Safe to show guests.
not_applicablearray of PreviewEntryRequired
Show attributesPreviewEntry
- typestringRequired
  One of reward, wallet_item, code
- reward_idstring (uuid)
- wallet_item_idstring (uuid)
- codestring
- namestringRequired
- points_costinteger
  For reward.
- discount_centsinteger
  Applicable entries only.
- affected_line_idsarray of string
  Applicable entries only.
- reasonReasonCode
  Show valuesHide values
  - below_minimum_subtotal
  - wrong_channel
  - wrong_location
  - wrong_fulfillment
  - outside_available_times
  - item_not_in_cart
  - tier_required
  - not_enough_points
  - per_member_limit_reached
  - budget_exhausted
  - not_started
  - expired
  - already_used
- messagestring
  Not-applicable entries only. Safe to show guests.
challenge_progressarray of object
Filled when challenges ship (coming soon).

Example

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54{
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "points_balance": 420,
  "points_to_earn": 125,
  "applicable": [
    {
      "type": "wallet_item",
      "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
      "name": "Fall pastry on us",
      "discount_cents": 350,
      "affected_line_ids": [
        "3"
      ]
    },
    {
      "type": "code",
      "code": "WELCOME10",
      "name": "10% off your order",
      "discount_cents": 125,
      "affected_line_ids": [
        "1",
        "2",
        "3"
      ]
    }
  ],
  "not_applicable": [
    {
      "type": "reward",
      "reward_id": "9a6e3d21-4c7b-4f8a-b2e5-0d1c6f3a7b98",
      "name": "Free drip coffee",
      "points_cost": 500,
      "reason": "not_enough_points",
      "message": "You need 80 more Beans for this reward."
    },
    {
      "type": "reward",
      "reward_id": "5e8b1f4c-2d9a-4b6e-8c3f-7a0d2e9b1c65",
      "name": "Free pastry",
      "points_cost": 700,
      "reason": "not_enough_points",
      "message": "You need 280 more Beans for this reward."
    },
    {
      "type": "reward",
      "reward_id": "b3d7a9e2-6f1c-4a8d-9e5b-2c4f7a1d3e86",
      "name": "$5 off",
      "points_cost": 900,
      "reason": "not_enough_points",
      "message": "You need 480 more Beans for this reward."
    }
  ],
  "challenge_progress": []
}

PreviewEntry#

typestringRequired
One of reward, wallet_item, code
reward_idstring (uuid)
wallet_item_idstring (uuid)
codestring
namestringRequired
points_costinteger
For reward.
discount_centsinteger
Applicable entries only.
affected_line_idsarray of string
Applicable entries only.
reasonReasonCode
Show valuesHide values
- below_minimum_subtotal
- wrong_channel
- wrong_location
- wrong_fulfillment
- outside_available_times
- item_not_in_cart
- tier_required
- not_enough_points
- per_member_limit_reached
- budget_exhausted
- not_started
- expired
- already_used
messagestring
Not-applicable entries only. Safe to show guests.

RedemptionRequest#

Send exactly one of reward_id, wallet_item_id or code.

Used by

POST/v1/redemptionsrequest body

member_idstring (uuid)
location_idstring (uuid)Required
channelstringRequired
app or web.
One of app, web
fulfillmentstringRequired
One of pickup, delivery, curbside, dine_in
currencystringRequired
ISO 4217 code. USD.
subtotal_centsintegerRequired
Integer cents.
Min 0
itemsarray of CartItemRequired
Show attributesCartItem
- line_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  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
reward_idstring (uuid)
wallet_item_idstring (uuid)
codestring

Example

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44{
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
  "channel": "app",
  "fulfillment": "pickup",
  "currency": "USD",
  "subtotal_cents": 1250,
  "items": [
    {
      "line_id": "1",
      "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
      "name": "Oat latte",
      "quantity": 1,
      "unit_price_cents": 575,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "2",
      "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
      "name": "Drip coffee",
      "quantity": 1,
      "unit_price_cents": 325,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "3",
      "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C",
      "name": "Butter croissant",
      "quantity": 1,
      "unit_price_cents": 350,
      "pos_category_ids": [
        "P9MT2XQ6KZR4WLN8HCB3J7VD"
      ],
      "modifiers": []
    }
  ],
  "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28"
}

Redemption#

Used by

POST/v1/redemptionsresponse
GET/v1/redemptions/{id}response
POST/v1/redemptions/{id}/cancelresponse

idstring (uuid)Required
Send it in redemption_ids on the order.
statusstringRequired
See Redemption statuses.
One of reserved, captured, canceled, expired, reversed
member_idstring (uuid)Nullable
null for a guest code.
reward_idstring (uuid)Nullable
What was redeemed. One is set.
wallet_item_idstring (uuid)Nullable
What was redeemed. One is set.
codestringNullable
What was redeemed. One is set.
discount_centsintegerRequired
The discount on the cart it was created for.
Min 0
points_costintegerRequired
Points held, then spent on capture. 0 for wallet items and codes.
affected_line_idsarray of string
Cart lines the discount applies to.
order_idstring (uuid)Nullable
The order that captured it.
expires_atstring (date-time)Required
End of the hold, 15 minutes after creation.
created_atstring (date-time)

Example

1
2
3
4
5
6
7
8
9
10{
  "id": "4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59",
  "status": "reserved",
  "discount_cents": 350,
  "points_cost": 0,
  "affected_line_ids": [
    "3"
  ],
  "expires_at": "2026-11-05T14:22:02Z"
}

OrderRequest#

Used by

POST/v1/ordersrequest body

external_order_idstringRequired
Max Length 128
member_idstring (uuid)
location_idstring (uuid)Required
channelstringRequired
app or web.
One of app, web
fulfillmentstringRequired
One of pickup, delivery, curbside, dine_in
currencystringRequired
ISO 4217 code. USD.
subtotal_centsintegerRequired
Integer cents.
Min 0
itemsarray of CartItemRequired
Show attributesCartItem
- line_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  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
placed_atstring (date-time)Required
discount_centsintegerRequired
Integer cents.
Min 0
tax_centsintegerRequired
Integer cents.
Min 0
tip_centsintegerRequired
Integer cents.
Min 0
total_centsintegerRequired
Integer cents.
Min 0
redemption_idsarray of string (uuid)
One at launch.
Max Items 1
attributionobjectComing soon
Coming soon.
Show attributesHide attributes
- link_idstring

Example

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52{
  "external_order_id": "app-30417",
  "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": [
    {
      "line_id": "1",
      "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
      "name": "Oat latte",
      "quantity": 1,
      "unit_price_cents": 575,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "2",
      "pos_item_id": "3NZQ7XKJ2Y5PLVKCW6RQ4G2T",
      "name": "Drip coffee",
      "quantity": 1,
      "unit_price_cents": 325,
      "pos_category_ids": [
        "C4RZ8NQ2MXK7WTP3LHB6V5JD"
      ],
      "modifiers": []
    },
    {
      "line_id": "3",
      "pos_item_id": "7PKD3RXN2WQ6ZLHM4TB5JV8C",
      "name": "Butter croissant",
      "quantity": 1,
      "unit_price_cents": 350,
      "pos_category_ids": [
        "P9MT2XQ6KZR4WLN8HCB3J7VD"
      ],
      "modifiers": []
    }
  ],
  "redemption_ids": [
    "4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59"
  ]
}

Order#

Used by

idstring (uuid)Required
unPLUG's id for the order.
external_order_idstringNullable
Your order id. Unique in your brand, forever.
statusstringRequired
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)Required
channelstringRequired
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.
currencystringRequired
USD.
subtotal_centsintegerRequired
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_idstringRequired
  Your id for the line, unique within the cart.
- pos_item_idstring
  Square catalog item variation id.
- namestringRequired
- quantityintegerRequired
  Min 1
- unit_price_centsintegerRequired
  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_earnedintegerRequired
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)Required
  - namestringRequired
created_atstring (date-time)Required
When unPLUG recorded the order.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21{
  "id": "c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24",
  "external_order_id": "app-30417",
  "status": "credited",
  "points_earned": 90,
  "bonus_points": 0,
  "redemptions": [
    {
      "id": "4b8d2f6a-9c1e-4a3d-b7f5-0e6c8a2d1b59",
      "status": "captured"
    }
  ],
  "member": {
    "points_balance": 510,
    "tier": {
      "id": "2b9e4f7a-1c3d-4e6b-8a5f-9d0c2e7b4a13",
      "name": "Green"
    }
  },
  "created_at": "2026-11-05T14:08:52Z"
}

RefundRequest#

Used by

POST/v1/orders/{id}/refundsrequest body

external_refund_idstringRequired
amount_centsinteger
Part of the subtotal refunded. Send this or full.
Min 1
fullboolean
reasonstring

Refund#

Used by

POST/v1/orders/{id}/refundsresponse

idstring (uuid)Required
order_idstring (uuid)Required
external_refund_idstringRequired
Your refund id.
amount_centsintegerRequired
The part of the subtotal after discounts that was refunded. For a full refund, everything not refunded before.
Min 0
fullbooleanRequired
true for a full refund.
reasonstringNullable
As you sent it.
points_reversedintegerRequired
Earned points taken back.
points_shortfallintegerRequired
Points that couldn't be taken back because the member had already spent them. The balance stops at zero.
order_statusstringRequired
The order's status after this refund: partially_refunded or refunded.
One of partially_refunded, refunded
member_idstring (uuid)Nullable
The order's member. null for a guest order.
memberobjectNullable
{ "points_balance" } after the refund. null for a guest order.
Show attributesHide attributes
- points_balanceinteger
created_atstring (date-time)Required

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "id": "e2b6d8f0-4a1c-4e7b-9d3f-6c8a0b2e5d71",
  "order_id": "c9e5a3f1-7d2b-4e8c-a0f6-3b1d9e5c7a24",
  "external_refund_id": "rf-30417-1",
  "amount_cents": 500,
  "full": false,
  "reason": "requested_by_customer",
  "points_reversed": 50,
  "points_shortfall": 0,
  "order_status": "partially_refunded",
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "member": {
    "points_balance": 460
  },
  "created_at": "2026-11-05T15:02:17Z"
}

Challenges#

Challenge Coming soon#

Coming soon.

Used by

GET/v1/challengesresponse

idstring (uuid)Required
The challenge.
namestringRequired
Shown to guests.
descriptionstring
One or two lines for guests.
image_urlstring (uri)Nullable
HTTPS image for the challenge card.
typestringRequired
visits, streak, spend or menu_discovery.
One of visits, streak, spend, menu_discovery
goalobjectRequired
target (number to reach) and unit (visits, periods, cents or items). Streaks add period (day or week) and grace_periods. Menu discovery adds item_set: items (pos_item_id, name) or categories (pos_category_id, name). Fields that don't apply are null or empty.
Show attributesHide attributes
- targetinteger
- unitstring
  One of visits, periods, cents, items
- periodstringNullable
  One of day, week
- grace_periodsintegerNullable
- item_setarray of object
qualifyingobject
Which orders count: min_subtotal_cents, channels, location_ids, fulfillment, available_times (same shapes as reward rules; empty lists mean no limit) and max_counted_per_day (default 1).
Show attributesHide attributes
- min_subtotal_centsinteger
  Integer cents.
  Min 0
- channelsarray of string
- location_idsarray of string (uuid)
- fulfillmentarray of string
  One of pickup, delivery, curbside, dine_in
- available_timesarray of AvailableTime
  Show attributesAvailableTime
  - daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
  - startstring
    Local time, HH:MM.
  - endstring
    Local time, HH:MM.
- max_counted_per_dayinteger
windowobject or objectRequired
{ "kind": "fixed", "starts_at", "ends_at" } for the same dates for everyone, or { "kind": "rolling", "days" } for a window per member that starts when they join.
enrollmentstringRequired
automatic or opt_in.
One of automatic, opt_in
rewardobject or objectRequired
{ "kind": "points", "points" } for bonus points, or { "kind": "reward", "reward_id" } for a catalog reward that lands in the wallet.
max_completions_per_memberinteger
Usually 1.
budgetobject
max_completions across all members, or null for no limit.
Show attributesHide attributes
- max_completionsintegerNullable
statusstringRequired
draft, scheduled, live, paused or ended.
One of draft, scheduled, live, paused, ended
versioninteger
Goes up each time a scheduled or live challenge is edited. Members keep the rules of the version they joined.

Example

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
28
29
30
31
32
33
34
35
36
37
38{
  "id": "4f9a2d61-3e8b-4c15-a7d0-b26e81f5c93a",
  "name": "Weekly regular",
  "description": "Visit 3 times this week and get 50 bonus Beans.",
  "image_url": "https://cdn.unplugdining.com/demo/challenges/weekly-regular.jpg",
  "type": "visits",
  "goal": {
    "target": 3,
    "unit": "visits",
    "period": null,
    "grace_periods": null,
    "item_set": []
  },
  "qualifying": {
    "min_subtotal_cents": 300,
    "channels": [],
    "location_ids": [],
    "fulfillment": [],
    "available_times": [],
    "max_counted_per_day": 1
  },
  "window": {
    "kind": "fixed",
    "starts_at": "2026-11-02T06:00:00Z",
    "ends_at": "2026-11-09T06:00:00Z"
  },
  "enrollment": "automatic",
  "reward": {
    "kind": "points",
    "points": 50
  },
  "max_completions_per_member": 1,
  "budget": {
    "max_completions": 2000
  },
  "status": "live",
  "version": 1
}

MemberChallenge Coming soon#

Coming soon. A member's progress on a challenge. member_id appears in webhooks.

Used by

GET/v1/members/me/challengesresponse
POST/v1/members/me/challenges/{id}/joinresponse
GET/v1/members/{id}/challengesresponse
POST/v1/members/{id}/challenges/{challenge_id}/joinresponse

challenge_idstring (uuid)Required
The challenge.
member_idstring (uuid)
statusstringRequired
eligible (can join, not joined), enrolled, completed or expired.
One of eligible, enrolled, completed, expired
progressobjectRequired
current, target and unit. For streaks, periods lists each day or week with starts_at, ends_at and met; it's empty for other types.
Show attributesHide attributes
- currentinteger
- targetinteger
- unitstring
  One of visits, periods, cents, items
- periodsarray of object
  Show attributesHide attributes
  - starts_atstring (date-time)
  - ends_atstring (date-time)
  - metboolean
window_ends_atstring (date-time)Nullable
When this member's window ends. For a rolling challenge they haven't joined, null.
completed_atstring (date-time)Nullable
When they completed it, or null.
reward_wallet_item_idstring (uuid)Nullable
The wallet item paid on completion, for catalog rewards. null otherwise.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "challenge_id": "4f9a2d61-3e8b-4c15-a7d0-b26e81f5c93a",
  "status": "enrolled",
  "progress": {
    "current": 2,
    "target": 3,
    "unit": "visits",
    "periods": []
  },
  "window_ends_at": "2026-11-09T06:00:00Z",
  "completed_at": null,
  "reward_wallet_item_id": null
}

Devices, messages and app events#

Device#

Used by

PUT/v1/members/me/devices/{device_id}response

device_idstringRequired
Your id for this install, up to 128 characters. Use a UUID you generate once and keep in app storage.
member_idstring (uuid)Required
The member signed in on the device.
platformstringRequired
ios or android.
One of ios, android
push_tokenstringNullable
The push token from Firebase or APNs. null if the app has none yet.
token_typestringRequired
fcm (from the Firebase SDK) or apns (a raw APNs token, iOS only).
One of fcm, apns
app_idstring
iOS bundle id or Android package name. Must be an app support set up for your brand.
push_enabledbooleanRequired
The OS notification permission. Marketing consent is separate: communication_preferences.push_marketing on the member.
app_versionstring
Your app's version, for example 4.2.0.
os_versionstring
For example 18.1.
localestring
BCP 47 tag, for example en-US.
time_zonestring
IANA name, for example America/Chicago. unPLUG uses it for quiet hours.
created_atstring (date-time)
First registration.
updated_atstring (date-time)
Last change.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
  "member_id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
  "platform": "ios",
  "push_token": "7f3a9c2e1b8d4f6a0c5e9b2d7f1a3c8e4b6d0f2a9c7e5b3d1f8a6c4e2b0d9f7a",
  "token_type": "apns",
  "app_id": "com.example.app",
  "push_enabled": true,
  "app_version": "4.2.0",
  "os_version": "18.1",
  "locale": "en-US",
  "time_zone": "America/Chicago",
  "created_at": "2026-10-12T15:04:51Z",
  "updated_at": "2026-10-30T14:58:20Z"
}

DeviceWrite#

Used by

PUT/v1/members/me/devices/{device_id}request body

platformstringRequired
One of ios, android
push_tokenstringNullable
Null until the app has a token.
token_typestring
Required with push_token.
One of fcm, apns
app_idstringRequired
push_enabledbooleanRequired
OS notification permission.
app_versionstring
os_versionstring
localestring
time_zonestring

Example

1
2
3
4
5
6
7
8
9
10
11{
  "platform": "ios",
  "push_token": "7f3a9c2e1b8d4f6a0c5e9b2d7f1a3c8e4b6d0f2a9c7e5b3d1f8a6c4e2b0d9f7a",
  "token_type": "apns",
  "app_id": "com.example.app",
  "push_enabled": true,
  "app_version": "4.2.0",
  "os_version": "18.1",
  "locale": "en-US",
  "time_zone": "America/Chicago"
}

Message#

A full-screen in-app message. Your app draws it.

Used by

GET/v1/members/me/messages/nextresponse
GET/v1/members/me/messages/{id}response
GET/v1/members/{id}/messages/nextresponse

idstring (uuid)Required
Same as message_id in the push that carried it.
layoutstringRequired
full_image (the image fills the screen and carries the words) or image_and_text (image on top, then title, body and buttons).
One of full_image, image_and_text
image_urlstring (uri)
HTTPS image.
titlestringNullable
Heading. For full_image, use it as the image's accessibility label.
bodystringNullable
Text under the title.
primaryMessageButtonRequired
The main button: label, action and url. action is open_screen (a link in your scheme or on your link domain), open_url (https, open in a browser) or close (url is null).
Show attributesMessageButton
- labelstring
- actionstring
  One of open_screen, open_url, close
- urlstringNullable
secondaryMessageButtonNullable
Second button, same shape, or null.
offerobjectNullable
An offer to show with the message, or null. code is a promo code to show; wallet_item_id is an offer already in the member's wallet; text is one line to show next to it.
Show attributesHide attributes
- codestringNullable
- wallet_item_idstring (uuid)Nullable
- textstring
displayobjectRequired
never_during: screens where the message must not appear. Always includes checkout.
Show attributesHide attributes
- never_duringarray of string
created_atstring (date-time)Required
When unPLUG created it.
expires_atstring (date-time)Nullable
Don't show it after this.

Your app always shows its own close button, whatever the buttons say.

Example

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
28
29{
  "id": "5b81d3e0-2c4f-4a96-8e17-d0f9a3b62c58",
  "layout": "image_and_text",
  "image_url": "https://cdn.unplugdining.com/demo/campaigns/fall-pastry.jpg",
  "title": "A pastry on us",
  "body": "Croissant or muffin, your pick. Add one to your next order and it's free. Good until November 12.",
  "primary": {
    "label": "See my wallet",
    "action": "open_screen",
    "url": "yourapp://wallet/7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28"
  },
  "secondary": {
    "label": "Not now",
    "action": "close",
    "url": null
  },
  "offer": {
    "code": null,
    "wallet_item_id": "7e3a9c51-0b8d-4f2e-a6c4-5d1b9e7f3a28",
    "text": "Fall pastry on us, until November 12."
  },
  "display": {
    "never_during": [
      "checkout"
    ]
  },
  "created_at": "2026-10-30T15:00:00Z",
  "expires_at": "2026-11-13T05:59:59Z"
}

MessageButton#

labelstring
actionstring
One of open_screen, open_url, close
urlstringNullable

MessageEventRequest#

Used by

POST/v1/members/me/messages/{id}/eventsrequest body
POST/v1/members/{id}/messages/{message_id}/eventsrequest body

typestringRequired
One of impression, button_tap, close
buttonstring
One of primary, secondary

PushOpenRequest#

Used by

POST/v1/members/me/push_opensrequest body

message_idstring (uuid)Required
opened_atstring (date-time)Required
buttonstring
One of primary, secondary

AppEvent#

event_idstring (uuid)Required
namestringRequired
occurred_atstring (date-time)Required
member_idstring (uuid)
anonymous_idstring
device_idstringRequired
session_idstringRequired
propertiesobject
No personal data.

AppEventBatch#

Used by

POST/v1/app_eventsrequest body

eventsarray of AppEventRequired
Min Items 1Max Items 100
Show attributesAppEvent
- event_idstring (uuid)Required
- namestringRequired
- occurred_atstring (date-time)Required
- member_idstring (uuid)
- anonymous_idstring
- device_idstringRequired
- session_idstringRequired
- propertiesobject
  No personal data.

Example

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
28
29
30
31
32
33
34
35
36
37{
  "events": [
    {
      "event_id": "e2b7c4a1-9d38-4f65-8a0e-3c1f6b9d2e57",
      "name": "added_to_cart",
      "occurred_at": "2026-11-03T14:12:40Z",
      "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
      "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
      "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
      "properties": {
        "cart_id": "cart_5Tn8qW2x",
        "pos_item_id": "HV4MZ2TQ7LW3KXRB5P8NJ6DC",
        "name": "Oat latte",
        "quantity": 1,
        "price_cents": 575,
        "currency": "USD",
        "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53"
      }
    },
    {
      "event_id": "7a3d9f0c-2e6b-4b18-a4c7-5e9b1d3f8a26",
      "name": "checkout_started",
      "occurred_at": "2026-11-03T14:13:05Z",
      "anonymous_id": "c5f1a8e3-7b2d-4c96-91e4-0a6d3f8b2c71",
      "device_id": "9c7e2f14-58ab-4d3e-b1a0-6f2d8e47c935",
      "session_id": "1d8e4b2f-6a3c-4e91-b7d5-2f0c9a8e6b34",
      "properties": {
        "cart_id": "cart_5Tn8qW2x",
        "subtotal_cents": 1000,
        "currency": "USD",
        "item_count": 2,
        "location_id": "8d4e2a17-3b9c-4f5e-a6d1-7c0b9e2f4a53",
        "fulfillment": "pickup"
      }
    }
  ]
}

AppEventResult#

Used by

POST/v1/app_eventsresponse

acceptedinteger
duplicatesinteger

Webhooks#

WebhookEndpoint#

Used by

POST/v1/webhook_endpointsresponse
GET/v1/webhook_endpointsresponse
GET/v1/webhook_endpoints/{id}response
PATCH/v1/webhook_endpoints/{id}response
POST/v1/webhook_endpoints/{id}/rotate_secretresponse

idstring (uuid)Required
The endpoint's id.
urlstring (uri)Required
Where events are sent. HTTPS on a public hostname.
descriptionstringNullable
Your label, up to 255 characters.
Max Length 255
event_typesarray of stringRequired
Types this endpoint gets, or ["*"] for all types, including types added later. See Webhook event types.
statusstringRequired
enabled or disabled. unPLUG sets disabled after 3 days of failed deliveries.
One of enabled, disabled
secretstring
The signing secret, whsec_ followed by base64. Returned only when you create the endpoint or rotate the secret.
created_atstring (date-time)Required
When the endpoint was created.
updated_atstring (date-time)Required
When the endpoint last changed.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "id": "1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72",
  "url": "https://api.example.com/webhooks/unplug",
  "description": "Loyalty sync",
  "event_types": [
    "points.changed",
    "tier.changed",
    "reward.issued",
    "member.deleted"
  ],
  "status": "enabled",
  "secret": "whsec_4cWtG7hYe5kSMHqAFDTiyxca6HNalvlQ",
  "created_at": "2026-11-02T14:51:30Z",
  "updated_at": "2026-11-02T14:51:30Z"
}

WebhookEndpointCreate#

Used by

POST/v1/webhook_endpointsrequest body

urlstring (uri)Required
HTTPS on a public hostname.
event_typesarray of stringRequired
Min Items 1
descriptionstring
Max Length 255

Example

1
2
3
4
5
6
7
8
9
10{
  "url": "https://api.example.com/webhooks/unplug",
  "event_types": [
    "points.changed",
    "tier.changed",
    "reward.issued",
    "member.deleted"
  ],
  "description": "Loyalty sync"
}

WebhookEndpointUpdate#

Used by

PATCH/v1/webhook_endpoints/{id}request body

urlstring (uri)
event_typesarray of string
Min Items 1
descriptionstring
Max Length 255
statusstring
One of enabled, disabled

Example

1
2
3
4
5
6
7
8
9
10{
  "event_types": [
    "points.changed",
    "tier.changed",
    "reward.issued",
    "member.deleted",
    "communication_preferences.updated"
  ],
  "status": "enabled"
}

RotateSecretRequest#

Used by

POST/v1/webhook_endpoints/{id}/rotate_secretrequest body

expire_current_in_hoursinteger
Default 24. 0 stops the current secret now.
Min 0Default 24

Event#

The same object is the body of every webhook and what the event log returns. Payloads for each type are on Webhook event types.

Used by

POST/v1/webhook_endpoints/{id}/testresponse
GET/v1/eventsresponse
GET/v1/events/{id}response

idstring (uuid)Required
The event's id. Same value as the webhook-id header, on every attempt and redelivery.
typestringRequired
For example points.changed. The list may grow.
Show valuesHide values
- member.created
- member.updated
- member.deleted
- points.changed
- tier.changed
- reward.issued
- reward.redeemed
- reward.expiring
- order.credited
- order.refunded
- communication_preferences.updated
- webhook.test
- points.expiring
- challenge.joined
- challenge.progressed
- challenge.completed
- referral.completed
created_atstring (date-time)Required
When the change happened. Use it to order events.
api_versionstringRequired
v1.
livemodebooleanRequired
true in production, false in the sandbox.
brand_idstring (uuid)Required
Your brand.
dataobjectRequired
Show attributesHide attributes
- objectobjectRequired
  Snapshot of the resource.
- previous_attributesobjectRequired

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "id": "d4c7a2e9-1f6b-4e85-8c3a-9b5d0e7f2a16",
  "type": "webhook.test",
  "created_at": "2026-11-06T09:15:40Z",
  "api_version": "v1",
  "livemode": true,
  "brand_id": "e5a1c7d9-2f4b-4c8e-a3d6-8b0f1e9c2a57",
  "data": {
    "object": {
      "webhook_endpoint_id": "1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72",
      "message": "Test event from unPLUG."
    },
    "previous_attributes": {}
  }
}

Delivery#

One attempt to send one event to one endpoint.

Used by

GET/v1/events/{id}/deliveriesresponse
POST/v1/events/{id}/redeliverresponse

idstring (uuid)Required
The delivery attempt's id.
event_idstring (uuid)Required
The event that was sent.
webhook_endpoint_idstring (uuid)Required
Where it was sent.
attemptintegerRequired
1 for the first attempt, then counting up through the retries.
Min 1
statusstringRequired
pending, succeeded or failed.
One of pending, succeeded, failed
status_codeintegerNullable
HTTP status your server returned. Null if there was no response.
response_msintegerNullable
How long your server took to respond, in milliseconds.
errorstringNullable
Why it failed when there was no HTTP status, for example timeout, connection_refused, tls_error or dns_error.
attempted_atstring (date-time)Nullable
When the attempt was made.
next_retry_atstring (date-time)Nullable
When the next retry is scheduled. Null after a success or when retries have run out.

Example

1
2
3
4
5
6
7
8
9
10
11
12{
  "id": "5e2a9f7c-4d1b-4e38-b6a0-2c8f1d7e3b95",
  "event_id": "7f3a9c2e-4b8d-4e16-a0c5-1d6b8e2f9a47",
  "webhook_endpoint_id": "1c7f4a9e-3d2b-4f86-a5e1-8b0d6c3f9e72",
  "attempt": 2,
  "status": "succeeded",
  "status_code": 200,
  "response_ms": 184,
  "error": null,
  "attempted_at": "2026-11-05T14:08:57Z",
  "next_retry_at": null
}

RedeliverRequest#

Used by

POST/v1/events/{id}/redeliverrequest body

webhook_endpoint_idstring (uuid)

ActivityEntryEvent#

idstring (uuid)Required
typestringRequired
May grow. expire is coming soon.
One of earn, bonus, redeem, adjust, reverse, expire
pointsintegerRequired
Signed.
balance_afterintegerRequired
descriptionstring
order_idstring (uuid)Nullable
reward_idstring (uuid)Nullable
adjustment_reasonstringNullable
One of goodwill, correction, migration, other
created_atstring (date-time)Required
member_idstring (uuid)Required

WalletItemEvent#

idstring (uuid)Required
rewardRewardRequired
Show attributesReward
- idstring (uuid)Required
  Send this as reward_id on previews and redemptions.
- namestringRequired
  For example Free drip coffee.
- descriptionstring
  Short text for the guest.
- image_urlstring (uri)Nullable
  HTTPS image URL.
- kindstringRequired
  points (catalog) or wallet (given to one member). May grow.
  One of points, wallet
- points_costinteger
  Points the reward costs. Only on points rewards; wallet rewards don't have it.
- discountDiscountRequired
  Show attributesDiscount
  - typestringRequired
    One of amount, percent, free_item, bogo
  - amount_centsinteger
    For amount.
  - percentnumber
    For percent.
  - itemsarray of object
    Item scope, by Square variation id.
    Show attributesHide attributes
    pos_item_idstring
    namestring
  - categoriesarray of object
    Category scope.
    Show attributesHide attributes
    pos_category_idstring
    namestring
  - max_itemsinteger
- rulesRulesRequired
  Show attributesRules
  - min_subtotal_centsinteger
    Integer cents.
    Min 0
  - channelsarray of string
    One of app, web
  - location_idsarray of string (uuid)
  - fulfillmentarray of string
    One of pickup, delivery, curbside, dine_in
  - available_timesarray of AvailableTime
    Show attributesAvailableTime
    daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
    startstring
    Local time, HH:MM.
    endstring
    Local time, HH:MM.
  - tier_idsarray of string (uuid)
- starts_atstring (date-time)Nullable
  When the reward becomes available. null means it already is.
- ends_atstring (date-time)Nullable
  When it stops being available. null means no end date.
sourcestringRequired
One of tier, offer, challenge, journey, support, birthday
offer_idstring (uuid)Nullable
statusstringRequired
One of available, reserved, used, expired
issued_atstring (date-time)Required
expires_atstring (date-time)Nullable
used_atstring (date-time)Nullable
order_idstring (uuid)Nullable
member_idstring (uuid)Required

DeletedMember#

idstring (uuid)Required
external_idstringNullable
statusstringRequired
deleted_atstring (date-time)Required

TierChange#

member_idstring (uuid)Required
previous_tierTierRefRequired
Show attributesTierRef
- idstring (uuid)Required
- namestringRequired
tierTierRefRequired
Show attributesTierRef
- idstring (uuid)Required
- namestringRequired
directionstringRequired
One of up, down

CommunicationPreferencesEvent#

email_marketingbooleanRequired
sms_marketingbooleanRequired
push_marketingbooleanRequired
updated_atstring (date-time)Required
sourcestringRequired
Set automatically.
One of app, web, api, unsubscribe_link
member_idstring (uuid)Required

PointsExpiring#

Coming soon.

member_idstring (uuid)
pointsinteger
points_balanceinteger
last_activity_atstring (date-time)
expires_atstring (date-time)

ReferralCompleted#

Coming soon.

idstring (uuid)
referrer_member_idstring (uuid)
referred_member_idstring (uuid)
qualifying_order_idstring (uuid)Nullable
completed_atstring (date-time)

WebhookTest#

webhook_endpoint_idstring (uuid)
messagestring

Test helpers#

TestInStoreOrderRequest#

Used by

POST/v1/test/in_store_ordersrequest body

member_idstring (uuid)Required
location_idstring (uuid)Required
subtotal_centsintegerRequired
Integer cents.
Min 0

TestWalletRequest#

Used by

POST/v1/test/members/{id}/walletrequest body

reward_idstring (uuid)Required

TestWebhookRequest#

Used by

POST/v1/test/webhooksrequest body

typestringRequired
Event type. May grow.
Show valuesHide values
- member.created
- member.updated
- member.deleted
- points.changed
- tier.changed
- reward.issued
- reward.redeemed
- reward.expiring
- order.credited
- order.refunded
- communication_preferences.updated
- webhook.test
- points.expiring
- challenge.joined
- challenge.progressed
- challenge.completed
- referral.completed