API overview

API conventions, authentication, errors, and rate limits.

Base URL and scope

https://tapcoupon.at/api/v1

This reference covers the POS API, public card views, and partner sessions. Download the OpenAPI specification. The specification and examples were checked against the current backend on October 2, 2026.

Authentication

API-key routes require Authorization: Bearer YOUR_API_KEY and X-Device-ID. Card operations also require X-Employee-Token. Public card views and payment-session create/status routes are unauthenticated. Session info requires the API key and device id. See authentication.

Units and identifiers

Value	Meaning
Coupon amount, amountLeft, and fees	Integer cents; 500 means €5.00
Points/status request amount	Integer points; not cents
Card/template lifetime	Integer hours from createdAt; 0 means unlimited
Status durationDays	Rolling points window in days
Reward cooldownHours	Hours between redemptions of the same reward on the same card
cardId	Printed/digital identifier that can be reused across card instances
Card id, template/program/reward ids	Database object ids

Timestamps use ISO 8601 date-time strings. Card types are blankCard, couponCard, loyaltyCard, pointsCard, and statusCard. Partner sessions use the shorter values coupon, loyalty, points, and status.

Success messages can contain $t(...) translation expressions. Use structured fields such as success and rewardEarned for application logic.

Errors

Handler errors include a machine-readable errorCode:

{
  "error": "reward is on cooldown",
  "errorCode": "REWARD_COOLDOWN"
}

Authentication middleware may return only error. Rate-limit responses may use a different body; handle the HTTP status first.

Status	Typical reason
400	Invalid body, wrong card type, insufficient balance/points, expired card, location mismatch
401	Missing/invalid key or device id, credentials, or employee token
403	Key bound to another device, archived location, employee location restriction, account/test restriction
404	Card, template, or reward not found
409	REWARD_COOLDOWN
410	Archived card or unavailable payment session
422	Inactive, fully used, or ineligible card reconfiguration
429	Rate limit exceeded
500	Server error

Rate limits

Limits are applied per IP and can stack. API-key routes share a limit of 300 requests per minute. Login and credential validation add a 20-per-minute limit. Session info adds a 60-per-minute limit.

Public session creation allows 30 requests per minute; public session status allows 60. Public card and card-reward views each allow 10 requests per minute. Back off on 429.

Card writes do not expose an idempotency-key parameter. After an uncertain network result, inspect card state or history before retrying a charge, stamp, or award.