For developers
Connect tapja to your POS, shop and CRM
REST API and webhooks for developers of POS systems, shops and CRMs who connect a business on the Favourite Chain plan.
Go to the API reference OpenAPI
Overview
Through the interface, a business’s own system talks directly to tapja. The POS scans the barcode on the card, finds the guest, adds stamps and redeems rewards. With webhooks, tapja reports back as soon as something happens.
What you can do
- Find a card by the serial number in its QR code or barcode:
GET /passes/by-serial/{serial} - Read a card’s state and minimal guest data:
GET /passes/{id},GET /customers/{id},GET /customers - Add stamps or points:
POST /passes/{id}/stamp - Redeem rewards and offers, cancel cards:
POST /passes/{id}/redeem,POST /passes/{id}/redeem-offer,POST /passes/{id}/cancel - Get a sign-up link for new guests:
POST /passes - Read card programmes, locations, employees and figures:
GET /cards,GET /locations,GET /employees,GET /analytics - Send a card notification to guests with marketing consent:
POST /notifications/push - Reconcile deleted guests:
GET /customers/deleted - Receive webhooks for 13 events, such as “Card issued”, “Stamp added”, “Reward ready” and “Guest deleted”
What is deliberately not possible
- Issuing cards without the guest’s consent.
POST /passesreturns a sign-up link; the guest creates the card themselves. - Creating guests without them signing up through that link.
- Bulk-exporting guests. Individual guests are available by ID or by email search.
- Booking package and membership cards. The interface rejects this with
PACKAGE_USE_REQUIREDorMEMBERSHIP_ACTION_REQUIRED.
Requirements
The business is on the Favourite Chain plan. The owner of the business creates the API key. There is no ready-made connector for any specific POS system; the interface is the way to build one.
Quickstart in 5 steps
1. Have an API key created
The owner creates the key on the web under Administration › Integrations, in the app under More › Setup & management › Integrations. tapja asks for their password again, and every owner of the business gets a security email. The key is shown exactly once.
- Scopes: only the ones your system needs (see Scopes).
pass:read,pass:writeandsetup:readare preselected. Withoutsetup:read, your system knows neitheremployeeIdnorlocationId. - Location binding (optional): the key then only books at these locations. The scopes
customer:read,pass:cancelandnotification:sendare not possible for such keys. - Highest actor role (“May act as” in the interface): your system may name employees up to this role. The default is “Employee”.
2. Base URL
https://api.tapja.de/api/v1/public3. Authenticate
Every request carries the key as a bearer token. The key belongs on the server or in the POS only, never in a browser, an app or logs.
Authorization: Bearer sk_live_…4. First call: read a card
Read the card by the serial number from its barcode.
curl https://api.tapja.de/api/v1/public/passes/by-serial/SN8F3K2 \
-H "Authorization: Bearer sk_live_…"{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z"
},
"timestamp": "2026-11-07T10:00:00.000Z"
}5. First booking: add a stamp
A booking always names an employee and a location. GET /employees and GET /locations return their IDs.
curl https://api.tapja.de/api/v1/public/employees -H "Authorization: Bearer sk_live_…"
curl https://api.tapja.de/api/v1/public/locations -H "Authorization: Bearer sk_live_…"The Idempotency-Key is new for every transaction, for example the receipt number. The card’s ID is the id field from step 4.
curl -X POST https://api.tapja.de/api/v1/public/passes/pass_123/stamp \
-H "Authorization: Bearer sk_live_…" \
-H "Idempotency-Key: kasse-3-bon-4711" \
-H "Content-Type: application/json" \
-d '{ "employeeId": "emp_42", "locationId": "loc_mitte", "employeeRef": "Kasse 3" }'{
"data": {
"id": "string",
"cardId": "string",
"customerId": "string",
"serialNumber": "string",
"stampCount": 0,
"pointsBalance": 0,
"tier": "string",
"lastStampAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-07T10:00:00.000Z",
"lifetimeProgress": 0,
"stampCycle": 0
},
"timestamp": "2026-11-07T10:00:00.000Z"
}Every key books for real. Read No test mode before your first test.
Ground rules
Responses and errors
Successful responses come in { data, timestamp }, errors in { error: { code, message } }.
{ "data": { "…": "…" }, "timestamp": "2026-11-07T10:00:00.000Z" }{ "error": { "code": "COOLDOWN_ACTIVE", "message": "Bereits kürzlich gestempelt." } }Branch on code only, never on message. The text is for humans, mostly German, and can change. The interface rejects unknown fields in the request body with 400.
Error codes (72)
| Code | Status | Endpoints |
|---|---|---|
AMOUNT_BELOW_MINIMUM | 400 | POST /passes/{id}/stamp |
AMOUNT_REQUIRED | 400 | POST /passes/{id}/stamp |
AMOUNT_TOO_SMALL | 400 | POST /passes/{id}/stamp |
BAD_REQUEST | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelGET /customersGET /customers/deletedPOST /notifications/push |
CARD_HAS_NO_BALANCE | 400 | POST /passes/{id}/stamp |
COUPON_NOT_COMBINABLE | 400 | POST /passes/{id}/redeem-offer |
IDEMPOTENCY_KEY_INVALID | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
LOCATION_WRONG_COMPANY | 400 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
MEMBERSHIP_ACTION_REQUIRED | 400 | POST /passes/{id}/stampPOST /passes/{id}/redeem |
OFFERS_NOT_ON_CARD | 400 | POST /passes/{id}/redeem-offer |
PACKAGE_USE_REQUIRED | 400 | POST /passes/{id}/stampPOST /passes/{id}/redeem |
PLACEHOLDER_UNKNOWN | 400 | POST /notifications/push |
POINTS_BALANCE_LIMIT | 400 | POST /passes/{id}/stamp |
POINTS_REQUIRED | 400 | POST /passes/{id}/stamp |
QUIET_HOURS | 400 | POST /notifications/push |
REWARD_AUTO_ISSUED | 400 | POST /passes/{id}/redeem |
STAMP_CAP_EXCEEDED | 400 | POST /passes/{id}/stamp |
STAMP_MODE_AMOUNT | 400 | POST /passes/{id}/stamp |
STAMP_MODE_VISIT | 400 | POST /passes/{id}/stamp |
UNAUTHORIZED | 401 | all endpoints |
ACTOR_ROLE_NOT_ALLOWED | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
CARD_FULL | 403 | POST /passes/{id}/stamp |
COMPANY_SUSPENDED | 403 | all endpoints |
COOLDOWN_ACTIVE | 403 | POST /passes/{id}/stamp |
EMPLOYEE_NOT_AT_LOCATION | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
GUEST_EMAIL_UNVERIFIED | 403 | POST /passes/{id}/redeemPOST /passes/{id}/redeem-offer |
LOCATION_NOT_ALLOWED | 403 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
NOT_ENOUGH_POINTS | 403 | POST /passes/{id}/redeem |
OFFER_COOLDOWN | 403 | POST /passes/{id}/redeem-offer |
OFFER_EXHAUSTED | 403 | POST /passes/{id}/redeem-offer |
OFFER_EXPIRED | 403 | POST /passes/{id}/redeem-offer |
OFFER_NOT_ELIGIBLE | 403 | POST /passes/{id}/redeem-offer |
OFFER_NOT_STARTED | 403 | POST /passes/{id}/redeem-offer |
OFFER_WRONG_LOCATION | 403 | POST /passes/{id}/redeem-offer |
PIN_REQUIRED | 403 | POST /passes/{id}/redeemPOST /passes/{id}/redeem-offer |
PLAN_FEATURE_REQUIRED | 403 | all endpoints |
REDEEM_NOT_AT_LOCATION | 403 | POST /passes/{id}/redeem |
REWARD_ALREADY_REDEEMED | 403 | POST /passes/{id}/redeem |
REWARD_EXPIRED | 403 | POST /passes/{id}/redeem |
REWARD_LIMIT_REACHED | 403 | POST /passes/{id}/redeem |
REWARD_MEMBERSHIP_REQUIRED | 403 | POST /passes/{id}/redeem |
REWARD_MIN_PURCHASE | 403 | POST /passes/{id}/redeem |
REWARD_NOT_COMBINABLE | 403 | POST /passes/{id}/redeem |
REWARD_NOT_YET_VALID | 403 | POST /passes/{id}/redeem |
REWARD_QUOTA_EXHAUSTED | 403 | POST /passes/{id}/redeem |
REWARD_THRESHOLD_NOT_REACHED | 403 | POST /passes/{id}/redeem |
REWARD_TIER_REQUIRED | 403 | POST /passes/{id}/redeem |
REWARD_WRONG_LOCATION | 403 | POST /passes/{id}/redeem |
ROLE_NOT_ALLOWED | 403 | POST /passes/{id}/cancel |
SCOPE_MISSING | 403 | all endpoints |
STAMP_LIMIT_REACHED | 403 | POST /passes/{id}/stamp |
CARD_NOT_FOUND | 404 | POST /passesPOST /notifications/push |
CUSTOMER_NOT_FOUND | 404 | GET /customersGET /customers/{id} |
EMPLOYEE_NOT_FOUND | 404 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
NOT_FOUND | 404 | GET /passes/{id}/offersPOST /passes/{id}/redeem-offer |
OFFER_NOT_FOUND | 404 | POST /passes/{id}/redeem-offer |
PASS_NOT_FOUND | 404 | GET /passes/by-serial/{serial}GET /passes/{id}POST /passes/{id}/stampPOST /passes/{id}/redeemGET /passes/{id}/offersPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
REWARD_NOT_FOUND | 404 | POST /passes/{id}/redeem |
CARD_ARCHIVED | 409 | POST /passesPOST /passes/{id}/redeem-offer |
CARD_NOT_AT_LOCATION | 409 | POST /passes |
IDEMPOTENCY_KEY_REUSED | 409 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancelPOST /notifications/push |
LOCATION_DEACTIVATED | 409 | POST /passesPOST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
OFFER_ALREADY_REDEEMED | 409 | POST /passes/{id}/redeem-offer |
OFFER_USED_UP | 409 | POST /passes/{id}/redeem-offer |
PASS_VOIDED | 409 | POST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/redeem-offerPOST /passes/{id}/cancel |
REQUEST_ABANDONED | 409 | POST /passes/{id}/stampPOST /passes/{id}/redeem-offerPOST /notifications/push |
UNPROCESSABLE | 422 | POST /notifications/push |
RATE_LIMITED | 429 | all endpoints |
INTERNAL_ERROR | 500 | all endpoints |
REQUEST_IN_PROGRESS | 503 | all endpoints |
RETRY | 503 | POST /passes/{id}/stampPOST /passes/{id}/redeemPOST /passes/{id}/cancel |
SERVICE_UNAVAILABLE | 503 | GET /passes/by-serial/{serial}GET /passes/{id}GET /passes/{id}/offersGET /customersGET /customers/deletedGET /customers/{id}GET /analyticsGET /cardsGET /locationsGET /employees |
Attribution
- Every booking names
employeeId(an active employee of the business, assigned to the location) andlocationId. - Your system can also send
employeeRef, the cashier’s reference. Use till or staff numbers, not real names. - If your system names an employee with a higher role than the key allows, the interface answers
403 ACTOR_ROLE_NOT_ALLOWED. - Cancelling needs an employee with the role
MANAGERorOWNERand a key whose actor role is at leastMANAGER.
Scopes
Deny by default: a key can only do what its scopes allow. If one is missing, you get 403 SCOPE_MISSING.
| Scope | Label the owner sees | Endpoints |
|---|---|---|
pass:write | Issue cards and add stamps | POST /passesPOST /passes/{id}/stamp |
pass:read | View cards | GET /passes/by-serial/{serial}GET /passes/{id} |
pass:redeem | Redeem rewards | POST /passes/{id}/redeem |
offer:read | View offers | GET /passes/{id}/offers |
offer:redeem | Redeem offers | POST /passes/{id}/redeem-offer |
pass:cancel | Cancel cards | POST /passes/{id}/cancel |
customer:read | View guests | GET /customersGET /customers/deletedGET /customers/{id} |
notification:send | Send messages to guests | POST /notifications/push |
analytics:read | Fetch figures | GET /analytics |
setup:read | Fetch cards, locations and team | GET /cardsGET /locationsGET /employees |
Idempotency
- All
POSTendpoints accept theIdempotency-Keyheader. It applies per API key, is bound to method, path and body, and has at most 255 visible ASCII characters, for example the receipt number. - An identical repeat returns the same response; for the sign-up link, a fresh link. Different content with the same key returns
409 IDEMPOTENCY_KEY_REUSED. While the first request is still running, you get503 REQUEST_IN_PROGRESS. - Only a successful response is stored, for 7 days. Only stamping and redeeming rewards stay protected beyond those 7 days: the same pass with the same key is not booked twice, and a different pass returns
409 IDEMPOTENCY_KEY_REUSED.
Special case: offer cards. On an offer card, the call books a visit. Like redeeming an offer, it is only protected for 7 days through the Idempotency-Key. If the first request breaks off midway, it is never executed again (first 503 REQUEST_IN_PROGRESS, then 409 REQUEST_ABANDONED). Check the state with GET /passes/{id} and, if needed, book again with a new Idempotency-Key.
IDs
IDs in paths have at most 64 characters; longer ones return 400.
Rate limits
- 300 requests per minute per key across all endpoints. Headers:
X-RateLimit-Limit-api,X-RateLimit-Remaining-api,X-RateLimit-Reset-api. - Email search (
GET /customers) additionally 60 per minute per key and 120 per minute per business. Headers:X-RateLimit-Limit-customerLookup,X-RateLimit-Remaining-customerLookup. - Above that you get
429 RATE_LIMITEDwith the standardRetry-Afterheader (seconds) plusRetry-After-apiorRetry-After-customerLookup. - Many invalid keys from one address lead to a temporary block of that address, also
429withRetry-After.
No test mode
There is no sandbox and there are no test keys. Every key books for real: bookings appear in reports and the activity log, and redeemed rewards also in the tax report.
- Test with a separate test card and a separate key with few scopes, and revoke it afterwards.
- Do not use
POST /notifications/pushfor testing; the messages go to real guests. - Webhooks can be tested safely, see Testing webhooks.
Versioning
The version is part of the path (/api/v1). New response fields and new events can appear at any time, so skip unknown fields. Breaking changes only come with a new version and advance notice.
Webhooks
Creating a webhook
The owner creates the webhook under Integrations: a publicly reachable HTTPS address and the selected events. The webhook secret is shown once. It is not the API key: the key opens access to tapja, the secret only verifies the messages that reach you.
Events
| Event | Label | Fields in data |
|---|---|---|
pass.created | Card issued | passId cardId customerId employeeId locationId channel |
pass.stamped | Stamp added | passId cardId stampCount pointsBalance employeeId locationId channel |
pass.redeemed | Reward redeemed | passId rewardId (optional) locationId (optional) |
pass.cancelled | Card cancelled | passId cardId |
pass.reactivated | Card active again | passId customerId |
pass.corrected | Booking corrected | passId field value employeeId (optional) locationId (optional) |
reward.ready | Reward ready | passId cardId rewardIds |
offer.redeemed | Offer redeemed | passId offerId locationId (optional) |
package.used | Package unit used | passId quantity units employeeId locationId (optional) |
customer.created | Guest added | customerId |
customer.deleted | Guest deleted | customerId passIds |
customer.consent_changed | Marketing consent changed | customerId marketingConsent |
campaign.sent | Message sent | campaignId recipients |
There is also the test event ping with the field message, which cannot be subscribed to. All descriptions are in the reference.
Envelope and headers
Every message has the fields id, event, data and timestamp. X-tapja-Delivery equals the id.
{
"id": "evt_3f2a…",
"event": "pass.redeemed",
"data": { "passId": "pass_123", "rewardId": "rw_1" },
"timestamp": "2026-11-07T10:00:00.000Z"
}X-tapja-Event: pass.redeemed
X-tapja-Delivery: evt_3f2a…
X-tapja-Timestamp: 1794045600
X-tapja-Signature: sha256=<hex>
User-Agent: tapja-webhooks/2Verifying the signature
HMAC-SHA256 with the webhook secret over ${X-tapja-Timestamp}.${raw body}, tolerance 300 seconds, constant-time comparison. What counts is the raw body, before any JSON parsing.
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secret) {
const ts = headers['x-tapja-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
const given = String(headers['x-tapja-signature'] ?? '');
return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}import hmac, hashlib, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
ts = headers['X-tapja-Timestamp']
if abs(time.time() - int(ts)) > 300:
return False
expected = 'sha256=' + hmac.new(secret.encode(), f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(headers.get('X-tapja-Signature', ''), expected)Delivery
- Answer quickly with a 2xx and do the work asynchronously. After 10 seconds an attempt counts as failed.
- On a non-2xx, up to 5 retries follow after about 1, 2, 4, 8 and 16 minutes, roughly half an hour in total.
- The
idstays the same across retries. Deduplicate on it. - After 30 failed attempts in a row the webhook pauses, and the owner reactivates it. Events from the pause are not delivered afterwards.
Order
Order is not guaranteed. pass.created can arrive before customer.created, reward.ready before pass.stamped. Order states by timestamp or GET /passes/{id}.
customer.deleted is a final deletion marker: discard later events about this guest and do not recreate them.
Webhooks are not a gapless log. Reconcile critical states with GET where needed.
Renewing the secret
The new webhook secret applies immediately, with no transition period. Renew it at a quiet time and enter the new secret right away.
Testing webhooks
- “Send test” sends
ping, “Send sample event” a sample of a subscribed type. - Tests carry the envelope field
"test": trueand the headerX-tapja-Test: 1. Real events carry neither. All IDs are made up and start withtest_. - Tests are not retried, also reach paused webhooks and never count towards the pause. At most 20 tests per hour per webhook.
- Detect tests by the
testfield and do not book them.
Deletions and privacy
customer.deletednames the IDs of the guest and their cards.- Fetch missed deletions with
GET /customers/deleted?since=…: the last 30 days, IDs only, cursor-based. Ideally reconcile daily and delete in your own system too. - If the whole business is deleted, no
customer.deletedis sent per guest. - Webhooks contain only IDs and counters, no names or addresses.
- Only
GET /customers/{id}and the email searchGET /customersreturn a guest’s email address. Every retrieval is logged. - Marketing from your own system only goes to guests with
marketingConsent: trueandemailVerifiedAtset. GET /employeesreturns the team’s names and roles. Only givesetup:readto systems that need it.
curl "https://api.tapja.de/api/v1/public/customers/deleted?since=2026-11-01T00:00:00.000Z" \
-H "Authorization: Bearer sk_live_…"Responsibility for data
The business is responsible for the data in its own system. Depending on the setup, it needs a data processing agreement with the provider of that system and names the system in its privacy notice.
Contact
Questions about the integration and security findings go to hallo@tapja.de. Include the endpoint, time (UTC) and error code. Never send the API key or the webhook secret.