Miniso México — Loyalty Integration Backend
The production integration backend of Miniso México's loyalty program, connecting the VTEX storefront, Aptos CRM and the mobile app.
At a glance
- 01Problem
- Miniso México's loyalty program spans three systems: the VTEX storefront, Aptos CRM and a mobile app. Customers register and check their loyalty points from either channel, and each piece of data has to come from the system that owns it.
- 02My responsibility
- I implemented and owned the production backend integration layer on my own, within a high-level architecture defined by my manager: the services connecting VTEX, Aptos CRM and the mobile app, plus persistence, recovery, reconciliation and reporting.
- 03Architectural challenge
- VTEX owns customer registration and Aptos owns loyalty points, while registration through VTEX Master Data V1 could fail intermittently. The backend has to keep both flows moving without becoming a competing source of truth.
- 04Outcome
- A production integration layer through which every registration and loyalty-point flow passed, with scheduled recovery, automatic and manual reconciliation, and business reporting.
Architecture
Three systems, one integration layer
Channels
- VTEX storefrontCustomer registration and loyalty-point queries
- Mobile appCustomer registration and loyalty-point queries
Integration layer
- Integration backend · Node.js / ExpressEvery relevant flow passes through it. Deployed on CentOS 8.
- Orchestrates registration and loyalty-point flows
- Persists registration and transaction data (MongoDB)
- Hourly recovery of pending operations
- Automatic and manual reconciliation
- Business and operational reporting
- Integration backend · Node.js / ExpressEvery relevant flow passes through it. Deployed on CentOS 8.
Systems of record
- VTEXSource of truth for customer registration
- Aptos CRMSource of truth for loyalty points
Source of truth
Architectural principle
Explicit sources of truth
The architecture, defined by my manager, gives each system one responsibility: VTEX is the source of truth for customer registration, and Aptos CRM is the source of truth for loyalty points. The backend I implemented orchestrates the flows and keeps its own records for recovery, reconciliation and reporting, but never an authoritative point balance. When point values differ, Aptos prevails.
Flows and operations
How registration and points move through the backend
Registration flow
- 01VTEX or mobile appThe customer registers
- 02Integration backendReceives and records the registration
- 03VTEX + Aptos CRMCustomer registration in VTEX; loyalty registration propagated to Aptos
Loyalty points flow
- 01VTEX or mobile appRequests loyalty information
- 02Integration backendQueries Aptos on the channel’s behalf
- 03Aptos CRMReturns the current points
- 04Integration backendRelays the response
- 05Requesting channelShows the current points
Registration flow
Registration starts in the VTEX storefront or in the mobile app and always passes through the backend. VTEX controls the customer registration, and the backend propagates the corresponding loyalty registration to Aptos CRM.
Loyalty points flow
When the storefront or the app asks for a customer's points, the backend queries Aptos CRM and returns the current value to the requesting channel. Points are read from Aptos, not from the backend's own data.
Operational resilience
Registration through VTEX Master Data V1 could fail intermittently. I implemented an hourly scheduled job that reprocesses pending registrations and operations in batches, with recoverable operations queued for a later run. Some errors came from outside the backend's control and could not be recovered automatically.
Reconciliation
The backend supports automatic and manual reconciliation of loyalty-related operations and data.
Metrics and reporting
Reporting requested by the Director of E-commerce, generated from the registration and transaction flows: registered users, users who activated their loyalty registration, registered users who did not, the selections made during registration, and transaction-related information.
For technical readers
Technical detail
Context
Miniso México's loyalty program, delivered as a Corebiz project. Customers register through the VTEX storefront or the mobile app and query their loyalty points from either channel. The backend is the integration layer between VTEX, Aptos CRM and the mobile app, and every relevant flow passes through it.
Responsibility
- Implemented the production backend integration layer, working alone on the backend.
- Built the services connecting VTEX, Aptos CRM and the mobile application, including the services the app consumes for registration and loyalty-point queries.
- Implemented the persistence, synchronization, recovery, reconciliation and reporting flows.
- The high-level architecture was defined by my manager; I owned its backend implementation.
Complexity
- Three systems with different responsibilities, and two of them authoritative for different data.
- Intermittent registration failures in VTEX Master Data V1, some of them outside the backend's control.
- Two channels, storefront and mobile app, sharing the same registration and loyalty flows.
Architecture
- REST services in Node.js and Express, consumed by the storefront and the mobile app.
- MongoDB for backend-side data, including user-registration and transaction information. It does not hold the authoritative point balance.
- An hourly scheduled job with a queue for recoverable operations, processed in batches.
- Deployed and operated on CentOS 8.
Alternatives & trade-offs
- Recovery runs on a schedule, so a recovered registration completes on a later hourly run rather than immediately.
- Errors that originate outside the backend cannot be recovered automatically and need manual follow-up, which is what manual reconciliation is for.
Result
- A single integration layer for registration and loyalty points across the storefront, the mobile app and Aptos CRM.
- Clear ownership of data, with Aptos CRM as the authority for points and VTEX for customer registration.
- Scheduled recovery of intermittent registration failures, plus automatic and manual reconciliation.
- Business and operational reporting for the e-commerce leadership.