INTEGRATION SURFACES

Choose the honest integration boundary.

Use the available HTTP API today and evaluate the schema-driven widget contract without mistaking an early preview for a production SDK.

Developer docs · no accountSandbox firstContract version 1.2.0

AVAILABILITY

Use only what is actually published.

HTTP APIAvailable

Six environment-scoped operations represented by OpenAPI 3.1.

Open reference →

Official JavaScript SDKNot published

Use server-side fetch. No supported npm package is claimed.

Official iOS / Android SDKNot published

Call your own backend. Never embed a Loyumi secret in an app.

Widget schema & StudioLocal preview

Schema-driven drafts remain on the device. There is no production embed runtime.

Review scope →

WIDGET DOCUMENT · PREVIEW 0.1

A portable shape for an early design draft.

The preview separates content structure from merchant styling. The published JSON Schema validates the current Studio document shape; it is an evaluation contract, not a stable production SDK guarantee.

Illustrative local draft

{
  "$schema": "https://docs.loyumi.com/schemas/widget-page.v0.1.json",
  "schemaVersion": 1,
  "id": "experience_sandbox",
  "name": "Customer loyalty experience",
  "revision": 1,
  "updatedAt": "2026-08-02T08:00:00.000Z",
  "theme": {
    "accent": "#176348",
    "background": "#f4f6f4",
    "surface": "#ffffff",
    "text": "#18211d",
    "radius": 18,
    "font": "system"
  },
  "canvas": { "maxWidth": 920, "gap": 14 },
  "blocks": [
    {
      "id": "member-balance",
      "type": "balance",
      "props": {
        "eyebrow": "Available balance",
        "unit": "points",
        "balance": 0,
        "helper": "Updated after each eligible purchase",
        "showHelper": true
      },
      "visibility": { "mobile": true, "desktop": true }
    },
    {
      "id": "member-tier",
      "type": "tier-progress",
      "props": {
        "title": "Your status",
        "currentTier": "Member",
        "nextTier": "Next tier",
        "currentValue": 0,
        "targetValue": 1000,
        "unit": "points"
      },
      "visibility": { "mobile": true, "desktop": true }
    }
  ]
}

Download the Widget Studio JSON Schema →

balance

Shows available points and supporting copy.

tier-progress

Shows current tier and a qualification threshold.

reward-catalog

Presents a reward supplied by the host.

earn-preview

Previews potential earnings without mutating value.

referral

Explains a referral benefit and host-owned action.

activity

Shows attributable earn and redeem activity.

SECURITY BOUNDARY

The customer surface never owns a secret key.

Web or mobile UIAuthenticated customer session

→

Your backendAuthorization and data shaping

→

Loyumi APIScoped server credential

Use your backend to map the signed-in customer to an external customer ID.
Return only the fields the widget needs.
Authorize redemption or profile actions again on the server.
Keep environment IDs and secret keys out of browser bundles, local drafts, analytics, and screenshots.