Hybrid RevoUnion
The Hybrid RevoUnion system is a digital container deposit management solution for events and venues. It allows issuing reusable containers (cups, plates, etc.) to guests against a deposit fee, and managing their return digitally through a unique transaction code.
The "hybrid" name reflects the combination of physical container handling with a digital token-based tracking system: the guest receives a physical container, but the return and tracking are handled digitally.
General Flow
This flowchart shows the end-to-end POS flow, including how Cheers Loyalty and Hybrid RevoUnion connect.
- Revo product configuration should be cached and refreshed periodically — only fetch once when Hybrid Revo is enabled.
- Cheers Loyalty is independent of Revo products — any user with a QR code goes through the Loyalty flow regardless of basket contents.
- If Hybrid Revo is not enabled, there is no need to check the basket for Revo products — Cheers Loyalty handles everything automatically.
- Hybrid Revo Flow only starts if the feature is enabled and there are Revo products with a remaining balance > 0 after Cheers Loyalty (or without Cheers Loyalty).
How It Works
Environments
| Environment | Base URL |
|---|---|
| Development | https://api.dev.votesess.com |
| Production | https://api.uniqpon.com |
Brand Assets
For up-to-date logo assets, brandbook, and other design resources, see the Brand Assets folder.
Core Concepts
| Concept | Description |
|---|---|
| RevoUnion Category | A reusable container type (e.g. "0.5L Cup", "Plate"). Each category has a name, description, and optional image. |
| Deposit | The amount the guest pays when receiving a container. Refunded upon return. Specified in gross cents. |
| Expiration Time | Duration (in hours) during which a token can be returned. After expiration, the token becomes invalid. |
| Transaction | An issuance event where one or more containers are given to a guest. Each transaction has a unique return code. |
| Transaction Code | A unique 40-character identifier the guest receives. Used to return containers and claim the deposit refund. |
| Short Code | A 6-character (A-Z, 0-9) alternative to the transaction code, meant to be typed in by hand when the QR code cannot be scanned. Accepted wherever the transaction code is. Unique only while the transaction still has returnable containers; after that it may be reused. |
Item Statuses
Each issued container item has one of three statuses:
| Status | Description |
|---|---|
ACTIVE | The container was issued and can be returned within the expiration window. The deposit will be refunded on return. |
RETURNED | The container was successfully returned. The deposit has been refunded. |
EXPIRED | The expiration time passed without the container being returned. The deposit is forfeited. |
The system automatically checks for expired items every 5 minutes and sets them to EXPIRED status, even if the guest never attempts a return.
Business Rules
- One configuration per organization -- Each organization can have exactly one Hybrid RevoUnion configuration.
- Versioning -- Every configuration change creates a new version. Existing transactions remain valid under their original configuration.
- Location-based access -- Devices can only manage transactions for their assigned location.
- Partial returns -- Guests are not required to return all containers at once.
- Cross-device returns -- Containers can be returned at any authorized device at the same location, not just the issuing device.