Scan & Go API

GROW

Kunden scannen, bezahlen und empfangen digitale Belege – in der BEEP!-App oder direkt im Browser.Customers scan, pay and receive digital receipts – in the BEEP! app or directly in the browser.

Checkout-FlowCheckout Flow

checkIn

Kunde scannt Store-QR-Code. App registriert Session.Customer scans store QR code. App registers session.

ScanningScanning

Kunde scannt Produkte (App-intern, kein API-Call).Customer scans products (app-internal, no API call needed).

Altersverifikation (wenn nötig)Age Verification (if required)

Produkt mit flags.requiresHumanVerification: true blockiert Checkout bis zur Verifikation.Product with flags.requiresHumanVerification: true blocks checkout until verified.

startCheckout

Erstellt Kauf-Datensatz, verknüpft konfigurierten PSP.Creates purchase record, links configured PSP.

ZahlungPayment

Kunde bezahlt via PSP. Webhook checkout.completed wird ausgelöst.Customer pays via PSP. Webhook checkout.completed fires.

generateReceiptWithQR

Digitaler Kassenbon mit Datum, Transaktionsnummer und QR-Code-Link.Digital receipt with date, transaction number and QR code link.

EndpointsEndpoints

POST /api/v1/checkIn Scan & Go Session startenStart Scan & Go session GROW

Startet eine Scan & Go Session. Der Kunde scannt den Store-QR-Code in der BEEP!-App.

Starts a Scan & Go session. The customer scans the store QR code in the BEEP! app.

Request Body

Parameter	Typ	PflichtRequired	BeschreibungDescription
`userId`	string	required	ID des Kunden (Consumer-App)Customer ID (consumer app)

200 OK

{ "success": true, "sessionId": "sess_sandbox_1740650400000", "storeId": "sandbox_store_001", "checkedInAt": "2026-03-04T14:00:00.000Z" }

POST /api/v1/startCheckout Checkout startenStart checkout GROW

Erstellt einen Kauf-Datensatz und verknüpft den konfigurierten PSP des Stores.

Creates a purchase record and links the store's configured PSP.

priceUnit ist immer in Cent (Integer).is always in cents (integer). vat: 7 oderor 19.

Request Body

Parameter	Typ	PflichtRequired	BeschreibungDescription
`userId`	string	required	Kunden-IDCustomer ID
`items`	array	required	`name`, `priceUnit` (Cent), `quantity`, `vat`
`sessionId`	string	optional	Session-ID aus checkInSession ID from checkIn
`currency`	string	optional	`"EUR"` (default)

200 OK

{ "success": true, "purchaseId": "pur_sandbox_001", "total": 3.57, "currency": "EUR", "status": "pending_payment", "pspProvider": "stripe", "message": "Checkout über stripe initiiert." }

POST /api/v1/fetchPurchase Einkauf abrufenFetch purchase GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`purchaseId`	string	required	ID des EinkaufsPurchase ID

POST /api/v1/fetchPurchaseHistory Kaufhistorie abrufenFetch purchase history GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`userId`	string	optional	Filterung nach UserFilter by user
`limit`	number	optional	Max. Anzahl (default: 20, max: 100)Max count (default: 20, max: 100)

KassenbonsReceipts

GROW

Digitale Kassenbons werden automatisch nach jedem Scan & Go-Checkout erstellt. Sie enthalten Datum, Transaktionsnummer, MwSt-Aufschlüsselung und QR-Code-Link.

Digital receipts are created automatically after every Scan & Go checkout. They contain date, transaction number, VAT breakdown and QR code link.

Fiskalisierung: Das Feld tse ist im Datenmodell vorhanden, wird derzeit aber nicht von einer zertifizierten Technischen Sicherheitseinrichtung befüllt. In der Sandbox liefert es feste Platzhalterwerte. Die Anbindung einer TSE ist geplant. Verwende dieses Feld nicht als Nachweis gegenüber dem Finanzamt.

Fiscalisation: The tse field exists in the data model but is currently not populated by a certified Technical Security Device. In the sandbox it returns fixed placeholder values. A TSE integration is planned. Do not use this field as evidence towards tax authorities.

