Developer
Test ModeTest Mode Sign In Get started
DeveloperDeveloper / Angebote APIOffers API

Angebote APIOffers API

Erstelle und verwalte digitale Angebote, die Alternative zu Papier-Prospekten. Angebote erscheinen in der BEEP!-App auf der Discover-Seite der jeweiligen Filiale(n). Ein Angebot kann gleichzeitig für mehrere Filialen einer Kette ausgerollt werden.

Create and manage digital offers, the alternative to paper flyers. Offers appear in the BEEP! app on the discover page of the relevant store(s). A single offer can be rolled out simultaneously to multiple branches of a chain.

Angebote-Endpoints erfordern mindestens das GO-Paket.
Auto-Expiry: Angebote deren validTo-Datum in der Vergangenheit liegt, werden automatisch aus der Consumer-App ausgeblendet. Sie bleiben über getManagerOffers sichtbar (Status-Filter "expired"). Zum vollständigen Entfernen nutze deleteOffer.Offers whose validTo date is in the past are automatically hidden from the consumer app. They remain visible via getManagerOffers (status filter "expired"). To remove completely, use deleteOffer.

Multi-Filial-AngeboteMulti-Store Offers

Handelsketten können ein Angebot in einem einzigen API-Call für alle gewünschten Filialen gleichzeitig ausrollen. Das Backend erstellt dabei ein eigenes Firestore-Dokument pro Filiale, jedes mit den lokalen Geodaten, damit Kunden in der Nähe der jeweiligen Filiale das Angebot sehen. Alle Filial-Kopien sind über ein gemeinsames groupId-Feld verknüpft.

Retail chains can roll out an offer to all desired branches in a single API call. The backend creates a dedicated Firestore document per store, each with local geo-data so that customers near that branch see the offer. All branch copies are linked via a shared groupId field.

1
Store-IDs übergebenPass store IDs
storeIds: ["store_a", "store_b", "store_c"]
2
Backend erstellt Filial-DokumenteBackend creates branch documents
Pro Filiale ein Firestore-Dokument mit lokalen Koordinaten. Alle Kopien teilen eine gemeinsame groupId.One Firestore document per branch with local coordinates. All copies share a common groupId.
3
Kunden sehen das Angebot in der NäheCustomers see the offer nearby
Die BEEP!-App zeigt das Angebot, wenn der Kunde sich in der Nähe irgendeiner der Filialen befindet.The BEEP! app shows the offer when the customer is near any of the branches.
4
Updates propagieren automatischUpdates propagate automatically
updateOffer und deleteOffer wirken auf alle Filial-Kopien der Angebotsgruppe.updateOffer and deleteOffer apply to all branch copies of the offer group.

POST /api/v1/createOffer

Erstellt ein neues Angebot für eine oder mehrere Filialen. Das Angebot wird nach Erstellung sofort in der App sichtbar.

Creates a new offer for one or more stores. The offer becomes immediately visible in the app after creation.

ParameterTypPflichtBeschreibung
storeIdsstring[]JaListe der Store-IDs. Für Multi-Filial-Angebote mehrere IDs übergeben.List of store IDs. Pass multiple IDs for multi-branch offers.
titlestringJaTitel des Angebots (min. 3 Zeichen)Offer title (min. 3 characters)
descriptionstringNeinBeschreibung (wird automatisch generiert wenn leer)Description (auto-generated if empty)
validFromstringJaISO 8601 StartdatumISO 8601 start date
validTostringJaISO 8601 EnddatumISO 8601 end date
merchantColorstringNeinPrimärfarbe als Hex ohne #, z.B. "D40000". Default: "FF6600"Primary colour as hex without #, e.g. "D40000". Default: "FF6600"
tagsstring[]NeinSchlagwörter für die Suche, z.B. ["Bio", "Frische"]Search keywords, e.g. ["Organic", "Fresh"]
productsobject[]JaListe der Angebotsprodukte (min. 1). Siehe Produkt-Schema unten.List of offer products (min. 1). See product schema below.

Produkt-Schema (products[])Product schema (products[])

FeldTypPflichtBeschreibung
namestringJaProduktnameProduct name
pricenumberJaAktueller Aktionspreis in EURCurrent discounted price in EUR
oldPricenumberNeinUrsprünglicher Preis (für Durchstreichung in App)Original price (displayed as strikethrough in app)
discountPercentagenumberNeinRabatt in Prozent (0–100). Wenn angegeben, wird price aus oldPrice berechnet.Discount in percent (0–100). If provided, price is calculated from oldPrice.
categorystringNeinProduktkategorie, z.B. "Getränke"Product category, e.g. "Beverages"
manufacturerstringNeinMarke/HerstellerBrand / manufacturer
unitstringNeinMengeneinheit, z.B. "1,5L Flasche"Unit description, e.g. "1.5L bottle"
descriptionstringNeinKurzbeschreibung des ProduktsShort product description

Response (200 OK)

