API reference

This is the entry point for the Globagift HTTP API reference. The API documented here is the BFF (Backend-for-Frontend) layer that the merchant dashboard, POS app, and embedded widget use, organised by sub-area.

Conventions

All BFF endpoints share the same conventions.

Base path

Endpoints are mounted under /api/bff/... on the portal host.

Authentication

Most BFF endpoints require an authenticated merchant session (cookie-based) and are gated by a merchant permission specific to that sub-area (for example, POS endpoints require the portal.pos permission). Admin users bypass per-permission checks. See Authentication for the session model.

The widget sub-area is the exception: those endpoints are CORS-public and require no session, since the widget is embedded on third-party storefronts rather than the merchant dashboard. This is called out on the widget page.

Response shape

Responses follow a consistent envelope:

{ "ok": true, "data": { } }

{ "ok": false, "error": { "message": "...", "code": "...", "status": 400, "details": { } } }

Some older routes return a bare { "error": "..." } on failure instead of the { "ok": false, "error": { ... } } envelope. Where that's the case it's called out on the specific endpoint.

Monetary amounts

Request bodies generally accept decimal amounts (for example "value": "25.00") in the merchant's display currency. Internally these are stored as integer minor units (cents). Responses from the portal's own database-backed endpoints return minor units; responses proxied directly from the upstream card network may return decimal amounts. This is noted per endpoint.

Sub-areas

• POS: issue and redeem gift cards in-store, look up a card by QR code.
• Widget: configuration and catalog for the embeddable widget. Currently backed by demo data, see the page for details.
• Offers: create, list, update, and change the status of gift card offers.
• Merchant orders: list orders, view order detail, and check a gift card's remaining balance.
• Analytics: overview, sales, redemption, and fraud insights.
• Settlements: list settlements, summary totals, and lookup by order or redemption.
• Reports export: download a CSV export of sales or redemptions for a date range.
• Merchant + team: merchant profile, stats, team members, retail stores, and gift cards management card lookup.
• Public merchant lookup and onboarding: storefront merchant/catalog lookup, and merchant onboarding submission, documents, and status check.