API ReferenceAPI Reference

Alle BEEP! Cloud Functions, Endpunkte, Parameter, Request/Response-Schemas. Der API Gateway läuft in europe-west6.

All BEEP! Cloud Functions, endpoints, parameters, request/response schemas. The API Gateway runs in europe-west6.

Base URLBase URL

https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/{action}

AuthentifizierungAuthentication

Alle API-Calls erfordern einen Bearer Token im Authorization-Header. Nutze den Secret Key für serverseitige Calls.

All API calls require a Bearer token in the Authorization header. Use the Secret Key for server-side calls.

Header

Authorization: Bearer bk_test_sk_YOUR_KEY X-Beep-Store-Id: YOUR_STORE_ID # optional, für Store-spezifische Calls

Fehler-CodesError Codes

HTTP Code	FunctionsError	Beschreibung
400	`invalid-argument`	Fehlende oder ungültige Parameter
401	`unauthenticated`	Kein gültiger API-Key
403	`permission-denied`	Paket-Feature nicht freigeschaltet
404	`not-found`	Ressource nicht gefunden
409	`already-exists`	Ressource existiert bereits
500	`internal`	Interner Fehler

Error Response

{ "error": { "code": "invalid-argument", "message": "Missing required field: storeId", "status": 400 } }

Pagination

Listen-Endpunkte unterstützen cursor-basierte Pagination via limit und cursor. Der cursor ist das Dokument-ID des letzten Elements der vorherigen Seite.

List endpoints support cursor-based pagination via limit and cursor. The cursor is the document ID of the last item on the previous page.

Query Parameters (Liste)

POST /fetchPurchaseHistory Body: { "userId": "usr_42", "limit": 20, "cursor": "purchase_abc123" }

GET /fetchStores

DISCOVER

Gibt alle Stores zurück, auf die der API-Key Zugriff hat. Im Sandbox-Modus werden 2 Test-Stores zurückgegeben.

Returns all stores the API key has access to. In sandbox mode 2 test stores are returned.

GET /fetchStores Liste aller zugänglichen Stores

Query Parameters

Parameter	Typ	Beschreibung
cityoptional	string	Filter nach Stadt
limitoptional	integer	Max. Ergebnisse (default: 50)

Response

200 OK

