TilloTech Docs StoreFront Documentation
Documentation for Ember (Tillo StoreFront)—the white-labelled, multi-tenant gift card storefront application.
Mental Model
StoreFront is Tillo’s white-labelled, multi-tenant gift card storefront. It lets Buyers (tenants) offer a branded gift card shop to end customers without building and operating their own site and payment stack, as API Buyers have historically done by integrating directly with the Tillo API.
Tillo is a rewards and incentives platform that connects Buyers (companies who want a gift card offering) with Brands and facilitates gift card sales between them. Core is Tillo’s central Laravel hub and API: it holds the commercial relationship and transaction between Buyer and Brand. StoreFront holds end-customer data—orders, payments, delivery details—that Core does not see, much like an app a Buyer would build themselves. StoreFront places orders against Core using the Buyer’s API key and signed requests, the same integration pattern as a custom Buyer app.
Each tenant (Buyer) gets its own branded storefront on a custom domain (locally: {tenant}.ember.local:8091). All tenants share one application instance and one database; tenant isolation is enforced by foreign keys and request-scoped tenant context resolved from the HTTP host.
Who uses StoreFront?
Buyers arrive with varied business models, for example:
- Cashback providers (e.g. TopCashback, QuidCo)—reward customers after purchase; transactional webhooks let the Buyer credit cashback in their own system.
- Discount-led retailers—gift cards are the primary product; purchases are incentivised with upfront discounts.
- Charities, banks, and loyalty programmes—targeted discounts or cashback for eligible customers.
- Salary Finance and similar—customers pay via an external wallet the Buyer authorises at checkout.
The product aims to support these cases while favouring out-of-the-box configurations over heavy customisation for faster launches.
Purchase schemes and pricing
At the brand level, a Buyer configures how much of their Brand discount to pass to the end user:
| Scheme | Customer experience |
|---|---|
| Discount | Pays less than face value at checkout. |
| Cashback | Pays face value; Buyer awards cashback post-purchase (often via webhook). |
| Face value | Pays full value; Buyer keeps the margin. |
Points (earn/burn) and richer Salary Finance wallet flows are planned extensions; a basic external-wallet checkout already exists for salary-deduction partners.
Relationship to Core and Hub
- Catalogue sync: Brand visibility and denominations are kept in sync from Core via inbound webhooks (brand status and denomination updates) and, for tenants with catalogue sync enabled, scheduled polling every 30 minutes of the Tillo brands API—importing new brands (off the storefront until configured) and refreshing existing ones. Polling predates Core’s outbound webhooks and still runs as a fallback.
- Fulfilment: StoreFront uses Tillo’s asynchronous order APIs only—retryable jobs place orders and poll status (see Fulfillment & Tillo in the domain overview).
- Reporting: StoreFront sends monthly transaction reports to the Buyer; Tillo finance also invoices the Buyer separately. Buyers may opt into outbound transactional webhooks (one per gift card: order ID, item ID, brand, amount, user ID, discount/cashback, etc.) for real-time integration.
- Hub: The legacy Hub bundled in Core shows Buyer–Brand transactions only, not end-user StoreFront data—support has often relied on DB access or ad-hoc APIs. The new Hub (Nuxt, separate from this repo) aggregates Core and StoreFront data for operations and support.
Further reading
- Domain overview — Business and technical domains, how they interact, and where to find key code.
- Key flows — Request path, purchase, auth, checkout selection, and gift purchase diagrams.