START HERE

Choose the smallest correct loyalty integration.

Embed a public rewards experience with Web Widget v1, or connect trusted commerce and customer flows through Loyumi’s secure HTTPS JSON API.

Developer docs · no accountSandbox firstAPI 1.13.0 · 121 operations · 106 paths

Open authenticated Sandbox Review the proof standard

CORRECT LOYALTY LOOP · VERIFICATION STANDARD

Know what to verify. Produce the evidence in Sandbox.

Use these acceptance criteria to plan the run, then sign in to Sandbox Lab. Only persisted records from your isolated workspace count as evidence.

VERIFICATION STANDARDA guide—not a generated result

Persisted Sandbox evidence required

01
Earn once
Send one completed purchase from your isolated Sandbox integration and confirm that exactly one source-linked value movement is persisted.
Keep: Request ID, source reference, transaction, and balance effect
02
Retry safely
Repeat the exact request with the same idempotency key and confirm that the original outcome returns without a second value movement.
Keep: Original receipt, replay result, and unchanged ledger count
03
Reverse the source
Return an identified order line and confirm that the reversal remains tied to the original purchase rather than becoming an unexplained adjustment.
Keep: Original line, reversal transaction, policy, and resulting balance
04
Prove the outcome
Create a recipient-bound Sandbox gift and inspect its governed state, entitlement, and every related value movement before accepting the result.
Keep: Gift state, recipient binding, entitlement, and ledger references

CHOOSE YOUR INTEGRATION

Start with the supported surface that fits.

Use Web Widget v1 for an embeddable customer surface and the secure HTTPS JSON API for commerce events. If your merchant team is still defining the program, send them to the plain-language guide first. Terminal users can follow the account-free CLI guide.

Business path

Merchant Guide

Define the business goal, program economics, customer promise, migration plan, and launch owners before integration.

Open merchant guide

Available Beta

Web Widget v1

Copy one versioned embed for a public rewards catalog. Personalized balances, history, and redemption require a short-lived session from your backend.

Embed the widget

Production API

Rewards Events API

Send purchases, returns, and other loyalty facts securely over HTTPS from your server with scoped credentials and stable idempotency keys.

Send your first event

QUICKSTART · ABOUT 10 MINUTES

Make one order earn exactly once.

This walkthrough uses synthetic Sandbox identifiers. Replace every angle-bracket value with one created in your own Sandbox.

1
Create and activate a Sandbox program
Choose a blueprint, review its earn rule, and keep production locked. Record the program ID.
2
Add one consenting test member
Use the same external customer ID your commerce system already knows. Confirm the member is active in the same environment.
3
Create a scoped server key
Create a Sandbox key with events:write. Copy it once and keep it on your server—never in storefront JavaScript or a mobile binary.
4
Send the completed order
Use the commerce order ID for both Idempotency-Key and sourceReference, and preserve each stable order-line ID as lineReference for exact returns. Amounts are integer minor units, so 2599 means 25.99 in a two-decimal currency.

cURL request

curl -X POST "https://app.loyumi.com/api/v1/events" \
  -H "Authorization: Bearer <sandbox-key>" \
  -H "X-Environment: <sandbox-environment-id>" \
  -H "Idempotency-Key: order-10042" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase.completed",
    "programId": "<program-id>",
    "externalCustomerId": "customer-123",
    "amountMinor": 2599,
    "channel": "web",
    "currency": "USD",
    "sourceReference": "order-10042",
    "items": [{
      "lineReference": "order-10042-line-1",
      "sku": "sku-…",
      "quantity": 1,
      "unitPriceMinor": 2599
    }]
  }'

201New award committed

{
  "id": "txn_…",
  "status": "committed",
  "requestId": "req_…",
  "evaluationMode": "receipt_time_current_configuration",
  "occurredAt": "2026-08-03T08:00:00.000Z",
  "receivedAt": "2026-08-03T08:00:01.000Z",
  "evaluatedAt": "2026-08-03T08:00:01.000Z",
  "currency": "USD",
  "totals": {
    "amountMinor": 2599, "subtotalMinor": 2599, "discountMinor": 0,
    "taxMinor": 0, "shippingMinor": 0, "eligibleAmountMinor": 2599
  },
  "linePointAttribution": [
    { "lineReference": "order-10042-line-1", "points": 25 }
  ],
  "member": {
    "id": "mem_…",
    "externalCustomerId": "customer-123",
    "tier": "Member"
  },
  "award": {
    "points": 25,
    "basePoints": 25,
    "campaignPoints": 0
  },
  "campaigns": [],
  "referral": null,
  "coupon": null
}

DEFINITION OF DONE

Finish with evidence, not hope.

A new order returns 201 and one transaction ID

The identical retry returns 200 and idempotent: true

The member endpoint shows the expected balance state

A line-selected return cites the original lineReference and returns 201

Logs retain requestId without storing secret keys

No Sandbox credential exists in client code

Build the mental model

Understand why these steps protect customer trust and financial control.

Read Concepts →

Know what to verify. Produce the evidence in Sandbox.

Start with the supported surface that fits.

Merchant Guide

Web Widget v1

Rewards Events API

Make one order earn exactly once.

Create and activate a Sandbox program

Add one consenting test member

Create a scoped server key

Send the completed order

Finish with evidence, not hope.