Developers · version 2026-09-01
Fidélitas API and integrations
Send sales from a till, recognise customers, credit their points and receive Fidélitas events in real time. A JSON REST API, signed webhooks and a single event format, whatever software the data comes from.
Getting started
- The merchant creates a key under Integrations › API and webhooks and picks its scopes (the “Till” preset is recommended).
- Every request carries the header
Authorization: Bearer fidk_…. The key identifies the business: there is no business ID to pass. - Base address:
https://fidelitas.fr/api/v1. JSON responses, ISO 8601 dates, amounts in cents.
What a key can do
customers:readRead customers and their pointscustomers:writeCreate customerstransactions:writeSend sales and refundsloyalty:writeRecord visits and adjust pointsrewards:readRead rewards and the programmerewards:writeRedeem rewardsactions:runRun till codes (reward, points, message)campaigns:sendLaunch campaignswebhooks:manageManage webhooks
Endpoints
| Method and path | What it does | Scope |
|---|---|---|
GET/customers | List / search customers (q, filter, page) | customers:read |
POST/customers | Create a customer (explicit consent)· Idempotency-Key | customers:write |
GET/customers/{id} | A customer's record | customers:read |
GET/customers/{id}/points | Balance, next reward, available rewards | customers:read |
POST/customers/{id}/visits | Record a visit· Idempotency-Key | loyalty:write |
GET/customers/by-token/{cardToken} | Find a customer from their card QR code | customers:read |
POST/transactions | Send a sale (points, visit, matched to the scan); Prefer: respond-async → 202 without waiting for processing· Idempotency-Key | transactions:write |
POST/transactions/{saleId}/refunds | Refund a sale (points removed)· Idempotency-Key | transactions:write |
POST/loyalty/events | Visit without a sale, or points adjustment· Idempotency-Key | loyalty:write |
GET/rewards | Programme tiers and a customer's rewards (customerId) | rewards:read |
POST/rewards/redeem | Redeem a reward (code)· Idempotency-Key | rewards:write |
GET/program | Programme rules (stamps / points, tiers) | rewards:read |
GET/pos/actions | Till codes set up by the merchant | actions:run |
POST/pos/actions/{code} | Trigger a till code for a customer (reward, points, campaign, tag)· Idempotency-Key | actions:run |
GET/campaigns | Campaigns ready to go out (drafts) | campaigns:send |
POST/campaigns/{id}/send | Launch a campaign (whole group) or send it to a single customer (customer)· Idempotency-Key | campaigns:send |
GET/webhooks | Webhook addresses | webhooks:manage |
POST/webhooks | Add an address (secret returned only once)· Idempotency-Key | webhooks:manage |
DELETE/webhooks/{id} | Delete an address | webhooks:manage |
Send a sale
Identify the customer by their Fidélitas ID, their card token (the QR scanned at the till), their email or their phone number. An unknown customer with an email or a phone number is created (without marketing consent). The same sale sent twice only counts once.
curl https://fidelitas.fr/api/v1/transactions \
-H "Authorization: Bearer fidk_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ticket-2026-000123" \
-d '{
"id": "ticket-2026-000123",
"amountCents": 2450,
"currency": "EUR",
"customer": { "cardToken": "ckx…", "email": "lea@exemple.fr" },
"items": [{ "name": "Coupe", "quantity": 1, "unitCents": 2450 }]
}'{
"eventId": "cm…",
"duplicate": false,
"status": "PROCESSED",
"outcome": "visit_created",
"outcomeLabel": "Visite enregistrée",
"customerId": "cm…",
"visitId": "cm…",
"transactionId": "cm…",
"points": 1,
"error": null
}Kiosk or busy till: never wait for Fidélitas. Add the header Prefer: respond-async and the sale is acknowledged with a 202 as soon as it arrives (status RECEIVED) and processed straight after. Send it without holding up the payment, with a 2-second timeout and a retry using the same Idempotency-Key if it fails: never a duplicate. The result comes back through the transaction.created webhook and under Integrations › Journal. Pass terminalId (the name of the station, as shown in the till page or in Comptoir) so that a sale with no customer is only matched to the card scanned at that station.
Refund: POST /transactions/ticket-2026-000123/refunds with { "refundId": "r-1", "amountCents": 2450 }. The matching points are removed (never below zero).
How loyalty rules are applied
- If the customer's card was scanned just before (within 30 minutes), the amount is attached to that visit: no double counting.
- Several purchases on the same day: a single visit (stamp card: one stamp only; points card: the points add up).
- Sale with no customer: attached to the only card scanned in the preceding minutes at the same station (
terminalId), otherwise recorded without points (the revenue is still known). The customer can also attach the receipt themselves from their card, using the order number (idof the sale). - The Wallet card is updated and the merchant's automations fire just as they would for a visit entered at the till.
“Other till” webhook
For a till that can call a web address (or through Zapier / Make): the merchant creates an “Other till” connection and gives you an address and a secret. Send one event (or { "events": [ … ] }, 100 at most), signed.
Event types
sale.completedSalesale.refundedRefundcustomer.upsertedCustomer created or updatedcustomer.visitVisitloyalty.adjustedPoints adjusted
{
"id": "evt-000123",
"type": "sale.completed",
"occurredAt": "2026-09-23T10:42:00Z",
"data": {
"saleId": "ticket-000123",
"amountCents": 1250,
"currency": "EUR",
"customer": { "externalId": "C-981", "phone": "+33612345678", "firstName": "Léa" },
"locationExternalId": "boutique-1"
}
}import crypto from "node:crypto";
const body = JSON.stringify(event);
const t = Math.floor(Date.now() / 1000);
const v1 = crypto.createHmac("sha256", SECRET).update(`${t}.${body}`).digest("hex");
await fetch(WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json", "Fidelitas-Signature": `t=${t},v1=${v1}` },
body,
});A 202 response gives the number of events accepted and duplicates ignored. A signature that is missing, wrong or more than 5 minutes old: 401. Invalid format: 422 with the offending field. The outcome of every event is visible to the merchant in their log.
Outgoing webhooks
Fidélitas calls your (https) addresses on every event. If a call fails (any response other than 2xx, or no response within 10 seconds), it is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and then 24 h. An address that fails 50 times in a row is paused.
customer.createdNew customercustomer.updatedCustomer updatedvisit.createdVisit recordedtransaction.createdSale received from a tillpoints.addedPoints addedreward.unlockedReward unlockedreward.redeemedReward redeemedwallet.updatedWallet card addedautomation.triggeredAutomatic message sent
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
const received = Buffer.from(parts.v1 ?? "");
return received.length === expected.length && crypto.timingSafeEqual(expected, received);
}Headers: Fidelitas-Signature, Fidelitas-Event-Id (the same on every retry: use it to de-duplicate), Fidelitas-Event-Type.
Errors, limits, idempotency
- Errors come as
{ "error": "message lisible", "code": "VALIDATION_ERROR", "details": [ … ] }— 400 unreadable request, 401 invalid key, 403 missing scope (INSUFFICIENT_SCOPE), 402 inactive subscription, 404 not found, 409 conflict, 422 invalid data, 429 rate limit reached. - 600 requests per minute per business across all addresses; creating a customer (120), till codes (300), sending a campaign and adding a webhook (30) each have their own limit on top. Headers
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-ResetandRetry-After. Idempotency-Keyon writes: the same key with the same request returns the same response for 24 hours (headerIdempotent-Replayed: true), with no duplicate effect; with a different request: 422.- Every response carries
Fidelitas-Api-VersionandX-Request-Id(quote it to support). Breaking changes will go through a new version, announced in advance.
Connected tills
Connected from the merchant area, with no development work. Any other till connects through the API above, or custom-built, on quote (Pro plan). Tills available today:
- Hiboutik Availablereal time · customer sent
Are you a till vendor interested in a native connector? Write to us.