LoyumiDeveloper docs
API REFERENCE · 1.2.0

Every public endpoint, rendered.

Inspect authentication, headers, fields, response codes, and examples without downloading or reading raw OpenAPI JSON.

Developer docs · no accountSandbox firstContract version 1.2.0
AUTHENTICATION

Every request is environment-scoped.

Keys belong to one environment, carry explicit scopes, and should live only in trusted server infrastructure.

AuthorizationRequiredBearer <key>
X-EnvironmentRequiredEnvironment ID that owns the key
Idempotency-KeyMutationsStable business-event identity
X-Request-IdOptionalYour trace ID; otherwise Loyumi creates one
6 PUBLIC OPERATIONS

Endpoint reference.

POST/api/v1/eventsPost a completed purchase and award points

Evaluates the active earn rule, tier multiplier, audiences, campaign caps, pending policy, expiration policy, and member limit in one idempotent transaction. Requires events:write.

Scope events:writeIdempotency required

JSON body

typerequiredconstant: purchase.completed

programIdrequiredstring

externalCustomerIdrequiredstring

amountMinorrequiredinteger

Completed order value in integer minor currency units.

channelrequiredweb | store | app

sourceReferencerequiredstring

Stable order reference from the commerce system.

couponCodeoptionalstring

Optional coupon code associated with this purchase.

itemsoptionalarray<CartItem>

Request body
{
  "type": "purchase.completed",
  "programId": "prg_…",
  "externalCustomerId": "customer-123",
  "amountMinor": 2599,
  "channel": "web",
  "sourceReference": "order-10042"
}
Example response
{
  "id": "txn_…",
  "status": "committed",
  "requestId": "req_…",
  "member": {
    "id": "mem_…",
    "externalCustomerId": "customer-123",
    "tier": "Member"
  },
  "award": {
    "points": 25,
    "basePoints": 25,
    "campaignPoints": 0
  },
  "campaigns": [],
  "referral": null,
  "coupon": null
}

Responses

200

Existing transaction returned for a repeated idempotency key.

201

New award committed.

400

Invalid JSON or missing Idempotency-Key.

401

Credential or X-Environment is absent, invalid, expired, revoked, or crossed between environments.

403

Credential lacks events:write.

404

Program or active member was not found in the selected environment.

409

Production is locked, or a governed policy, cap, or state conflict blocked the award.

413

JSON body exceeds 128 KiB.

415

Content-Type must be application/json.

422

Event type or required field is invalid.

429

Credential exceeded 600 requests in one minute. Honor Retry-After.

500

Internal processing error. Retry safely with the same key and body.

POST/api/v1/returnsReturn all or part of an order and claw back points

Uses the original source reference to derive the related order and program. Calculates a bounded proportional clawback from the order's remaining active and pending point lots. Requires events:write.

Scope events:writeIdempotency required

JSON body

sourceReferencerequiredstring

Reference of the original completed order.

returnReferencerequiredstring

Stable identity for this full or partial return.

returnAmountMinorrequiredinteger

Amount being returned in integer minor currency units.

Request body
{
  "sourceReference": "order-10042",
  "returnReference": "return-10042-1",
  "returnAmountMinor": 1000
}
Example response
{
  "id": "txn_…",
  "status": "committed",
  "requestId": "req_…",
  "return": {
    "sourceReference": "order-10042",
    "returnReference": "return-10042-1",
    "returnAmountMinor": 1000,
    "pointsClawedBack": 9,
    "orderStatus": "partially_returned"
  }
}

Responses

200

Existing clawback transaction returned for a repeated idempotency key.

201

Return and proportional clawback committed.

400

Invalid JSON or missing Idempotency-Key.

401

Invalid credential or environment.

403

Credential lacks events:write.

404

Original order was not found.

409

Production is locked, return exceeds remaining order value, or original points cannot be clawed back.

413

JSON body exceeds 128 KiB.

415

Content-Type must be application/json.

422

sourceReference, returnReference, or positive returnAmountMinor is invalid.

429

Rate limit exceeded. Honor Retry-After.

500

Internal processing error.

POST/api/v1/custom-eventsPost a registered engagement event

Records a governed event and advances matching challenges atomically, returning any awards created when a target completes. Requires events:write.

Scope events:writeIdempotency required

JSON body

typerequiredstring

Name of an active event definition in the selected environment.

externalCustomerIdrequiredstring

sourceReferencerequiredstring

occurredAtoptionalstring · date-time

attributesoptionalobject

Request body
{
  "type": "profile.completed",
  "externalCustomerId": "customer-123",
  "sourceReference": "profile-customer-123-v1",
  "occurredAt": "2026-08-02T08:00:00.000Z",
  "attributes": { "source": "account_page" }
}
Example response
{
  "id": "evt_…",
  "status": "accepted",
  "requestId": "req_…",
  "awards": []
}

Responses

200

Existing event returned for a repeated source reference.

201

