Coffee Kit loyalty: product and developer specification
12 November 2026. Full product concept and acceptance requirements. The website demonstrates local sample state; no rewards provider, points ledger or Shopify discount has been connected.
Product promise
Make every coffee bring customers closer to the next one. A clear program, visible progress and a reward that is easy to use. Loyalty is a first-class app destination and customer experience. Integration is an implementation choice beneath that experience.
The coffee-specific opportunity is connecting a meaningful purchase unit, coffee preferences, subscription behavior and a suitable next reward. A decorative stamp card alone is not a differentiated loyalty system. Existing providers already handle important earning/redemption jobs; test the complete task against them.
Program templates
| Template | Earning unit | Reward | Distinct requirements |
|---|---|---|---|
| Coffee bags | Eligible paid bag quantity, with explicit size/multipack rules | Fixed-value voucher or a specified bag | Product/variant exclusions, discounted-item rules, partial returns and reward-stock availability |
| Coffee points | Eligible spend or a fixed award per order | Defined exchange rate and eligible rewards | Currency/tax/shipping basis, rounding, minimum redemption and balance history |
| Café stamps | Eligible prepared drinks or qualifying visits | Defined free drink/upgrade | POS customer identification, staff workflow, qualifying item rules and channel parity |
| Member benefits | Membership/subscription status or successful deliveries | A stated perk or earning multiplier | Status changes, failed/skipped payments, discount stacking and future-contract restrictions |
These are separate templates. Six general-purpose points are not automatically six bags, and six visits are not six drinks. Start with one deliberately configured program; do not manufacture a universal score across channels.
Merchant navigation and setup
Loyalty → Overview / Program / Rewards / Members / Activity / Connections. These can begin as tabs within one destination. Overview shows actual program status and exceptions, not invented uplift. Program setup follows six steps:
- Choose the promise: bag stamps, spend points or café program. Name it in customer language and choose the earning/reward units.
- Choose eligible purchases: products/variants, channels, bag sizes, bundles and subscription orders. Explain whether one 1kg bag counts as one bag or another explicitly configured unit. Do not infer four stamps merely because it weighs four times 250g.
- Set earning: quantity or per-order/spend rule, award timing and exclusions. Show a preview for a one-bag order, a two-bag order, a free reward and a subscription renewal.
- Set the reward: threshold, reward value/product, minimum purchase, expiry if used, shipping treatment and permitted discount combinations. A free-product reward needs an available eligible product and an explicit fallback.
- Set presentation and follow-up: shared Coffeetale card/page, progress wording, signed-in/guest state and optional provider email handoff. Marketing enrollment is a separate choice.
- Review and activate: compare configured intent with the operational provider/ledger. States are Draft, Needs provider setup, Verified configuration and Live. Saving local intent is not activation.
For a provider lacking program-write APIs, the initial flow guides setup in that provider and exposes only capabilities actually verified. The full Coffee Kit builder is the designed destination; unsupported writes must not be represented as live controls in a shipped integration.
Customer surfaces
| Surface | Required information/action |
|---|---|
| Coffee card / PDP | Plain explanation of what this purchase earns, only where eligibility is resolved; no false “earn” badge on excluded/free items |
| Reward card | Current available progress, threshold, exact reward and next qualifying action; text alternative to stamp graphics |
| Rewards page/account | Available rewards, earning history, redeemed/expired states, terms and supported redemption |
| Cart | Whether the chosen reward applies, the actual discount and any conflict with another offer; customer can remove/reselect |
| Subscription account | Whether paid renewals earn; current progress; supported next-order redemption or a clear separate-shop purchase route |
| Café/QR | Identified customer's supported reward view; QR is an entry point, not proof of a POS transaction or identity |
The sample prototype can start at 4 of 5 eligible bags and show “Your next qualifying bag earns €10 toward a future order.” That is a voucher promise, not “a free coffee.” A separate café template can say “Buy five eligible drinks; the sixth is free” only when its reward truly supplies that drink under the stated conditions.
A successful demo journey is: inspect program → select whether renewals qualify → record a sample eligible purchase → see progress/reward update → redeem in the sample → inspect history → reverse a sample purchase under the displayed policy. All values and actions are labeled as sample state, and reset returns the same fixtures.
Earning, spending and reversals
Define award timing. A conservative proposed bag rule awards after paid and fulfilled eligibility is established; the selected provider may support a different documented event. Display pending versus available rewards if there is a delay. Failed payments and skipped subscription cycles do not earn paid-purchase stamps. A later successful payment must earn once.
Per-bag earning counts eligible line quantities. A box containing two eligible coffees and a mug should not earn three coffee stamps. Parent and component lines must not both count the same physical bag. A fully discounted reward must follow the explicit eligibility rule; do not accidentally create an unlimited earn/redeem loop.
Refunds require three distinct decisions: reverse earned units, restore previously spent units, and invalidate an unused issued reward. A partial item refund reverses the corresponding eligible units. A money-only adjustment may lack enough line detail and should become an exception. If the customer already spent the earned reward, follow a documented deficit/review policy rather than silently issuing another reward. Never automatically charge money to settle a points deficit.
Pausing a reward does not necessarily revoke previously issued codes. Simultaneous redemptions need a ledger lock or equivalent provider guarantee. A successful API response and an applicable Shopify discount are different states. Reconcile failures before retrying.
Subscription and POS integration
Subscription earning and subscription redemption are separate capabilities. A provider may award points for renewal orders while lacking a way to apply a reward to the next contract charge. Show that distinction. A redemption must identify the effective cycle and confirm applicable discounts, product eligibility and price; it cannot simply add a discount badge to the preview.
Customers should understand whether subscribe-and-save and loyalty benefits combine. Merchant configuration previews the combined commercial effect. Avoid duplicate awards from quantity, general purchase and subscription-specific rules processing the same order.
POS requires an attached customer and a supported staff workflow. Guest purchases, later identification, customer merges, refunds and offline events need explicit treatment. A shared online/POS balance is a provider capability to verify, not a consequence of using the same colors. Café stamps can remain a separate program if prepared drinks and online beans have different economics.
Provider route and ownership alternative
The current evidence identifies Appstle's $10–$30 provider-interface route as the most promising affordable starting point. Its custom API add-on price is unpublished. Rivo and Smile reserve their custom developer interfaces for substantially more expensive tiers. A customer-facing Coffeetale balance/redemption card therefore requires either verified commercial/API access or an owned ledger; a basic provider plan alone does not supply it.
Choose between:
- Provider experience: fastest way to deliver a functional program. Coffee Kit supplies coffee-aware setup guidance, compatible presentation links and shared catalog context, while the provider operates the ledger.
- Provider API: Coffee Kit presents the complete interface, with the provider as authority. Confirm authentication, balances, reward issuance, redemption, reversal and events, as well as the actual bill.
- Narrow owned program: one shop/customer identity, one channel, eligible paid-bag quantities, one reward, durable transactions and explicit reversals. Add more channels/programs only after the basic loop is reliable.
An owned program is a legitimate strategic option if custom experience and predictable merchant economics justify the maintenance. It is additional engineering beyond the initial-app budget; it should not be buried inside subscription work. Do not build a general referral/VIP/affiliate platform by accident.
Data and API contract
The operational engine owns the balance. Coffee Kit records a versioned ProgramConfig, product eligibility, presentation settings, provider capability map and a timestamped mirror where needed. An owned implementation additionally requires immutable RewardTransactions with an idempotency key, source order/line/refund, customer/shop identity, units, status and linked reversal; RewardEntitlements with issuance/redemption state; and audited staff adjustments.
Use Shopify customer identity plus shop scope and a provider mapping. Email is not an immutable key. A customer merge requires explicit reconciliation of history, outstanding rewards and duplicate bonuses. Public product metafields must never expose a customer's reward balance, private preferences or transaction history.
A proposed agency interface reads authenticated customer progress and available rewards and requests validated redemption through the engine. It never trusts a browser-submitted balance. Public program descriptions can be cached separately from private member state. Export/migration includes auditable balances and liabilities, not just a decorative stamp count.
Acceptance cases and value measurement
Test one versus multiple eligible bags; excluded products and mixed boxes; same order delivered twice; initially failed renewal later paid; skip/cancel; initial plus recurring subscription awards; fully discounted reward purchases; partial line refunds; money-only refunds; redemption followed by refund; two concurrent redemptions; missing reward stock; incompatible discounts; customer merge; guest/POS identification; revoked access and uninstall.
Track eligible customers, earners, available versus issued versus redeemed rewards, delivery failures and net discount cost. Attributed repeat orders are not proven incremental orders. A hypothetical €10 reward can exceed the contribution on the next bag; merchant margin and long-term repeat value must be considered. A free bag's cost and foregone sale opportunity differ from its retail price. The app should make reward economics legible without inventing a retention result.
Reward exposure and stock planning
Physical free-coffee rewards need planning alongside subscriptions. Distinguish issued unredeemed entitlements, customers approaching a threshold, and redeemed rewards already in orders. A monetary voucher is not a reserved bag. Show demand scenarios, shortages and operational alerts while preserving earned entitlements. See the demand/inventory specification for event flows, records, forecasting limits and acceptance cases.
Source: loyalty-product-specification.md The complete Markdown handoff and private datasets remain in the local project. This web edition includes selected supporting visuals and scenario downloads.