# unPLUG Loyalty API

> API for restaurant brands that run unPLUG Loyalty inside their own mobile app or website: members, points, rewards, checkout, offers, challenges, push and in-app messages with unPLUG, webhooks and data sharing. Mobile and web only. The App API is what an app or website needs; the Management API is optional and automates what the unPLUG Dashboard does.

Full text of every page: https://docs.unplugdining.com/llms-full.txt
OpenAPI, App API (what your app, website and server call for guests): https://docs.unplugdining.com/openapi.yaml
OpenAPI, Management API (optional; automates what the unPLUG Dashboard does): https://docs.unplugdining.com/openapi-management.yaml

## Guides: Get started

- [Welcome](https://docs.unplugdining.com/): What the unPLUG Loyalty API does, how your server, your app and unPLUG fit together, and where to start.
- [Quickstart](https://docs.unplugdining.com/quickstart): Create a member, credit a paid order and watch the points and webhooks arrive in the sandbox, in about 15 minutes.
- [Sandbox](https://docs.unplugdining.com/sandbox): The test environment: its host and keys, the seeded demo environment with Square catalog ids, test phone numbers, test helpers, and how to request one.
- [Going live](https://docs.unplugdining.com/going-live): The go-live checklist unPLUG reviews before issuing live keys, and how the review with support works.

## Guides: Build

- [Authentication](https://docs.unplugdining.com/guides/authentication): Secret keys for your server, short-lived member tokens for your app, scopes, key rotation, IP allowlists and what to do if a key leaks.
- [Members and sign-in](https://docs.unplugdining.com/guides/members): Enroll guests from your own sign-up, link guests who already earn at the register, keep profiles and preferences in sync, and delete accounts.
- [Points and rewards](https://docs.unplugdining.com/guides/points-and-rewards): Build the rewards screen: program settings, balance and tier progress, points history, the rewards catalog and wallet, reward rules, and points adjustments from support tools.
- [Checkout and orders](https://docs.unplugdining.com/guides/checkout): Preview rewards for a cart, hold one while the guest pays, credit points when the order is paid, and handle expired holds, retries, timeouts and refunds.
- [Offers and promo codes](https://docs.unplugdining.com/guides/offers): Accept shared and unique promo codes at checkout and show the targeted offers waiting in a guest's wallet.
- [Challenges](https://docs.unplugdining.com/guides/challenges): Goals like "visit 3 times this week" that pay a reward on completion: types, rules, how progress is counted from orders, and how to build the challenges screen in your app.

## Guides: Engage your guests

- [Push and in-app messages](https://docs.unplugdining.com/guides/push-and-in-app): Connect your iOS and Android app to unPLUG so campaigns reach your guests as push notifications and full-screen in-app messages sent from your own Firebase and Apple keys.
- [App events](https://docs.unplugdining.com/guides/app-events): Send what guests do in your app (screens, items, carts, checkout) so unPLUG can trigger journeys and build abandoned-cart and funnel reports.

## Guides: Integrate

- [Webhooks](https://docs.unplugdining.com/guides/webhooks): Get a signed HTTPS request on your server when points, rewards, tiers, orders or members change, and verify, dedupe and process it safely.
- [Data sharing](https://docs.unplugdining.com/guides/data-sharing): Get loyalty data into your own tools through the Reports API, daily CSV exports to SFTP, S3 or GCS, or a Snowflake Secure Data Share.

## Guides: Resources

- [Security](https://docs.unplugdining.com/security): How to keep keys, member tokens, webhooks and guest data safe on your side, what unPLUG does on its side, and how to report a vulnerability.
- [Changelog](https://docs.unplugdining.com/changelog): Every change to the unPLUG Loyalty API and these docs, newest first, with dates, and how breaking changes are announced.
- [Support](https://docs.unplugdining.com/support): How to reach unPLUG developer support, what to include so we can help fast, what support handles today, and response times.

## App API: Overview

- [App API overview](https://docs.unplugdining.com/reference): Every endpoint your app, website and the server behind them call to run unPLUG Loyalty for guests, grouped by area, with base URLs, authentication and the rules every request follows.
- [Data models](https://docs.unplugdining.com/reference/models): Every object the API sends and accepts, field by field: types, required fields, allowed values, and which endpoints use it.

## App API: Basics

- [Errors](https://docs.unplugdining.com/reference/errors): The problem+json error format, what each HTTP status means, and every error code with what to do and whether a retry is safe.
- [Idempotency](https://docs.unplugdining.com/reference/idempotency): Send an Idempotency-Key so retries after a timeout never create a second member, redemption, order or refund. Rules, replay behavior, and a retry recipe.
- [Pagination](https://docs.unplugdining.com/reference/pagination): How list endpoints page with limit and cursor, the response shape, and a loop that reads every page.
- [Rate limits](https://docs.unplugdining.com/reference/rate-limits): Request limits per secret key and per member token, the RateLimit headers, how to handle 429, and how to ask for more.
- [Versioning](https://docs.unplugdining.com/reference/versioning): How 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.

## App API: Identity

- [Member tokens](https://docs.unplugdining.com/reference/member-tokens): Create short-lived member tokens on your server for your app to call unPLUG directly, revoke them on sign-out everywhere, and see what a token can call.
  - [Create a member token](https://docs.unplugdining.com/reference/member-tokens/create-a-member-token): POST /v1/member_tokens
  - [Revoke member tokens](https://docs.unplugdining.com/reference/member-tokens/revoke-member-tokens): POST /v1/members/{id}/revoke_tokens
- [Members](https://docs.unplugdining.com/reference/members): The member object and every members endpoint: create, read, look up, update, delete, communication preferences and merge.
  - [Create a member](https://docs.unplugdining.com/reference/members/create-a-member): POST /v1/members
  - [Get a member](https://docs.unplugdining.com/reference/members/get-a-member): GET /v1/members/{id}
  - [Find members](https://docs.unplugdining.com/reference/members/find-members): GET /v1/members
  - [Update a member](https://docs.unplugdining.com/reference/members/update-a-member): PATCH /v1/members/{id}
  - [Delete a member](https://docs.unplugdining.com/reference/members/delete-a-member): DELETE /v1/members/{id}
  - [Get communication preferences](https://docs.unplugdining.com/reference/members/get-communication-preferences): GET /v1/members/{id}/communication_preferences
  - [Update communication preferences](https://docs.unplugdining.com/reference/members/update-communication-preferences): PATCH /v1/members/{id}/communication_preferences

## App API: Loyalty

- [Program and catalog](https://docs.unplugdining.com/reference/program): Read your loyalty program settings, your locations and your rewards catalog: GET /v1/program, /v1/locations and /v1/rewards.
  - [Get the program](https://docs.unplugdining.com/reference/program/get-the-program): GET /v1/program
  - [List locations](https://docs.unplugdining.com/reference/program/list-locations): GET /v1/locations
  - [List rewards](https://docs.unplugdining.com/reference/program/list-rewards): GET /v1/rewards
  - [Get a reward](https://docs.unplugdining.com/reference/program/get-a-reward): GET /v1/rewards/{id}
- [Activity](https://docs.unplugdining.com/reference/activity): Read a member's points history: the activity entry object and GET activity, from the app or your server.
  - [List activity](https://docs.unplugdining.com/reference/activity/list-activity): GET /v1/members/{id}/activity
- [Wallet](https://docs.unplugdining.com/reference/wallet): Rewards a member already holds, from tiers, offers, birthdays and support: the wallet item object, its statuses and sources, and GET wallet.
  - [List wallet items](https://docs.unplugdining.com/reference/wallet/list-wallet-items): GET /v1/members/{id}/wallet

## App API: Checkout

- [Checkouts and redemptions](https://docs.unplugdining.com/reference/checkouts): The cart object, checkout preview with reason codes, and redemptions: reserve a reward or code while the guest pays, read it, cancel it.
  - [Preview a checkout](https://docs.unplugdining.com/reference/checkouts/preview-a-checkout): POST /v1/checkouts/preview
  - [Create a redemption](https://docs.unplugdining.com/reference/checkouts/create-a-redemption): POST /v1/redemptions
  - [Get a redemption](https://docs.unplugdining.com/reference/checkouts/get-a-redemption): GET /v1/redemptions/{id}
  - [Cancel a redemption](https://docs.unplugdining.com/reference/checkouts/cancel-a-redemption): POST /v1/redemptions/{id}/cancel
- [Orders and refunds](https://docs.unplugdining.com/reference/orders): Credit paid orders so members earn points, read orders back, and refund them: the order object, POST /v1/orders, GET orders, refunds and statuses.
  - [Create an order](https://docs.unplugdining.com/reference/orders/create-an-order): POST /v1/orders
  - [Get an order](https://docs.unplugdining.com/reference/orders/get-an-order): GET /v1/orders/{id}
  - [List orders](https://docs.unplugdining.com/reference/orders/list-orders): GET /v1/orders
  - [Create a refund](https://docs.unplugdining.com/reference/orders/create-a-refund): POST /v1/orders/{id}/refunds

## App API: Challenges

- [Challenges](https://docs.unplugdining.com/reference/challenges): Show challenges in your app or website, load a member's progress and join opt-in challenges, from the app or from your server.
  - [List challenges](https://docs.unplugdining.com/reference/challenges/list-challenges): GET /v1/challenges
  - [List a member's challenges](https://docs.unplugdining.com/reference/challenges/list-a-members-challenges): GET /v1/members/me/challenges
  - [Join a challenge](https://docs.unplugdining.com/reference/challenges/join-a-challenge): POST /v1/members/me/challenges/{id}/join
  - [List a member's challenges from your server](https://docs.unplugdining.com/reference/challenges/list-a-members-challenges-server): GET /v1/members/{id}/challenges
  - [Join a challenge for a member](https://docs.unplugdining.com/reference/challenges/join-a-challenge-for-a-member): POST /v1/members/{id}/challenges/{challenge_id}/join

## App API: Engagement

- [Devices and messages](https://docs.unplugdining.com/reference/devices-and-messages): Register a member's devices for push, fetch full-screen in-app messages, and report impressions, taps and push opens.
  - [Register a device](https://docs.unplugdining.com/reference/devices-and-messages/register-a-device): PUT /v1/members/me/devices/{device_id}
  - [Remove a device](https://docs.unplugdining.com/reference/devices-and-messages/remove-a-device): DELETE /v1/members/me/devices/{device_id}
  - [Get the next message](https://docs.unplugdining.com/reference/devices-and-messages/get-the-next-message): GET /v1/members/me/messages/next
  - [Get a message](https://docs.unplugdining.com/reference/devices-and-messages/get-a-message): GET /v1/members/me/messages/{id}
  - [Report a message event](https://docs.unplugdining.com/reference/devices-and-messages/report-a-message-event): POST /v1/members/me/messages/{id}/events
  - [Get a member's next message from your server](https://docs.unplugdining.com/reference/devices-and-messages/get-a-members-next-message): GET /v1/members/{id}/messages/next
  - [Report a message event from your server](https://docs.unplugdining.com/reference/devices-and-messages/report-a-message-event-for-a-member): POST /v1/members/{id}/messages/{message_id}/events
  - [Report a push open](https://docs.unplugdining.com/reference/devices-and-messages/report-a-push-open): POST /v1/members/me/push_opens
- [App events](https://docs.unplugdining.com/reference/app-events): POST /v1/app_events sends batches of up to 100 in-app behavior events to unPLUG, deduplicated by event_id.
  - [Send app events](https://docs.unplugdining.com/reference/app-events/send-app-events): POST /v1/app_events

## App API: Webhooks

- [Webhook endpoints](https://docs.unplugdining.com/reference/webhook-endpoints): Create, list, update, test and delete webhook endpoints, rotate signing secrets, and read the event log and delivery attempts.
  - [Create a webhook endpoint](https://docs.unplugdining.com/reference/webhook-endpoints/create-a-webhook-endpoint): POST /v1/webhook_endpoints
  - [List webhook endpoints](https://docs.unplugdining.com/reference/webhook-endpoints/list-webhook-endpoints): GET /v1/webhook_endpoints
  - [Get a webhook endpoint](https://docs.unplugdining.com/reference/webhook-endpoints/get-a-webhook-endpoint): GET /v1/webhook_endpoints/{id}
  - [Update a webhook endpoint](https://docs.unplugdining.com/reference/webhook-endpoints/update-a-webhook-endpoint): PATCH /v1/webhook_endpoints/{id}
  - [Delete a webhook endpoint](https://docs.unplugdining.com/reference/webhook-endpoints/delete-a-webhook-endpoint): DELETE /v1/webhook_endpoints/{id}
  - [Send a test event](https://docs.unplugdining.com/reference/webhook-endpoints/send-a-test-event): POST /v1/webhook_endpoints/{id}/test
  - [Rotate the signing secret](https://docs.unplugdining.com/reference/webhook-endpoints/rotate-the-signing-secret): POST /v1/webhook_endpoints/{id}/rotate_secret
  - [List events](https://docs.unplugdining.com/reference/webhook-endpoints/list-events): GET /v1/events
  - [Get an event](https://docs.unplugdining.com/reference/webhook-endpoints/get-an-event): GET /v1/events/{id}
  - [List deliveries](https://docs.unplugdining.com/reference/webhook-endpoints/list-deliveries): GET /v1/events/{id}/deliveries
  - [Redeliver an event](https://docs.unplugdining.com/reference/webhook-endpoints/redeliver-an-event): POST /v1/events/{id}/redeliver
- [Webhook event types](https://docs.unplugdining.com/reference/webhook-events): The webhook envelope and headers, and for each event type when it fires, what data.object holds and a full example payload.

## App API: Testing

- [Test helpers](https://docs.unplugdining.com/reference/test-helpers): Sandbox-only endpoints that simulate register visits, fill and expire wallets, fire webhooks and reset your sandbox brand.
  - [Simulate an in-store order](https://docs.unplugdining.com/reference/test-helpers/simulate-an-in-store-order): POST /v1/test/in_store_orders
  - [Add a wallet item](https://docs.unplugdining.com/reference/test-helpers/add-a-wallet-item): POST /v1/test/members/{id}/wallet
  - [Expire wallet items](https://docs.unplugdining.com/reference/test-helpers/expire-wallet-items): POST /v1/test/members/{id}/expire_wallet_items
  - [Send a test webhook](https://docs.unplugdining.com/reference/test-helpers/send-a-test-webhook): POST /v1/test/webhooks
  - [Reset the sandbox](https://docs.unplugdining.com/reference/test-helpers/reset-the-sandbox): POST /v1/test/reset

## Management API: Overview

- [Management API overview](https://docs.unplugdining.com/management): Optional endpoints that do what the unPLUG Dashboard does: create and run offers and challenges, adjust points, merge members and read reports.
- [Data models](https://docs.unplugdining.com/management/models): Every object the Management API sends and accepts, field by field: types, required fields, allowed values, and which endpoints use it.

## Management API: Guides

- [Run offers from your server](https://docs.unplugdining.com/management/guides/offers): Create, publish, preview and grant offers, print unique code batches and set budgets from your own tools instead of the unPLUG Dashboard.

## Management API: Offers

- [Offers](https://docs.unplugdining.com/management/offers): Create, publish, preview, grant and budget offers from your server, and generate unique promo code batches.
  - [Create an offer](https://docs.unplugdining.com/management/offers/create-an-offer): POST /v1/offers
  - [List offers](https://docs.unplugdining.com/management/offers/list-offers): GET /v1/offers
  - [Get an offer](https://docs.unplugdining.com/management/offers/get-an-offer): GET /v1/offers/{id}
  - [Update an offer](https://docs.unplugdining.com/management/offers/update-an-offer): PATCH /v1/offers/{id}
  - [Publish an offer](https://docs.unplugdining.com/management/offers/publish-an-offer): POST /v1/offers/{id}/publish
  - [Pause an offer](https://docs.unplugdining.com/management/offers/pause-an-offer): POST /v1/offers/{id}/pause
  - [Resume an offer](https://docs.unplugdining.com/management/offers/resume-an-offer): POST /v1/offers/{id}/resume
  - [End an offer](https://docs.unplugdining.com/management/offers/end-an-offer): POST /v1/offers/{id}/end
  - [Preview an offer](https://docs.unplugdining.com/management/offers/preview-an-offer): POST /v1/offers/{id}/preview
  - [Grant an offer](https://docs.unplugdining.com/management/offers/grant-an-offer): POST /v1/offers/{id}/grants
  - [Create a code batch](https://docs.unplugdining.com/management/offers/create-a-code-batch): POST /v1/offers/{id}/code_batches
  - [List codes in a batch](https://docs.unplugdining.com/management/offers/list-codes-in-a-batch): GET /v1/offers/{id}/code_batches/{batch_id}/codes
  - [Void a code batch](https://docs.unplugdining.com/management/offers/void-a-code-batch): POST /v1/offers/{id}/code_batches/{batch_id}/void

## Management API: Challenges

- [Challenges](https://docs.unplugdining.com/management/challenges): Create, publish, pause, end and preview challenges, enroll members by hand and list the templates. Most brands do this in the unPLUG Dashboard.
  - [List challenges](https://docs.unplugdining.com/management/challenges/list-challenges): GET /v1/challenges
  - [Create a challenge](https://docs.unplugdining.com/management/challenges/create-a-challenge): POST /v1/challenges
  - [Update a challenge](https://docs.unplugdining.com/management/challenges/update-a-challenge): PATCH /v1/challenges/{id}
  - [Publish a challenge](https://docs.unplugdining.com/management/challenges/publish-a-challenge): POST /v1/challenges/{id}/publish
  - [Pause a challenge](https://docs.unplugdining.com/management/challenges/pause-a-challenge): POST /v1/challenges/{id}/pause
  - [End a challenge](https://docs.unplugdining.com/management/challenges/end-a-challenge): POST /v1/challenges/{id}/end
  - [Preview a challenge](https://docs.unplugdining.com/management/challenges/preview-a-challenge): POST /v1/challenges/{id}/preview
  - [Enroll members](https://docs.unplugdining.com/management/challenges/enroll-members): POST /v1/challenges/{id}/enrollments
  - [List challenge templates](https://docs.unplugdining.com/management/challenges/list-challenge-templates): GET /v1/challenge_templates

## Management API: Member support

- [Points and member support](https://docs.unplugdining.com/management/member-support): Add or remove points by hand and merge duplicate members. Your support team can do both in the unPLUG Dashboard.
  - [Create a points adjustment](https://docs.unplugdining.com/management/member-support/create-a-points-adjustment): POST /v1/members/{id}/points_adjustments
  - [Merge members](https://docs.unplugdining.com/management/member-support/merge-members): POST /v1/members/{id}/merge

## Management API: Reports

- [Reports](https://docs.unplugdining.com/management/reports): GET /v1/reports/program_summary and GET /v1/reports/rewards: daily member, points, reward and sales totals for your program, by local date.
  - [Program summary](https://docs.unplugdining.com/management/reports/program-summary): GET /v1/reports/program_summary
  - [Rewards report](https://docs.unplugdining.com/management/reports/rewards-report): GET /v1/reports/rewards