POST /api/v1/generateReceiptWithQR Kassenbon mit QR generierenGenerate receipt with QR GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`purchaseId`	string	required	ID des abgeschlossenen EinkaufsID of the completed purchase

200 OK

{ "success": true, "data": { "purchaseId": "pur_sandbox_001", "receiptNumber": "PUR_SANDB", "storeId": "sandbox_store_001", "total": 3.57, "taxBreakdown": [{ "rate": 7, "net": 2.22, "tax": 0.16, "gross": 2.38 }], "tse": { "serialNumber": "SANDBOX-TSE-001", "signature": "sandbox_tse_signature_base64", "transactionNumber": 42 }, "qrCodeUrl": "https://storage.googleapis.com/.../receipts/pur_001_qr.png", "qrCodeData": "cHVyX3NhbmRib3hfMDAxOnNhbmRib3hfc3RvcmVfMDAx", "issuedAt": "2026-03-04T14:15:00.000Z" } }

POST /api/v1/getReceiptFromToken Kassenbon per Token abrufenRetrieve receipt by token GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`token`	string	required	QR-Token aus `generateReceiptWithQR`QR token from `generateReceiptWithQR`

EmpfehlungenRecommendations

GROW

Empfehlungen basieren auf aktiven Angeboten des Stores (status: "active"). Sie werden im Scan & Go-Flow oder beim Checkout ausgespielt.

Recommendations are based on the store's active offers (status: "active"). They are served during the Scan & Go flow or at checkout.

POST /api/v1/getRecommendations Empfehlungen abrufenGet recommendations GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`trigger`	string	optional	`"scan_and_go"` \| `"checkout"` \| `"cart"`
`limit`	number	optional	Max. Empfehlungen (default: 5)Max. recommendations (default: 5)

Config-Aware: Respektiert die via configureRecommendations gesetzte Konfiguration. maxPerSession überschreibt limit.Config-Aware: Respects configuration set via configureRecommendations. maxPerSession overrides limit.

200 OK

{ "success": true, "data": [{ "offerId": "offer_sandbox_001", "title": "Wochendeal Milchprodukte", "discount": "20%", "relevanceScore": 0.92, "trigger": "scan_and_go", "validTo": "2026-03-10T23:59:59.000Z" }] }

POST /api/v1/configureRecommendations Empfehlungsregeln setzenConfigure recommendation rules GROW

Parameter	Typ	PflichtRequired	BeschreibungDescription
`enabled`	boolean	optional	Aktivieren (default: true)Enable (default: true)
`triggers`	array	optional	`["scan_and_go", "checkout"]`
`maxPerSession`	number	optional	Max. pro Session (default: 3)Max. per session (default: 3)
`excludeExpiredOffers`	boolean	optional	Abgelaufene Angebote ausschließen (default: true)Exclude expired offers (default: true)

AltersverifikationAge Verification

GROW

Händler-Pflicht: Produkte mit gesetzlicher Alterskontrolle (Alkohol, Tabak) müssen mit flags.requiresHumanVerification: true markiert sein. BEEP! blockiert den Checkout automatisch bis zur Verifikation.Merchant requirement: Products requiring legal age control (alcohol, tobacco) must be flagged flags.requiresHumanVerification: true. BEEP! automatically blocks checkout until verification.

Produkt kennzeichnenFlag the product

flags.requiresHumanVerification: true in insertProduct setzen. Automatisch via POS-Sync möglich.set in insertProduct. Also automatic via POS sync.

Verifikations-QR-CodeVerification QR Code

BEEP! sichert für den Verifikations-QR-Code kein API-Feld zu. store.verificationCodeUrl ist nicht länger dokumentiert und kann ohne Vorlauf entfallen — bauen Sie Ihre Integration nicht darauf. Wie der Code an den Händler ausgegeben wird, ist derzeit nicht festgelegt.BEEP! does not guarantee an API field for the verification QR code. store.verificationCodeUrl is no longer documented and may be removed without notice — do not build your integration on it. How the code is issued to the merchant is not yet defined.

QR-Code platzierenPlace QR Code

