Widget

The widget API serves the embeddable, merchant-branded gift card widget. Unlike other BFF sub-areas, these endpoints are CORS-public and do not require a merchant session, since the widget runs on third-party storefronts rather than inside the merchant dashboard.

Currently backed by demo data, not live merchant data

As of this writing, both endpoints below return fixed demo/fallback data rather than the requesting merchant's real configuration or catalog:

widget/config reads from an in-memory MerchantState object that nothing in the codebase ever populates. It is always empty, so the endpoint always returns its hardcoded fallback values ("Your Brand", EUR, a fixed theme palette), regardless of which merchant the widget is embedded for.
widget/giftcards reads from a hardcoded two-item demo catalog (src/app/api/bff/widget/_data.ts), not the real CatalogOffer model. A demo_merchant_123 override exists in the same file, but no other merchantId returns merchant-specific items.

The contract documented here (request/response shape) reflects the real, current code. The data behind it does not yet reflect real merchants. Treat this sub-area as a demo/preview surface, not a production-ready integration point, until this is wired to live merchant and catalog data.

GET /api/bff/widget/config

Returns branding and theme details for the widget to render.

{
  "ok": true,
  "data": {
    "merchant": {
      "name": "Your Brand",
      "logoUrl": "...",
      "currency": "EUR",
      "website": null
    },
    "theme": {
      "primaryColor": "#111827",
      "textColor": "#111827",
      "accentColor": "#4F46E5"
    }
  }
}

Cache-Control: no-store, max-age=0 is set on every response.

GET /api/bff/widget/giftcards

Returns the gift card catalog items the widget should display.

Auth

None. CORS-public; responds to OPTIONS preflight for GET.

Query parameters

Param	Type	Required	Notes
`merchantId`	string	no	Selects a merchant-specific item set if one exists in the demo data; otherwise the default demo set is returned.

Response

{
  "ok": true,
  "data": {
    "merchantId": "merchant-id-or-null",
    "items": [
      {
        "id": "gc_digital_25",
        "name": "Digital Gift Card",
        "description": "Delivered instantly via email",
        "currency": "EUR",
        "denominations": [25, 50, 75, 100],
        "imageUrl": "..."
      }
    ],
    "count": 1
  }
}

Errors

Status	Cause
400	`merchantId` present but not a non-empty string.

If a merchantId is supplied, a best-effort widget_catalog_viewed analytics event is recorded and an analytics session cookie may be set on the response.

Get widget configuration

Auth

Request

Response

List gift cards for the widget

Auth

Query parameters

Response

Errors

On this page