Event accepted and challenge awards returned.

400

Invalid JSON.

401

Invalid credential or environment.

403

Credential lacks events:write.

404

Active event definition or member was not found.

413

JSON body exceeds 128 KiB.

415

Content-Type must be application/json.

422

Idempotency-Key or a required event field is missing.

429

Rate limit exceeded. Honor Retry-After.

500

Internal processing error.

POST/api/v1/offers/evaluateEvaluate active cart offers

Returns a deterministic discount plan under exclusive, stack, and best-value policies without mutating the cart or consuming a coupon. Requires events:write.

Scope events:write

JSON body

programIdoptionalstring

Required to include program-scoped offers.

couponCodeoptionalstring

itemsrequiredarray<CartItem>

Request body
{
  "programId": "prg_…",
  "couponCode": "WELCOME10",
  "items": [
    { "sku": "SKU-42", "category": "coffee", "quantity": 2, "unitPriceMinor": 650 }
  ]
}
Example response
{
  "requestId": "req_…",
  "subtotalMinor": 1300,
  "discountMinor": 130,
  "totalMinor": 1170,
  "effects": [],
  "coupon": { "code": "WELCOME10", "valid": true }
}

Responses

200

Applicable effects, coupon validity, subtotal, discount, and total returned.

400

Invalid JSON.

401

Invalid credential or environment.

403

Credential lacks events:write.

413

JSON body exceeds 128 KiB.

415

Content-Type must be application/json.

422

Cart is empty or contains an item without a SKU or positive unitPriceMinor.

429

Rate limit exceeded. Honor Retry-After.

500

Internal processing error.

POST/api/v1/choice-benefitsClaim a milestone choice benefit

Fulfills one eligible reward choice without spending points and decrements the member's remaining selections. Requires events:write.

Scope events:writeIdempotency required

JSON body

externalCustomerIdrequiredstring

choiceSetIdrequiredstring

rewardIdrequiredstring

sourceReferencerequiredstring

Request body
{
  "externalCustomerId": "customer-123",
  "choiceSetId": "choice_…",
  "rewardId": "rwd_…",
  "sourceReference": "anniversary-2026-customer-123"
}
Example response
{
  "id": "ful_…",
  "state": "fulfilled",
  "requestId": "req_…",
  "choice": {
    "setId": "choice_…",
    "rewardId": "rwd_…",
    "rewardName": "Anniversary benefit",
    "choicesRemaining": 0
  }
}

Responses

200

Existing fulfillment returned for a repeated idempotency key.

201

Choice fulfilled and remaining selections returned.

400

Invalid JSON.

401

Invalid credential or environment.

403

Credential lacks events:write.

404

Member or active choice set was unavailable.

409

No eligible choice or selected reward inventory remains.

413

JSON body exceeds 128 KiB.

415

Content-Type must be application/json.

422

Idempotency-Key or a required choice field is missing.

429

Rate limit exceeded. Honor Retry-After.

500

Internal processing error.

GET/api/v1/members/{externalId}Get a member, balances, tier, and qualification state

Returns the member identity state and consent status plus every program profile and its available, pending, and reserved account balances. Requires members:read.

Scope members:read
Request
GET /api/v1/members/customer-123
Authorization: Bearer <sandbox-key>
X-Environment: <sandbox-environment-id>
Example response
{
  "requestId": "req_…",
  "member": {
    "id": "mem_…",
    "externalCustomerId": "customer-123",
    "status": "active",
    "consentStatus": "granted"
  },
  "programs": [
    {
      "programId": "prg_…",
      "tier": "Member",
      "qualificationPoints": 25,
      "balances": [
        { "accountType": "member", "available": 25, "pending": 0, "reserved": 0 }
      ]
    }
  ]
}

Responses

200

Member, consent state, program profiles, tiers, qualification totals, and account balances returned with Cache-Control: no-store.

401

Invalid credential or environment.

403

Credential lacks members:read.

404

Member was not found in the selected environment.

429

Rate limit exceeded. Honor Retry-After.

500

Internal processing error.

Download the OpenAPI 3.1 document →
ERROR ENVELOPE

Fix, wait, or safely retry.

Error shape
{
  "error": {
    "code": "invalid_event",
    "message": "A human-readable explanation",
    "requestId": "req_…"
  }
}
400
Fix JSON or a missing idempotency key

Do not retry unchanged.

401
Fix the key or environment

The credential is absent, invalid, expired, revoked, or crossed between environments.

403
Add the required scope

The key is valid but not authorized.

404
Check the referenced subject

Member, order, event definition, or resource was not found.

409
Resolve the state conflict

Production lock, limits, balance, inventory, or eligibility blocked the operation.

413 / 415 / 422
Fix the payload

Keep JSON under 128 KiB, use application/json, and satisfy the contract.

429
Wait and retry

Honor Retry-After and keep the same idempotency key and body.

5xx
Retry safely

Use exponential backoff and preserve requestId for support.