Ausdruck, Kassendisplay oder Tablet an der Kasse. Sichtbar für Mitarbeiter und Kunden.Print, POS display, or tablet at checkout. Visible to staff and customers.

Ausweis prüfenCheck ID

Mitarbeiter kontrolliert den Ausweis des Kunden und zeigt anschließend den QR-Code.Staff checks the customer's ID then shows the QR code.

Kunde scanntCustomer scans

Die BEEP!-App ruft validateHumanVerificationCode auf. Verifikation ist 24 Stunden gültig.The BEEP! app calls validateHumanVerificationCode. Verification is valid for 24 hours.

POST /validateHumanVerificationCode Altersverifikation prüfenValidate age verification GROW

Standalone Cloud Function. Keine Gateway-Route. Eigene Base-URL:Standalone Cloud Function. Not a gateway route. Own base URL:
https://europe-west6-beep-c6786.cloudfunctions.net/validateHumanVerificationCode

Parameter	Typ	PflichtRequired	BeschreibungDescription
`storeId`	string	required	ID des StoresStore ID
`humanVerificationCode`	string	required	Wert aus dem QR-CodeValue read from the QR code

200 OK

{ "message": "Human verification code is valid." }

403 Falscher CodeWrong Code

"Invalid human verification code."

ProduktsicherungSecurity Tags

GROW

Scan & Go unterstützt Stores mit elektronischen Produktsicherungen (EAS). Konfiguriere securityTagMode in deinen Store-Einstellungen, um den passenden Deaktivierungsablauf für deine Kund:innen zu aktivieren.

Scan & Go supports stores with electronic article surveillance (EAS). Configure securityTagMode in your store settings to activate the appropriate deactivation flow for your customers.

Unterstützte Branchen: Mode (Hard-Tags), Drogerie (Rasierklingen, Parfum), Supermärkte (Spirituosen, Premium-Fleisch), Elektronik (Spider-Wraps, Keeper-Cases), Baumärkte (Elektrowerkzeuge), Sport (RFID-Tags).Supported segments: Fashion (hard tags), drugstores (razor blades, perfume), supermarkets (spirits, premium meat), electronics (spider wraps, keeper cases), hardware (power tools), sports (RFID tags).

Store-KonfigurationStore Configuration

Field	TypType	BeschreibungDescription
`securityTagMode`	string	`"none"` (default) \| `"manual"` \| `"station"` \| `"rfid""none"` (default) \| `"manual"` \| `"station"` \| `"rfid"`
`securityTagHint`	string?	Optionaler Kundenhinweis-Text, der im Warenkorb und auf dem Kassenbon angezeigt wird.Optional custom hint text shown to customers in the cart and on the receipt.

ModiModes

Mode	AblaufFlow	Typisch fürTypical for
`manual`	Kunde zeigt Kassenbon vor, Mitarbeiter entfernt SicherungCustomer shows receipt, staff removes tag	Mode, Drogerie, SupermärkteFashion, drugstores, supermarkets
`station`	Kunde scannt QR am Terminal, Station verifiziert und deaktiviertCustomer scans QR at terminal, station verifies and deactivates	Große Modeketten, ElektromärkteLarge fashion chains, electronics stores
`rfid`	Automatische Deaktivierung per RFID nach ZahlungAutomatic RFID deactivation after payment	Zara, Uniqlo, DecathlonZara, Uniqlo, Decathlon

POST /api/v1/verifySecurityTagDeactivation Deaktivierung verifizierenVerify deactivation GROW

Für den station-Modus: Prüft ob ein Kauf bezahlt wurde und gibt die Deaktivierung frei. Wird von Deaktivierungs-Terminals aufgerufen.

For station mode: Checks whether a purchase has been paid and authorizes deactivation. Called by deactivation terminals.

Parameter	TypType	PflichtRequired	BeschreibungDescription
`purchaseId`	string	optional*	Kauf-IDPurchase ID
`receiptToken`	string	optional*	QR-Code Token vom KassenbonQR code token from receipt

* Mindestens purchaseId oder receiptToken muss angegeben werden.* At least purchaseId or receiptToken must be provided.

200 OK

{ "success": true, "status": "paid", "items": [...], "securityTagMode": "station", "deactivationAuthorized": true }