{ "data": [ { "id": "store_abc123", "name": { "legal": "Mustermann GmbH", "trading": "Frische Ecke Mitte" }, "address": { "street": "Hauptstraße 12", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" }, "phone": "+49 30 12345678", "coordinates": { "latitude": 52.5200, "longitude": 13.4050 }, "mode": "live", "package": "grow", "hasScanAndGo": true, "hasOffers": true, "rating": 4, "receiptCount": 1247 } ], "total": 1 }

GET /fetchStore

DISCOVER

Gibt einen einzelnen Store zurück, inkl. Produktkatalog. Der API-Key darf nur den eigenen Store abrufen.

Returns a single store including the product catalog. The API key may only fetch its own store.

GET /fetchStore Einzelnen Store abrufen

Query Parameters

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores

Response

Gibt das Store-Objekt zurück (wie in fetchStores), ergänzt um ein products[]-Array mit allen Produkten des Stores.

Returns the store object (as in fetchStores), augmented with a products[] array containing all products of the store.

insertStore ist nicht verfügbar. Nutze submitStoreRegistrationRequest für die Store-Registrierung. Dieser Endpoint erstellt einen Registrierungsantrag, der von einem BEEP! Admin geprüft und freigegeben wird.Use submitStoreRegistrationRequest for store registration. This endpoint creates a registration request that is reviewed and approved by a BEEP! admin.

POST /checkIn

GROW

Startet eine neue Scan & Go Session für einen Kunden. Gibt eine sessionId zurück, die für den anschließenden Checkout benötigt wird.

Starts a new Scan & Go session for a customer. Returns a sessionId required for the subsequent checkout.

POST /checkIn Scan & Go Session starten

Request Body

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores
userIdrequired	string	Kunden-ID

Response

200 OK

{ "success": true, "sessionId": "sess_k7aB3xQm9wPz", "storeId": "store_abc123", "userId": "usr_42", "checkedInAt": "2026-02-27T09:41:22.000Z", "message": "Check-in successful" }

POST /startCheckout

GROW

Initiiert den Checkout für eine Scan & Go Session. Gibt eine Checkout-URL zurück, zu der die BEEP-App weiterleitet.

Initiates the checkout for a Scan & Go session. Returns a checkout URL to which the BEEP app redirects.

POST /startCheckout PSP-Checkout initiieren

Request Body

Parameter	Typ	Beschreibung
userIdrequired	string	Kunden-ID
storeIdrequired	string	ID des Stores
sessionIdrequired	string	Session-ID aus /checkIn
currencyrequired	string	ISO 4217, z.B. `EUR`
destinationoptional	string	PSP-Account-ID des Händlers (konfiguriert via `configurePSP`). Falls nicht angegeben, wird der im Store hinterlegte PSP-Account verwendet.
itemsrequired	array	Gekaufte Produkte (siehe unten)

Item-Objekt

Feld	Typ	Beschreibung
namerequired	string	Produktname (für Beleg)
priceUnitrequired	integer	Preis in Cent (z.B. 129 = 1,29 €)
quantityrequired	integer	Anzahl
vatrequired	integer	`7` oder `19` (MwSt.-Satz in %)

Preise immer in Cent. MwSt. immer 7 (ermäßigt, z.B. Lebensmittel) oder 19 (normal). TSE-Konformität wird serverseitig sichergestellt.

Response

200 OK

{ "success": true, "transactionId": "txn_mP4kR9nX", "sessionId": "sess_k7aB3xQm9wPz", "checkoutSessionId": "cs_test_a1B2c3D4", "checkoutUrl": "https://checkout.example.com/pay/session_...", "total": 437, "currency": "EUR", "status": "PENDING_PAYMENT", "createdAt": "2026-02-27T09:41:55.000Z" }

Purchase Status Flow

CREATED → PENDING_PAYMENT → SUCCESS → CANCELLED

POST /fetchPurchase

GROW

POST /fetchPurchase Einzelne Transaktion abrufen

Query Parameters

Parameter	Typ	Beschreibung
idrequired	string	Transaktions-ID

POST /fetchPurchaseHistory

GROW

POST /fetchPurchaseHistory Transaktionshistorie eines Kunden

Parameter	Typ	Beschreibung
userIdrequired	string	Kunden-ID
limitoptional	integer	Max. Ergebnisse (default: 50)

GET /fetchProducts

DISCOVER

Gibt alle Produkte im Katalog des Stores zurück, der dem API-Key zugeordnet ist.

Returns all products in the catalog of the store assigned to the API key.

GET /fetchProducts Alle Produkte des Stores

Query Parameters

Parameter	Typ	Beschreibung
categoryoptional	string	Filter nach Kategorie
limitoptional	integer	Max. Ergebnisse (default: 100)

GET /fetchProduct

DISCOVER

Gibt ein einzelnes Produkt zurück, per id (Produkt-ID) oder barcode (EAN).

Returns a single product by id (product ID) or barcode (EAN).

GET /fetchProduct Einzelnes Produkt abrufen

Query Parameters

Parameter	Typ	Beschreibung
idone of	string	Produkt-ID
barcodeone of	string	EAN-13 oder EAN-8 Barcode

Entweder id oder barcode muss angegeben werden. Das Produkt muss dem Store des API-Keys gehören.

POST /insertProduct

DISCOVER

Fügt ein neues Produkt in den Store-Katalog ein. Vollständiges Datenformat-Guide: Datenformate →

Inserts a new product into the store catalog. Full data format guide: Data Formats →

POST /insertProduct Produkt in Katalog einfügen

Request Body (JSON)

Feld	Typ	Beschreibung
storeIdrequired	string	Store, in den das Produkt gehört
eanrequired	string	EAN-13 oder EAN-8 Barcode
namerequired	string	Produktname (max. 120 Zeichen)
pricerequired	number	Verkaufspreis in EUR (Dezimal)
vatrequired	integer	`7` oder `19`
categoryoptional	string	Kategorie (z.B. "Getränke")
unitoptional	string	Einheit (z.B. "Flasche", "kg")

Produktbilder werden über den separaten Endpoint uploadImageToProduct (Standalone CF, multipart/form-data) hochgeladen.Product images are uploaded via the separate uploadImageToProduct endpoint (standalone CF, multipart/form-data).

POST /registerProductToStore

DISCOVER

Verknüpft ein bestehendes Produkt mit dem Store des API-Keys. Das Produkt muss bereits über insertProduct angelegt worden sein.

Links an existing product to the store of the API key. The product must already have been created via insertProduct.

POST /registerProductToStore Produkt einem Store zuordnen

Request Body

Parameter	Typ	Beschreibung
productIdrequired	string	Produkt-ID

POST /uploadImageToProduct

DISCOVER

Standalone Cloud Function: dieser Endpoint läuft nicht über das API-Gateway. Basis-URL:this endpoint does not run through the API Gateway. Base URL: https://europe-west6-beep-c6786.cloudfunctions.net/uploadImageToProduct

Lädt ein Produktbild hoch und setzt es als Snapshot des Produkts. Das Bild wird in BEEP! Cloud Storage unter products/{productId}/snapshot/ abgelegt und der öffentliche Download-URL in media.snapshot des Produktdokuments gespeichert.

Uploads a product image and sets it as the product’s snapshot. The image is stored in BEEP! Cloud Storage under products/{productId}/snapshot/ and the public download URL is saved to media.snapshot on the product document.

POST /uploadImageToProduct Produktbild hochladen

Request: `multipart/form-data`

Feld	Typ	Beschreibung
productIdrequired	string	Produkt-ID (aus `insertProduct`)
snapshotrequired	file	Bilddatei (JPEG / PNG / WebP). Das Feld muss exakt `snapshot` heißen.

Response

200 OK

{ "message": "Images uploaded and product updated successfully." }

400: Fehlendes Feld

"productId is required."

POST /markPurchaseCancelled

GROW

Coming Soon. Dieser Endpoint ist aktuell noch nicht über das API-Gateway erreichbar. Stornierungen können derzeit über das BEEP! Dashboard oder die Händler-App durchgeführt werden.This endpoint is not yet available via the API Gateway. Cancellations can currently be performed via the BEEP! Dashboard or the Merchant App.

Markiert eine Transaktion als storniert. Nur Transaktionen mit Status PENDING_PAYMENT oder SUCCESS können storniert werden. Bei bereits bezahlten Transaktionen wird ein Refund über den konfigurierten PSP ausgelöst.

Marks a transaction as cancelled. Only transactions with status PENDING_PAYMENT or SUCCESS can be cancelled. For already-paid transactions a refund is triggered via the configured PSP.

POST /markPurchaseCancelled Transaktion stornieren

Request Body

Parameter	Typ	Beschreibung
purchaseIdrequired	string	Transaktions-ID
reasonoptional	string	Stornierungsgrund (für interne Dokumentation)

POST /generateCodes

GROW

Generiert QR-Codes für einen Store, z.B. für Tisch-Aufsteller, Eingangsbereich oder Marketing-Material. Gibt Base64-kodierte PNG-Bilder zurück.

Generates QR codes for a store, e.g. for table stands, entrance area or marketing material. Returns Base64-encoded PNG images.

POST /generateCodes Store QR-Codes generieren

Request Body

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores
typeoptional	string	`checkin` (default), `payment`, `profile`
sizeoptional	integer	Bildgröße in px (default: 512)

POST /generateReceiptWithQR

GROW

Generiert einen QR-Code, der zu einem digitalen Beleg führt. Der QR-Code enthält einen Token, über den der Beleg öffentlich (ohne Auth) aufrufbar ist.

Generates a QR code that leads to a digital receipt. The QR code contains a token through which the receipt can be accessed publicly (without auth).

POST /generateReceiptWithQR Beleg-QR generieren

Request Body

Parameter	Typ	Beschreibung
purchaseIdrequired	string	Transaktions-ID

Response

200 OK

{ "success": true, "receiptUrl": "https://beep-c6786.web.app/receipt/...", "qrCode": "data:image/png;base64,...", "token": "rct_a1B2c3D4e5F6" }

GET /getReceiptFromToken

GROW

Holt den vollständigen Beleg über einen öffentlichen Token. Dieser Endpoint erfordert keine Authentifizierung: der Token selbst ist das Zugriffsrecht.

Fetches the complete receipt via a public token. This endpoint requires no authentication: the token itself is the access credential.

GET /getReceiptFromToken?token={token} Beleg via Token abrufen

Query Parameters

Parameter	Typ	Beschreibung
tokenrequired	string	Receipt-Token (aus `generateReceiptWithQR`)

Gibt die vollständigen Belegdaten zurück inkl. Items, MwSt.-Aufschlüsselung und TSE-Signatur. Siehe Beleg-Datenformat.

POST /submitStoreRegistrationRequest

Store-Registrierungsanfragen werden von einem BEEP! Admin manuell geprüft und genehmigt. Neue Stores starten automatisch mit dem DISCOVER-Paket (kostenlos).

POST /submitStoreRegistrationRequest Neue Store-Registrierung beantragen

Request Body

JSON

{ "storeData": { "name": { "legal": "Mustermann Getränkemarkt GmbH", "trading": "Getränke Mustermann" }, "address": { "street": "Hauptstraße 12", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" }, "phone": "+49 30 12345678" }, "managerData": { "firstName": "Max", "lastName": "Mustermann", "email": "max@mustermann.de", "phone": "+49 171 9876543" } }

Response

200 OK

{ "success": true, "registrationId": "reg_7c3f8e1a-...", "message": "Registration request submitted. Awaiting admin approval." }

Angebote (GO-Paket)

Angebote werden über die REST-API verwaltet und sind in Echtzeit in der BEEP!-App sichtbar. Multi-Store-Angebote verwenden ein groupId-Konzept. Vollständige Docs: Angebote API →

Offers are managed via the REST API and appear in real time in the BEEP! app. Multi-store offers use a groupId concept. Full docs: Offers API →

POST /createOffer

Erstellt ein Angebot und rollt es auf einen oder mehrere Stores aus. Alle Filial-Kopien teilen eine groupId.

Creates an offer and rolls it out to one or more stores. All branch copies share a groupId.

POST /createOffer Angebot erstellenCreate offer

Request Body

Feld	Typ	Beschreibung
storeIdsrequired	string[]	Eine oder mehrere Store-IDs
titlerequired	string	Angebotstitel
productsrequired	array	`{ ean, name, originalPrice, discountPrice }`
validFromoptional	string	ISO 8601 Startzeit
validUntiloptional	string	ISO 8601 Endzeit
descriptionoptional	string	Angebotstext

Response

200 OK

{ "success": true, "offerId": "offer_abc123", "offerIds": ["offer_abc123", "offer_def456"], "groupId": "grp_x1y2z3", "storeCount": 2 }

Updates: updateOffer propagiert zu allen Filialen via groupId. Löschen: deleteOffer. Vollständige Docs: Angebote API.Updates: updateOffer propagates to all branches via groupId. Delete: deleteOffer. Full docs: Offers API.

Offer-SchemaOffer Schema

Offer Object

{ "offerId": "off_abc123", "storeId": "store_xyz", "title": "Bio-Vollmilch Sonderangebot", "productEan": "4000000000001", "originalPrice": 1.49, // EUR Dezimal "discountPrice": 1.19, // EUR Dezimal "discountPercent": 20, // auto-berechnet "validFrom": "2026-03-01T00:00:00.000Z", "validTo": "2026-03-07T23:59:59.000Z", "scope": "LOCAL", // scope: "LOCAL" | "MULTI_STORE" | "CITY_WIDE" | "REGIONAL" | "NATIONAL" "status": "ACTIVE", // status: "DRAFT" | "ACTIVE" | "EXPIRED" | "ARCHIVED" "imageUrl": "https://storage.googleapis.com/beep-c6786.appspot.com/...", "createdAt": "2026-02-27T10:00:00.000Z", "updatedAt": "2026-02-27T10:00:00.000Z" }

Loyalty API GO+

Treueprogramme (Stamps, Points, Cashback, Tier-System) werden über die Loyalty API verwaltet. Kunden sammeln Punkte per QR-Code, GPS Check-in, Click & Collect und Scan & Go (GROW+).

Loyalty programs (Stamps, Points, Cashback, Tier system) are managed via the Loyalty API. Customers earn points via QR code, GPS check-in, Click & Collect and Scan & Go (GROW+).

Stamps / Points

1 Programm, 6 Templates, QR-Code + Check-in + C&C Earning

GROW

Cashback & Custom Rewards

+ Scan & Go Earning automatisch

PRIME

Tier-System & Extern

Bronze/Silber/Gold, Multi-Store, Payback Sync API

ENDPOINTS

Loyalty API Referenz

createProgram, enroll, addPoints, redeem, getBalance

Die vollständige Loyalty API Reference, alle Endpoints, Parameter und Webhook-Events findest du in der Loyalty API Dokumentation. Einstieg: Loyalty Quickstart (5 Min.).The complete Loyalty API reference, all endpoints, parameters and webhook events are in the Loyalty API documentation. Get started: Loyalty Quickstart (5 min.).

API ReferenceAPI Reference

Base URLBase URL

AuthentifizierungAuthentication

Fehler-CodesError Codes

Pagination

GET /fetchStores

Query Parameters

Response

GET /fetchStore

Query Parameters

Response

POST /checkIn

Request Body

Response

POST /startCheckout

Request Body

Item-Objekt

Response

Purchase Status Flow

POST /fetchPurchase

Query Parameters

POST /fetchPurchaseHistory

GET /fetchProducts

Query Parameters

GET /fetchProduct

Query Parameters

POST /insertProduct

Request Body (JSON)

POST /registerProductToStore

Request Body

POST /uploadImageToProduct

Request: multipart/form-data

Response

POST /markPurchaseCancelled

Request Body

POST /generateCodes

Request Body

POST /generateReceiptWithQR

Request Body

Response

GET /getReceiptFromToken

Query Parameters

POST /submitStoreRegistrationRequest

Request Body

Response

Angebote (GO-Paket)

POST /createOffer

Request Body

Response

Offer-SchemaOffer Schema

Loyalty API GO+

Request: `multipart/form-data`