Environments and Sandbox Testing: live, sandbox, and demo

The Aplauso API supports three isolated data environments. Every business logic endpoint accepts an environment parameter to control which environment is used for reads and writes, and employee, department, and property records can expose a server-resolved resolvedEnvironment to downstream clients.

Environments

Passing the Environment Parameter

As a query parameter:

GET /v2/analytics?type=employee&employeeId=abc123&environment=sandbox

Or in the request body:

{
  "employeeId": "abc123",
  "amount": 10.00,
  "environment": "sandbox"
}

If omitted, the API defaults to live.

Resolved Environment on Entities

Environment is resolved hierarchically for operational entities:

1. Employee activeEnvironment
2. Department activeEnvironment
3. Property activeEnvironment
4. Default live

API responses for employees, departments, and properties can include a resolvedEnvironment field so clients do not need to rebuild the inheritance logic themselves.

This is what kiosk and dashboard should trust when deciding whether to operate in live, sandbox, or demo.

Updating an Entity Environment

Admins can update the active environment through dedicated PATCH endpoints:

PATCH /v2/live/properties/{id}/environment
PATCH /v2/live/departments/{id}/environment
PATCH /v2/live/employees/{id}/environment

Example request body:

{
  "activeEnvironment": "sandbox",
  "cascade": true,
  "reason": "Enable training"
}

These endpoints validate permissions, reject invalid environments, and write audit events for the change.

Data Isolation

Each environment stores data completely separately:

• A tip created in sandbox never appears in live tip queries.
• Guest identity records are shared across environments. The environment boundary applies to the tipped or rated target and to transactional records such as tips, ratings, visits, and dividends.
• Wallet balances are maintained per environment (wallet.live, wallet.sandbox).
• Stripe account IDs are separate per environment (one Express account per user per environment).
• Analytics are computed separately per environment.

Returning from Sandbox to Live

Switching a property, department, or employee from sandbox back to live also clears sandbox transactional data for that scope.

• Sandbox visits, ratings, tips, and related dividend records are purged during the rollback.
• Guest profiles are not purged because they are not environment-specific.
• After the rollback, kiosk and dashboard clients return to live data only.

Testing in Sandbox

To run a full end-to-end test in sandbox:

1. Create a tip with environment: "sandbox".
2. Use the sandbox Stripe keys to create a Payment Intent (the API handles this automatically when environment is sandbox).
3. Use a Stripe test card number to simulate payment:

Any future expiry date, any 3-digit CVC, any billing ZIP.

4. The sandbox Stripe webhook delivers a payment_intent.succeeded event.
5. The tip status updates to 20 (Paid) and dividends are created.
6. Query /v2/tips?environment=sandbox and /v2/dividends?environment=sandbox to verify.

Environment in the Kiosk and Dashboard

The kiosk app (k.aplauso.io) and dashboard (my.aplauso.io) display a colored environment banner when running in a non-live environment:

The environment is controlled server-side per recipient or employee context. If a recipient or signed-in employee resolves to sandbox or demo, kiosk and dashboard automatically route their API traffic and Stripe behavior to the matching environment.

Employee-level overrides can also be applied through supported admin or self-service flows. In all cases, clients should trust the API-resolved environment rather than deriving it from a URL or local-only setting.

Local Development

When running the Firebase emulators locally, the API automatically uses test Stripe keys regardless of the environment parameter. This ensures no real charges occur during local development.

cd api
npm run serve
# Firebase emulators start on localhost:5001

Point your frontend apps at the local emulator base URL for testing:

http://localhost:5001/aplauso-f0501/us-central1/internal/v1/