> ## Documentation Index
> Fetch the complete documentation index at: https://tapcoupon.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> API conventions, authentication, errors, and rate limits.

## Base URL and scope

```text theme={null}
https://tapcoupon.at/api/v1
```

This reference covers the POS API, public card views, and partner sessions. Download the [OpenAPI specification](https://tapcoupon.mintlify.site/api-reference/openapi.json). 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](https://tapcoupon.mintlify.site/authentication.md).

## 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`:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.