Loyalty & rewards app

Hand it to an agent

This prompt briefs an AI coding agent to implement the entire recipe against the live docs — authentication, every endpoint, and webhooks.

Build a loyalty & rewards Ewity App called <name>.

Setup: Ewity app with API key <EWITY_APP_KEY>, approved scopes r/read-customer + r/manage-loyalty-customer + r/history-bill, webhook signing secret <whsec_…>. API base https://api.ewitypos.com/apps-v1 with headers Authorization: Bearer <EWITY_APP_KEY> and X-Ewity-Store: <store_id> (from the app.installed envelope). Docs: https://ewity-api.readme.io/docs/building-apps, https://ewity-api.readme.io/docs/apps-webhooks; App UI protocol via the in-ewity-app-ui recipe prompt.

1) Webhook receiver (signature-verified, deduped on envelope id): app.installed → persist store_id + default earn rules; bill.created → if the bill has a customer, compute earn from the bill total (GET /sales/bills/{id} for detail), POST /customers/{id}/loyalty-adjustment with the earned points; claw back on bill.voided / bill.refunded (the envelope links the parent bill); customer.created/updated → upsert your mirror.
2) App UI endpoint (GET {app_ui_url}): verify X-Ewity-Signature + X-Ewity-Context JWT. Serve tabs: "Rewards" (search field + customer balance DetailCard + redeem Form posting app_action redeem with {customer_id, points}), "History" (Table of recent earns/redeems from your DB). Handle POST actions: validate balance, apply the redemption as a negative loyalty-adjustment, respond {"toast":{"tone":"success","message":"Redeemed"},"refresh":true}.
3) Rules engine: points per currency unit + optional multiplier windows; nightly expiry job that pushes negative adjustments; keep Ewity the balance of record (never trust only your mirror).
4) Admin mini-site for the merchant to tune earn rules per store (authenticate installs by store_id).

…or follow the build, step by step

1. 1

   Create the app & request scopes

   Loyalty needs customers and sales — and nothing else.

   • Request `r/read-customer`, `r/manage-loyalty-customer` (loyalty balances + programs) and `r/history-bill` (to award on spend). Set the category to Loyalty.
   • Merchants approve exactly that list at install; if you later need more, bump your requested roles and installs are prompted to re-authorize.

   Read the docs for this step
2. 2

   Award points on every sale

   bill.created is your earning engine.

   • POST{your_webhook_url}Receive bill.created / customer.created
   • GET/apps-v1/sales/bills/{id}Bill detail (customer + totals)
   • POST/apps-v1/customers/{id}/loyalty-adjustmentAdjust loyalty balance

   • Subscribe to `bill.created` and `customer.created`. Verify the envelope signature, dedupe on the envelope id.
   • When a bill lands with a customer attached, compute the earn (your rules — points per currency unit, multipliers, streaks) and write it back with a loyalty adjustment so the balance shows everywhere in Ewity, not just in your app.
   • Refund and void bills should claw points back — branch on bill type before awarding.

   Read the docs for this step
3. 3

   Rewards screen inside the POS

   Balance, history and redeem — rendered natively in Ewity via the App UI.

   • GET{app_ui_url}?page=homeServe the App UI document
   • POST{app_ui_url}Handle redeem actions

   • Serve a tabbed App UI: a customer search + balance view (Table + DetailCard), a redeem Form that posts an app_action back to you, and a history tab. The 'Render your app's UI inside Ewity' recipe carries the full protocol spec.
   • Redeem = validate the balance server-side, apply the discount as a loyalty adjustment, then return a success toast + refresh.
   • The X-Ewity-Context JWT on every UI request tells you which merchant, store and cashier you're serving — no separate login.
4. 4

   Close the loop

   Expiry, tiers and campaigns run on your side; Ewity stays the balance of record.

   • GET/apps-v1/customersList customers (paginated)

   • Nightly job: expire points, recompute tiers, and push the deltas as loyalty adjustments.
   • Use `customer.updated` to keep your mirror fresh instead of re-listing everyone.