200 OK
{ "success": true, "offerId": "abc123", // ID of the first created document "offerIds": ["abc123", "def456"], // one entry per branch "groupId": "grp_xyz789", // links all branch copies "storeCount": 2, "createdAt": "2026-03-02T10:00:00.000Z" }

POST /api/v1/updateOffer

Aktualisiert ein bestehendes Angebot. Nur übergebene Felder werden geändert (Partial Update). Bei Multi-Store-Angeboten werden gemeinsame Felder (Titel, Produkte, Datum, Farbe, Tags) automatisch auf alle verknüpften Filial-Dokumente propagiert. Über das optionale Feld storeIds kann die Filial-Zuordnung nachträglich angepasst werden: neue Filialen werden automatisch angelegt, entfernte Filialen deaktiviert.

Updates an existing offer. Only passed fields are changed (partial update). For multi-store offers, shared fields (title, products, dates, colour, tags) are automatically propagated to all linked branch documents. The optional storeIds field allows updating the store assignment: new stores are automatically created, removed stores are deactivated.

ParameterTypPflichtBeschreibung
offerIdstringJaID eines der Angebots-Dokumente (eines aus offerIds reicht)ID of any one offer document (any ID from offerIds works)
titlestringNeinNeuer Titel
productsobject[]NeinNeue Produktliste (ersetzt bisherige vollständig)New product list (replaces existing completely)
storeIdsstring[]NeinNeue vollständige Filial-Liste. Das Backend erstellt Dokumente für hinzugefügte Filialen und deaktiviert Dokumente für entfernte Filialen. Alle Änderungen propagieren auf bestehende Geschwister-Dokumente.New complete store list. The backend creates documents for added stores and deactivates documents for removed stores. All changes propagate to existing sibling documents.
validFromstringNeinNeues Startdatum (ISO 8601)New start date (ISO 8601)
validTostringNeinNeues Enddatum (ISO 8601)New end date (ISO 8601)
merchantColorstringNeinNeue Primärfarbe (Hex ohne #)New primary colour (hex without #)
tagsstring[]NeinNeue SchlagwörterNew tags

Response (200 OK)

200 OK
{ "success": true, "offerId": "abc123", "updatedFields": ["title", "products"], "siblingUpdates": 1, // count of propagated sibling docs "addedStores": 0, // newly created branch documents "removedStores": 0 // deactivated branch documents }

POST /api/v1/deleteOffer

Löscht ein Angebot. Das Angebot verschwindet sofort aus der App. Bei Multi-Store-Angeboten werden alle verknüpften Filial-Dokumente gemeinsam gelöscht.

Deletes an offer. The offer disappears immediately from the app. For multi-store offers, all linked branch documents are deleted together.

ParameterTypPflichtBeschreibung
offerIdstringJaID eines der Angebots-DokumenteID of any one offer document

POST /api/v1/getManagerOffers

active scheduled expired

Listet alle Angebote des angemeldeten Managers auf (aktiv, abgelaufen, geplant). Multi-Store-Angebote werden dedupliziert zurückgegeben, jede Angebotsgruppe erscheint einmal mit ihrer groupId.

Lists all offers for the authenticated manager (active, expired, scheduled). Multi-store offers are returned deduplicated, each offer group appears once with its groupId.

ParameterTypPflichtBeschreibung
statusstringNein"active", "expired", "scheduled" (Default: alle)
200 OK
{ "success": true, "offers": [ { "id": "abc123", "groupId": "grp_xyz789", // null for single-store offers "title": "Wochenangebote KW 10", "storeIds": ["store_a", "store_b"], "validFrom": "2026-03-02T00:00:00.000Z", "validTo": "2026-03-08T23:59:59.000Z", "productCount": 6, "isActive": true } ], "total": 1 }

POST /api/v1/cloneOffer

Dupliziert ein bestehendes Angebot für andere Filialen. Nützlich um bewährte Angebote auf neue Filialen einer Kette auszurollen oder saisonale Angebote als Vorlage zu nutzen.

Duplicates an existing offer for other stores. Useful for rolling out proven offers to new chain branches or using seasonal offers as templates.

ParameterTypPflichtBeschreibung
offerIdstringJaID des zu duplizierenden AngebotsID of the offer to duplicate
targetStoreIdsstring[]JaStore-IDs für die KopienStore IDs for the copies
priceAdjustmentsobjectNeinOptionale Preisanpassungen pro Filiale. Schlüssel = Store-ID, Wert = { type: "percentage"|"fixed", value: number }Optional price adjustments per store. Key = store ID, value = { type: "percentage"|"fixed", value: number }

Response (200 OK)

200 OK
{ "success": true, "clonedOfferId": "def456", "clonedOfferIds": ["def456", "ghi789"], "groupId": "grp_clone_001", "storeCount": 2, "createdAt": "2026-03-04T13:49:00.000Z" }
In der Sandbox werden Angebote nicht tatsächlich erstellt. Die Response enthält immer "_sandbox": true und Mock-Daten.In sandbox mode, offers are not actually created. The response always contains "_sandbox": true and mock data.