> For the complete documentation index, see [llms.txt](https://stamply.gitbook.io/stamply-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stamply.gitbook.io/stamply-knowledge-base/api/stamply-api.md).

# Stamply API

Die Stamply API ermöglicht Eigenintegrationen um Loyalty-Aktionen programmgesteuert auszuführen.

**API Reference (OpenAPI / ReDoc):**\
Alle Endpoints, Request/Response-Schemas, Parameter und Beispiele findest du hier:

{% embed url="<https://docs.stamply.ch>" %}

### Authentifizierung (API Key)

Alle Requests an die Stamply API müssen mit einem API Key authentifiziert werden.

**So verwendest du den API Key**

Der API Key wird als HTTP Header mitgesendet, zum Beispiel:

```
GET /something HTTP/1.1
X-API-Key: abcdef12345
```

**API Key finden**

<figure><img src="/files/fhgC1uEe0ZoToPEjU8Qo" alt=""><figcaption></figcaption></figure>

1. In der Stamply Plattform **Einstellungen** öffnen
2. Tab **Integrations** wählen
3. Unter **API** den **API Key** kopieren

### Rate Limit

Aktuelles Limit:

* **10 Requests / Sekunde** (≈ **600 Requests / Minute**)
* Bei Überschreitung: **HTTP 429 – Too Many Requests**
* Dies bedeutet, dass das Limit erreicht wurde und der Client die Anfragefrequenz verringern muss.

### Zentrale Konzepte

Die Stamply API unterscheidet zwischen **Kartentyp (Card Type ID)** und teilweise zusätzlich der **Mechanik** (z. B. *Visit*, *Spend*, *Points*).\
Nicht jede Methode funktioniert für jeden Kartentyp. Die folgende Übersicht zeigt, was zulässig ist.

#### Card Types (IDs)

| Card Type  | ID |
| ---------- | -: |
| Stamp      |  0 |
| Cashback   |  1 |
| Multipass  |  2 |
| Coupon     |  3 |
| Discount   |  4 |
| Gift       |  5 |
| Membership |  6 |
| Reward     |  7 |

### Methoden nach Kartentyp

**Legende**

* ✓ = grundsätzlich unterstützt
* ✓\* = nur mit passender Mechanik / Einschränkung (siehe Hinweise unter der Tabelle)

| Methode                    | \[0] Stamp | \[1] Cashback | \[2] Multipass | \[3] Coupon | \[4] Discount | \[5] Gift | \[6] Membership | \[7] Reward |
| -------------------------- | :--------: | :-----------: | :------------: | :---------: | :-----------: | :-------: | :-------------: | :---------: |
| Add amount                 |            |       ✓       |                |             |               |           |                 |             |
| Subtract amount            |            |       ✓       |                |             |               |           |                 |             |
| Add point                  |            |       ✓       |                |             |       ✓       |     ✓     |                 |             |
| Subtract point             |            |       ✓       |                |             |       ✓       |     ✓     |                 |             |
| Add stamp                  |      ✓     |               |                |             |               |           |                 |             |
| Subtract stamp             |      ✓     |               |                |             |               |           |                 |             |
| Add reward                 |      ✓     |               |                |             |               |           |                 |             |
| Subtract reward            |      ✓     |               |                |             |               |           |                 |             |
| Add scores                 |            |               |        ✓       |             |               |           |                 |     ✓\*     |
| Subtract scores            |            |               |        ✓       |             |               |           |                 |      ✓      |
| Add visit                  |     ✓\*    |               |        ✓       |             |               |           |       ✓\*       |     ✓\*     |
| Subtract visit             |            |               |        ✓       |             |               |           |       ✓\*       |             |
| Add purchase               |     ✓\*    |               |                |             |               |           |                 |     ✓\*     |
| Receive reward (by client) |            |               |                |             |               |           |                 |      ✓      |
| Redeem coupon              |            |               |                |      ✓      |               |           |                 |             |

#### Hinweise / Einschränkungen

* **Add visit**
  * Stamp (0) nur, wenn die Karte auf Visit-Mechanik basiert.
  * Reward (7) nur, wenn die Karte auf Visit-Mechanik basiert.
  * Membership (6) nur, wenn ohne Limits konfiguriert.
* **Subtract visit**
  * Membership (6) nur, wenn mit Limits konfiguriert.
* **Add purchase**
  * Stamp (0) nur, wenn die Karte auf Spend/Purchase-Mechanik basiert.
  * Reward (7) nur, wenn die Karte auf Spend/Purchase-Mechanik basiert.
* **Add scores (Reward)**
  * Reward (7) nur, wenn Mechanik-Typ “Points” ist.

Die konkreten Endpoints und Payloads findest du in der [API Reference (ReDoc)](https://docs.stamply.ch/).

**Häufigste POS-Methoden**

* Stamp (0) + Visit Mechanik → Add visit
* Stamp (0) + Spend Mechanik → Add purchase
* Cashback (1) → Add/Subtract amount

***

### Grundobjekte

| Objektbereich            | Typische Operationen                              |
| ------------------------ | ------------------------------------------------- |
| Customers                | list / get / create / update / delete             |
| Cards                    | list / issue (create for customer) / get / delete |
| Companies / Sub-Accounts | list / get / create / update / change tariff      |
| Operations               | list                                              |
| Templates                | list / get                                        |
| Tariffs                  | list / get                                        |
| Push (optional)          | list / get / send                                 |

### Spezialfall: Einlösen von Prämien gegen Kosten (Stempelkarten)

In der Scanner-App kannst du beim Einlösen einer Prämie deren Kosten manuell eingeben. Dieser Betrag wird zum LTV (Lifetime Value) des Kunden addiert.

Das gleiche Verhalten kannst du über die API mit der Methode **`Subtract reward from card`** erzielen.

Wenn du bei einer Reward-Redemption einen monetären Wert erfassen willst, wird dieser als **`purchaseSum`** übergeben und in den LTV eingerechnet.

Beispiel:

```json
{
  "rewards": 1,
  "comment": "Reward redeemed",
  "purchaseSum": 10.5
}
```

* `rewards` → Anzahl Rewards, die abgezogen werden
* `comment` → optionaler Kommentar
* `purchaseSum` → monetärer Wert des eingelösten Rewards (für LTV)

Wichtig: Der Reward-Preis wird nicht automatisch aus den Karteneinstellungen übernommen. Wenn du den Wert tracken willst, musst du purchaseSum bei jedem Call explizit setzen.