Skip to content

App API

Every endpoint your app, your website and the server behind them call to run loyalty for guests, grouped by what it's for. Each one lists who can call it, the request and response models, and examples in cURL, Node.js and Python.

Creating and running offers and challenges, adjusting points and reports happen in the unPLUG Dashboard, so they aren't here. To automate them from your own tools, see the Management API.

Productionhttps://api.unplugdining.com/v1uk_live_ keys

Sandboxhttps://sandbox.api.unplugdining.com/v1uk_test_ keys, connected to our Square sandbox

Formatapplication/jsonUTF-8, amounts in integer cents, times in UTC ISO 8601

Who can call what#

Every endpoint is marked with the credential it accepts.

Secret keyLives on your server only. Each key carries scopes such as members:write, shown on every endpoint. Member tokenLives in your app for 15 minutes and acts for one member. Your server mints it.

Calls that create or change money or points need an Idempotency-Key header. Errors follow RFC 9457, lists use cursor pagination, and /v1 only gets additive changes (versioning). The full contract is in openapi.yaml. Almost every member token call also has a server version, for a server-to-server integration.

53 endpoints: 48 available at launch, 5 coming soon.

Basics#

Rules every request follows.

ErrorsThe problem+json error format, what each HTTP status means, and every error code with what to do and whether a retry is safe.IdempotencySend an Idempotency-Key so retries after a timeout never create a second member, redemption, order or refund. Rules, replay behavior, and a retry recipe.PaginationHow list endpoints page with limit and cursor, the response shape, and a loop that reads every page.Rate limitsRequest limits per secret key and per member token, the RateLimit headers, how to handle 429, and how to ask for more.VersioningHow the API is versioned: /v1 in the path, additive changes only within v1, breaking changes in /v2 with 12 months of overlap, and webhook payload versions.

Identity#

Enroll guests, keep profiles in sync and give your app a short-lived token for one member.

POST/v1/member_tokensCreate a member token POST/v1/members/{id}/revoke_tokensRevoke member tokens

POST/v1/membersCreate a member GET/v1/members/{id}Get a member GET/v1/membersFind members PATCH/v1/members/{id}Update a member DELETE/v1/members/{id}Delete a member GET/v1/members/{id}/communication_preferencesGet communication preferences PATCH/v1/members/{id}/communication_preferencesUpdate communication preferences

Loyalty#

The program, a member's points history and the rewards in their wallet.

Program and catalog

GET/v1/programGet the program GET/v1/locationsList locations GET/v1/rewardsList rewards GET/v1/rewards/{id}Get a reward

GET/v1/members/{id}/activityList activity

GET/v1/members/{id}/walletList wallet items

Checkout#

Apply rewards to a cart, hold one while the guest pays, credit points and handle refunds.

Checkouts and redemptions

POST/v1/checkouts/previewPreview a checkout POST/v1/redemptionsCreate a redemption GET/v1/redemptions/{id}Get a redemption POST/v1/redemptions/{id}/cancelCancel a redemption

Orders and refunds

POST/v1/ordersCreate an order GET/v1/orders/{id}Get an order GET/v1/ordersList orders POST/v1/orders/{id}/refundsCreate a refund

Challenges#

Show challenges, load progress and join opt-in challenges. Offers reach your app as codes and wallet items at checkout.

GET/v1/challengesList challengesSoon GET/v1/members/me/challengesList a member's challengesSoon POST/v1/members/me/challenges/{id}/joinJoin a challengeSoon GET/v1/members/{id}/challengesList a member's challenges from your serverSoon POST/v1/members/{id}/challenges/{challenge_id}/joinJoin a challenge for a memberSoon

Engagement#

Register devices for push, fetch in-app messages and send app events for campaigns.

Devices and messages

PUT/v1/members/me/devices/{device_id}Register a device DELETE/v1/members/me/devices/{device_id}Remove a device GET/v1/members/me/messages/nextGet the next message GET/v1/members/me/messages/{id}Get a message POST/v1/members/me/messages/{id}/eventsReport a message event GET/v1/members/{id}/messages/nextGet a member's next message from your server POST/v1/members/{id}/messages/{message_id}/eventsReport a message event from your server POST/v1/members/me/push_opensReport a push open

POST/v1/app_eventsSend app events

Webhooks#

Endpoints that receive events, and every event type unPLUG sends.

Webhook endpoints

POST/v1/webhook_endpointsCreate a webhook endpoint GET/v1/webhook_endpointsList webhook endpoints GET/v1/webhook_endpoints/{id}Get a webhook endpoint PATCH/v1/webhook_endpoints/{id}Update a webhook endpoint DELETE/v1/webhook_endpoints/{id}Delete a webhook endpoint POST/v1/webhook_endpoints/{id}/testSend a test event POST/v1/webhook_endpoints/{id}/rotate_secretRotate the signing secret GET/v1/eventsList events GET/v1/events/{id}Get an event GET/v1/events/{id}/deliveriesList deliveries POST/v1/events/{id}/redeliverRedeliver an event

Webhook event types

EVTmember.createdmember.created EVTmember.updatedmember.updated EVTmember.deletedmember.deleted EVTpoints.changedpoints.changed EVTpoints.expiringpoints.expiringSoon EVTtier.changedtier.changed EVTreward.issuedreward.issued EVTreward.redeemedreward.redeemed EVTreward.expiringreward.expiring EVTorder.creditedorder.credited EVTorder.refundedorder.refunded EVTcommunication_preferences.updatedcommunication_preferences.updated EVTchallenge.joinedchallenge.joinedSoon EVTchallenge.progressedchallenge.progressedSoon EVTchallenge.completedchallenge.completedSoon EVTreferral.completedreferral.completedSoon EVTwebhook.testwebhook.test

Testing#

Sandbox-only helpers for in-store orders, wallet items and test webhooks.

POST/v1/test/in_store_ordersSimulate an in-store order POST/v1/test/members/{id}/walletAdd a wallet item POST/v1/test/members/{id}/expire_wallet_itemsExpire wallet items POST/v1/test/webhooksSend a test webhook POST/v1/test/resetReset the sandbox