Integration Guide
Forloy is a loyalty platform supporting punch, cashback, and discount cards. This guide explains how to integrate your POS system or application with the Forloy API.
Architecture Overview
The diagram below shows the high-level integration flow between your POS system, the Forloy API, and the loyalty engine.
What Happens at Point of Purchase
This diagram maps the business process to the API calls your integration will make. When a customer reaches checkout with a loyalty card, here is the full flow — from scanning the card to completing the transaction. The blue boxes are API calls.
The key insight: every checkout follows the same pattern — look up the card, optionally redeem rewards or cashback, then record the purchase. The card type determines what happens after the purchase is recorded (punches added, cashback earned, or discount applied), but your integration logic stays the same.
Base URL
All API requests should be made to the production base URL. Every endpoint is prefixed with /api/v1/.
https://api.forloy.com/api/v1/Authentication
The Forloy API uses Bearer token authentication. To authenticate, log in with your email and password to receive an access token and a refresh token. Include the access token in the Authorization header of every request.
Authorization: Bearer <your_access_token>Response Format
All responses follow a standard envelope format. Successful responses include a data field, while error responses include an error field.
Success Response
{
"success": true,
"data": { ... },
"meta": {
"request_id": "req_...",
"timestamp": "2026-01-15T10:30:00.000Z"
}
}Error Response
{
"success": false,
"error": {
"code": "CARD_NOT_FOUND",
"message": "No active card found for the given code"
},
"meta": { ... }
}Error Codes
The following error codes may be returned by the API.
| Code | Status | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid authentication token |
| TOKEN_EXPIRED | 401 | The access token has expired |
| INVALID_CREDENTIALS | 401 | Email or password is incorrect |
| LOCATION_NOT_AUTHORIZED | 403 | The authenticated user is not authorized for this location |
| VALIDATION_ERROR | 400 | Request body failed validation |
| CARD_NOT_FOUND | 404 | No active card found for the given code |
| CARD_INACTIVE | 400 | The card exists but is not currently active |
| NO_PENDING_REWARDS | 400 | No rewards are available to claim |
| INSUFFICIENT_BALANCE | 400 | Not enough cashback balance to redeem |
| COOLDOWN_ACTIVE | 429 | A recent transaction was already recorded; cooldown period is active |
| INTERNAL_ERROR | 500 | An unexpected server error occurred |
| DATABASE_ERROR | 500 | A database operation failed |
Card Types
Forloy supports three types of loyalty cards, each with a different reward mechanism.
- Punch cards — Customers earn punches per visit. After reaching the configured threshold, they earn a reward that can be claimed.
- Cashback cards — Customers earn a percentage back on each purchase. The accumulated balance can be redeemed toward future purchases.
- Discount cards — Customers receive a percentage discount on purchases based on their current tier level.
What's Next
Dive deeper into specific topics by following the guides below.
- Authentication — How to authenticate and manage tokens
- Transactions — How to look up cards and record purchases
- Offline Sync — How to batch sync offline transactions
- Rewards & Cashback — How to claim rewards and redeem cashback