Request my free trial

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

  1. The merchant creates a key under Integrations › API and webhooks and picks its scopes (the “Till” preset is recommended).
  2. Every request carries the header Authorization: Bearer fidk_…. The key identifies the business: there is no business ID to pass.
  3. 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 points
  • customers:writeCreate customers
  • transactions:writeSend sales and refunds
  • loyalty:writeRecord visits and adjust points
  • rewards:readRead rewards and the programme
  • rewards:writeRedeem rewards
  • actions:runRun till codes (reward, points, message)
  • campaigns:sendLaunch campaigns
  • webhooks:manageManage webhooks

Endpoints

Method and pathWhat it doesScope
GET/customersList / search customers (q, filter, page)customers:read
POST/customersCreate a customer (explicit consent)· Idempotency-Keycustomers:write
GET/customers/{id}A customer's recordcustomers:read
GET/customers/{id}/pointsBalance, next reward, available rewardscustomers:read
POST/customers/{id}/visitsRecord a visit· Idempotency-Keyloyalty:write
GET/customers/by-token/{cardToken}Find a customer from their card QR codecustomers:read
POST/transactionsSend a sale (points, visit, matched to the scan); Prefer: respond-async → 202 without waiting for processing· Idempotency-Keytransactions:write
POST/transactions/{saleId}/refundsRefund a sale (points removed)· Idempotency-Keytransactions:write
POST/loyalty/eventsVisit without a sale, or points adjustment· Idempotency-Keyloyalty:write
GET/rewardsProgramme tiers and a customer's rewards (customerId)rewards:read
POST/rewards/redeemRedeem a reward (code)· Idempotency-Keyrewards:write
GET/programProgramme rules (stamps / points, tiers)rewards:read
GET/pos/actionsTill codes set up by the merchantactions:run
POST/pos/actions/{code}Trigger a till code for a customer (reward, points, campaign, tag)· Idempotency-Keyactions:run
GET/campaignsCampaigns ready to go out (drafts)campaigns:send
POST/campaigns/{id}/sendLaunch a campaign (whole group) or send it to a single customer (customer)· Idempotency-Keycampaigns:send
GET/webhooksWebhook addresseswebhooks:manage
POST/webhooksAdd an address (secret returned only once)· Idempotency-Keywebhooks:manage
DELETE/webhooks/{id}Delete an addresswebhooks: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.

Request
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 }]
  }'
201 response
{
  "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 (id of 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.completedSale
  • sale.refundedRefund
  • customer.upsertedCustomer created or updated
  • customer.visitVisit
  • loyalty.adjustedPoints adjusted
Body (sale.completed)
{
  "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"
  }
}
Signature (Node.js)
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 customer
  • customer.updatedCustomer updated
  • visit.createdVisit recorded
  • transaction.createdSale received from a till
  • points.addedPoints added
  • reward.unlockedReward unlocked
  • reward.redeemedReward redeemed
  • wallet.updatedWallet card added
  • automation.triggeredAutomatic message sent
Verifying the signature (Node.js)
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-Reset and Retry-After.
  • Idempotency-Key on writes: the same key with the same request returns the same response for 24 hours (header Idempotent-Replayed: true), with no duplicate effect; with a different request: 422.
  • Every response carries Fidelitas-Api-Version and X-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.

Your cookies, your choice. Only cookies the site needs, cookie-free audience measurement, no advertising cookies. Privacy policy ·