TASK GUIDES

Integrate the complete customer lifecycle.

Follow tested request shapes for earning, reading balances, returns, engagement events, offers, and signed outcomes.

Developer docs · no accountSandbox firstContract version 1.2.0

GUIDE 01 · EARN

Award a completed purchase.

Create the program, active member, and events:write key in the same environment before sending the event.

POST /api/v1/events

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",
    "sourceReference": "order-10042"
  }'

GUIDE 02 · READ

Read a member and their program balances.

URL-encode the external customer ID. The response includes identity status, consent state, tier, qualification points, and account balances by program.

Requires members:read.
Uses the same X-Environment as the award.
Returns Cache-Control: no-store.

Member request

GET /api/v1/members/customer-123
Authorization: Bearer <sandbox-key>
X-Environment: <sandbox-environment-id>

GUIDE 03 · RETURN

Claw back a full or partial order.

Reference the original order and send the amount being returned as returnAmountMinor. The endpoint derives the related program and bounds the proportional clawback.

POST /api/v1/returns

curl -X POST "https://app.loyumi.com/api/v1/returns" \
  -H "Authorization: Bearer <sandbox-key>" \
  -H "X-Environment: <sandbox-environment-id>" \
  -H "Idempotency-Key: return-10042-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceReference": "order-10042",
    "returnReference": "return-10042-1",
    "returnAmountMinor": 1000
  }'

GUIDE 04 · ENGAGE

Advance a challenge with a registered event.

The event definition must already be active in the selected environment and the member must exist. Use a source reference that identifies the real behavior once.

Requires events:write.
Requires an idempotency key.
Returns any completed challenge awards in awards.

Request body

{
  "type": "profile.completed",
  "externalCustomerId": "customer-123",
  "sourceReference": "profile-customer-123-v1",
  "occurredAt": "2026-08-02T08:00:00.000Z",
  "attributes": { "source": "account_page" }
}

GUIDE 05 · OFFERS

Evaluate a cart without mutating it.

Send positive integer minor-unit prices. The result explains subtotal, discount, total, eligible effects, and coupon validity.

POST /api/v1/offers/evaluate

{
  "programId": "prg_…",
  "couponCode": "WELCOME10",
  "items": [
    { "sku": "SKU-42", "category": "coffee", "quantity": 2, "unitPriceMinor": 650 }
  ]
}

Inspect every field

Use the rendered reference for exact requirements and status codes.

Open API reference →