The StampyWallet API
BetaAdd visits, create customers and receive your loyalty card's events from your POS, your website or a no-code tool.
The API connects StampyWallet to the rest of your business. It works both ways:
- Into StampyWallet: your POS, your website or your booking software adds a visit, creates a customer or gives a reward, without scanning at the counter.
- Out of StampyWallet: on every visit, new card or reward, StampyWallet calls an address of your choice (a webhook). That is what feeds a spreadsheet, a CRM or a Zapier scenario.
Before you start : the API, the POS incoming addresses (Connect your POS) and webhooks are included in the Growth plan (€40 excl. VAT per month), and open during the free trial. On the Essential plan, calls respond 403 with the code formule_requise.
Warning : the API is in beta. The routes and fields described here are those of the implementation; new fields may appear before the stable version: ignore the ones you don't know. Changes are announced in the changelog.
Base URL
All routes are served over HTTPS, in JSON (field names in French, in snake_case), under:
https://app.stampywallet.com/v1Identifiers are UUIDs; amounts are in the business's currency, in units (12.5 for €12.50).
A first call
Create a key in Settings › Integrations (see Authentication), then read your business profile:
curl https://app.stampywallet.com/v1/commerce \
-H "Authorization: Bearer sw_live_your_key"const reponse = await fetch('https://app.stampywallet.com/v1/commerce', {
headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` },
});
console.log(await reponse.json());import os, requests
reponse = requests.get(
"https://app.stampywallet.com/v1/commerce",
headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"},
)
print(reponse.json())What the API can do
| Route | Purpose |
|---|---|
GET /v1/commerce | Read the business profile and the card rules |
POST /v1/clients | Create a customer and get their card link |
GET /v1/clients | Find a customer by phone, email or card |
GET /v1/clients/:id | Get a customer and the state of their card |
POST /v1/passages | Add a visit: a stamp, or points based on the amount |
DELETE /v1/passages/:id | Cancel a visit |
POST /v1/recompenses | Give an earned reward |
POST /v1/entrants/:jeton | Receive sales from your POS (Square, Shopify, SumUp, Zettle, or the generic format) |
And the other way, outgoing webhooks: nine signed events.
Tip : no developer at hand? The Connect your POS page gives step-by-step settings for Square, Shopify, SumUp and Zettle, and for Zapier, Make and n8n.
What about MCP?
The API is made for software: a POS, a website, a script. To run your business in a conversation, from Claude, ChatGPT or Cursor, use the MCP server instead: it needs no key, only connecting your account.
Frequently asked questions
How much does the API cost?
The API, POS incoming addresses and webhooks are included in the Growth plan, at €40 excl. VAT per month, and open during the 30-day free trial. On the Essential plan, calls respond 403.
Do I need a developer to connect my POS?
Not for Square, Shopify, SumUp, Zettle, Zapier, Make or n8n: the Connect your POS page gives step-by-step settings. Calling the API from your own software, however, takes someone who writes code.
Is there a rate limit?
Yes: 120 requests per minute per key. Beyond that, the response is 429 with a Retry-After header.
Does one key work for several locations?
No. A key gives access only to the business it was created in: create a key in each location.
How do I avoid a double stamp when my POS retries?
Give each visit a reference, such as the receipt number, and send an Idempotency-Key header on every POST: a retry does not stamp twice.
Updated