API REFERENCE · 1.13.0

Every public endpoint, rendered.

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

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

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

121 PUBLIC OPERATIONS · 15 GROUPS

Endpoint reference.

Operations are grouped by job. Open one endpoint to see every path, query, and header parameter, the JSON request contract, and the named response schema with its top-level fields.

3 operations

Commerce

Earn, return, and offer-evaluation operations

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

Evaluates the selected immutable earn rules, tier multiplier, contextual audiences, campaign caps, pending policy, expiration policy, and member limit in one idempotent transaction. Receipt-time current-configuration evaluation is the default. For a late event, event-time evaluation can explicitly pin a configuration published and effective at occurredAt plus historical member-tier evidence. Currency must match the program, and normalized line references preserve point attribution for later item-selected returns. Requires events:write.

Scope events:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `PurchaseRequest`

typerequiredconstant: purchase.completed

programIdrequiredstring

minimum length 1

externalCustomerIdrequiredstring

minimum length 1

amountMinorrequiredinteger

Merchant-normalized completed order value in the configured program currency's integer minor units.

currencyoptionalstring

ISO 4217 transaction currency. Must match the program's configured currency.

occurredAtoptionalstring · date-time

Merchant business occurrence timestamp. It is audit evidence under the default receipt-time policy and becomes the evaluation clock only when event_time_pinned_configuration is explicitly selected.

storeIdoptionalstring

minimum length 1 · maximum length 200

terminalIdoptionalstring

minimum length 1 · maximum length 200

marketoptionalstring

minimum length 1 · maximum length 100

localeoptionalstring

minimum length 1 · maximum length 100

deviceTypeoptionalstring

minimum length 1 · maximum length 100

orderTypeoptionalstring

minimum length 1 · maximum length 100

salesAssociateIdoptionalstring

minimum length 1 · maximum length 200

customerTagsoptionalarray<string>

maximum 50 items

attributesoptionalPurchaseAttributes

contextoptionalPurchaseNestedContext

subtotalMinoroptionalinteger

minimum 0

discountMinoroptionalinteger

minimum 0

taxMinoroptionalinteger

minimum 0

shippingMinoroptionalinteger

minimum 0

eligibleAmountMinoroptionalinteger

minimum 0

sourceAmountMinoroptionalinteger

Original pre-normalization transaction amount; requires the complete FX evidence group.

sourceCurrencyoptionalstring

fxRateoptionalstring

fxRateSourceoptionalstring

minimum length 1 · maximum length 200

fxRateAtoptionalstring · date-time

sourceReferencerequiredstring

Stable order reference from the commerce system.

couponCodeoptionalstring

Optional coupon code associated with this purchase.

itemsoptionalarray<CartItem>

Normalized order lines whose eligible values feed base earning and whose stable references preserve line-attributed returns. Current built-in purchase rules do not interpret arbitrary line attributes.

Request body

{
  "type": "purchase.completed",
  "programId": "prg_…",
  "externalCustomerId": "customer-123",
  "amountMinor": 2599,
  "channel": "web",
  "currency": "USD",
  "occurredAt": "2026-08-03T08:00:00.000Z",
  "storeId": "store-…",
  "sourceReference": "order-10042",
  "items": [{
    "lineReference": "order-10042-line-1",
    "sku": "sku-…",
    "quantity": 1,
    "unitPriceMinor": 2599
  }]
}

Example response

{
  "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
}

Typed responses

200

Existing transaction returned for a repeated idempotency key.

IdempotentOutcome

idrequiredstring
statusoptionalstring
stateoptionalstring
idempotentrequiredconstant: true
requestIdrequiredstring

201

New award committed.

PurchaseOutcome

idrequiredstring
statusrequiredconstant: committed
requestIdrequiredstring
evaluationModerequiredreceipt_time_current_configuration | event_time_pinned_configuration
occurredAtrequiredstring · date-time
receivedAtrequiredstring · date-time
evaluatedAtrequiredstring · date-time
currencyrequiredstring
totalsrequiredCommerceTotals
linePointAttributionrequiredarray<LinePointAttribution>
memberrequiredobject
awardrequiredobject
campaignsrequiredarray<CampaignDecision>
referralrequiredvalue
couponrequiredstring | null
evaluationAtrequiredstring · date-time
configurationVersionrequiredinteger
ruleDecisionsrequiredarray<EarnRuleDecision>

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

A governed privacy deletion tombstoned the historic response, so this Idempotency-Key can no longer replay it. The deletion supersedes replay; reconcile durable state or begin a genuinely new permitted operation.

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

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. Item-selected returns validate stable line references and remaining quantities, derive the exact returned line amount, and reverse the points attributed to those lines. Legacy amount-only returns retain bounded proportional clawback semantics. Requires events:write.

Scope events:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `ReturnRequest`

sourceReferencerequiredstring

Reference of the original completed order.

returnReferencerequiredstring

Stable identity for this full or partial return.

returnAmountMinoroptionalinteger

Legacy amount-based return value, or an integrity check for an item-selected return.

itemsoptionalarray<object>

minimum 1 item · maximum 500 items

Request body

{
  "sourceReference": "order-10042",
  "returnReference": "return-10042-1",
  "items": [
    { "lineReference": "order-10042-line-1", "quantity": 1 }
  ]
}

Example response

{
  "id": "txn_…",
  "status": "committed",
  "requestId": "req_…",
  "return": {
    "id": "ret_…",
    "sourceReference": "order-10042",
    "returnReference": "return-10042-1",
    "returnAmountMinor": 2599,
    "pointsClawedBack": 25,
    "orderStatus": "returned",
    "items": [{
      "lineReference": "order-10042-line-1", "quantity": 1,
      "amountMinor": 2599, "pointsClawedBack": 25
    }]
  }
}

Typed responses

200

Existing clawback transaction returned for a repeated idempotency key.

ReturnIdempotentOutcome

idrequiredstring
statusrequiredstring
idempotentrequiredconstant: true
requestIdrequiredstring
returnoptionalvalue

201

Return and proportional clawback committed.

ReturnOutcome

idrequiredstring
statusrequiredconstant: committed
requestIdrequiredstring
returnrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

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

Returns a deterministic contextual discount plan under exclusive, stack, and best-value policies without mutating the cart or consuming a coupon. The request can supply member identity, channel, currency, business occurrence time, market, store, device, order, customer-tag, custom, and normalized line context. New credentials should use offers:evaluate; events:write remains accepted for API 1.7 compatibility.

Scope offers:evaluate

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `OfferEvaluationRequest`

programIdoptionalstring

Required to include program-scoped offers.

externalCustomerIdoptionalstring

minimum length 1 · maximum length 200

couponCodeoptionalstring

amountMinoroptionalinteger

Optional reconciled order total. When omitted, the evaluator derives it from normalized items and optional shippingMinor.

currencyoptionalstring

occurredAtoptionalstring · date-time

Merchant business timestamp retained as decision context; it does not select a historical offer configuration.

storeIdoptionalstring

minimum length 1 · maximum length 200

terminalIdoptionalstring

minimum length 1 · maximum length 200

marketoptionalstring

minimum length 1 · maximum length 100

localeoptionalstring

minimum length 1 · maximum length 100

deviceTypeoptionalstring

minimum length 1 · maximum length 100

orderTypeoptionalstring

minimum length 1 · maximum length 100

salesAssociateIdoptionalstring

minimum length 1 · maximum length 200

customerTagsoptionalarray<string>

maximum 50 items

attributesoptionalobject

contextoptionalobject

subtotalMinoroptionalinteger

minimum 0

discountMinoroptionalinteger

minimum 0

taxMinoroptionalinteger

minimum 0

shippingMinoroptionalinteger

minimum 0

eligibleAmountMinoroptionalinteger

minimum 0

sourceAmountMinoroptionalinteger

minimum 1

sourceCurrencyoptionalstring

fxRateoptionalstring

fxRateSourceoptionalstring

minimum length 1 · maximum length 200

fxRateAtoptionalstring · date-time

itemsrequiredarray<CartItem>

minimum 1 item · maximum 500 items

Request body

{
  "programId": "prg_…",
  "externalCustomerId": "customer-123",
  "couponCode": "WELCOME10",
  "channel": "web",
  "currency": "USD",
  "market": "US",
  "items": [
    {
      "lineReference": "cart-line-1", "sku": "SKU-42",
      "category": "coffee", "quantity": 2, "unitPriceMinor": 650
    }
  ]
}

Example response

{
  "requestId": "req_…",
  "evaluationMode": "receipt_time_current_configuration",
  "occurredAt": "2026-08-03T08:00:00.000Z",
  "receivedAt": "2026-08-03T08:00:00.000Z",
  "evaluatedAt": "2026-08-03T08:00:00.000Z",
  "currency": "USD",
  "totals": {
    "amountMinor": 1300, "subtotalMinor": 1300, "discountMinor": 0,
    "taxMinor": 0, "shippingMinor": 0, "eligibleAmountMinor": 1300
  },
  "subtotalMinor": 1300,
  "discountMinor": 130,
  "totalMinor": 1170,
  "member": { "id": "mem_…", "externalCustomerId": "customer-123", "tier": "Member" },
  "effects": [],
  "coupon": { "code": "WELCOME10", "valid": true }
}

Typed responses

200

Contextual effects, eligibility reasons, matched line references, member context, coupon validity, and reconciled totals returned without mutation.

OfferEvaluationOutcome

requestIdrequiredstring
evaluationModerequiredconstant: receipt_time_current_configuration
occurredAtrequiredstring · date-time
receivedAtrequiredstring · date-time
evaluatedAtrequiredstring · date-time
currencyrequiredstring | null
totalsrequiredCommerceTotals
subtotalMinorrequiredinteger
discountMinorrequiredinteger
totalMinorrequiredinteger
memberrequiredvalue
effectsrequiredarray<object>
couponrequiredvalue

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

2 operations

Engagement

Registered custom events and milestone benefits

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

Records a governed event and advances each matching challenge with an atomic database transition. Ledger, balance, and lot writes are conditional on the exact event that wins a completion transition, so concurrent requests cannot double-award or lose progress. Requires events:write.

Scope events:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `CustomEventRequest`

typerequiredstring

Name of an active event definition in the selected environment.

externalCustomerIdrequiredstring

minimum length 1 · maximum length 200

sourceReferencerequiredstring

minimum length 1 · maximum length 200

occurredAtoptionalstring · date-time

maximum length 64

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": []
}

Typed responses

200

Durable event and challenge-award outcome replayed for the same Idempotency-Key and exact request payload.

CustomEventOutcome

idrequiredstring
statusrequiredconstant: accepted
requestIdrequiredstring
idempotentoptionalboolean
awardsoptionalarray<object>

201

Event accepted and challenge awards returned.

CustomEventOutcome

idrequiredstring
statusrequiredconstant: accepted
requestIdrequiredstring
idempotentoptionalboolean
awardsoptionalarray<object>

400

Invalid JSON.

ApiError

errorrequiredobject

401

Invalid credential or environment.

ApiError

errorrequiredobject

403

Credential lacks events:write.

ApiError

errorrequiredobject

404

Active event definition or member was not found.

ApiError

errorrequiredobject

409

Idempotency-Key payload mismatch, production lock, or sourceReference already belongs to another event in this environment.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

JSON body exceeds 128 KiB.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

Idempotency-Key or a required event field is missing.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error.

ApiError

errorrequiredobject

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

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `ChoiceBenefitRequest`

externalCustomerIdrequiredstring

minimum length 1

choiceSetIdrequiredstring

minimum length 1

rewardIdrequiredstring

minimum length 1

sourceReferencerequiredstring

minimum length 1

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
  }
}

Typed responses

200

Existing fulfillment returned for a repeated idempotency key.

ChoiceBenefitOutcome

idrequiredstring
staterequiredstring
requestIdrequiredstring
idempotentoptionalboolean
choiceoptionalobject

201

Choice fulfilled and remaining selections returned.

ChoiceBenefitOutcome

idrequiredstring
staterequiredstring
requestIdrequiredstring
idempotentoptionalboolean
choiceoptionalobject

400

Invalid JSON.

ApiError

errorrequiredobject

401

Invalid credential or environment.

ApiError

errorrequiredobject

403

Credential lacks events:write.

ApiError

errorrequiredobject

404

Member or active choice set was unavailable.

ApiError

errorrequiredobject

409

No eligible choice or selected reward inventory remains.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

JSON body exceeds 128 KiB.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

Idempotency-Key or a required choice field is missing.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error.

ApiError

errorrequiredobject

7 operations

Members

Member enrollment, profile updates, and balance reads

POST/api/v1/membersCreate a member identity

Creates one environment-scoped member identity and consent record without enrolling any loyalty program. Repeating an existing externalCustomerId returns the existing member. Use PUT /members/{externalId}/programs/{programId} for explicit program enrollment. Legacy non-empty programIds input is rejected with explicit_program_enrollment_required. Requires members:write.

Scope members:write

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

externalCustomerIdrequiredstring

minimum length 1 · maximum length 200

displayNamerequiredstring

minimum length 1 · maximum length 200

emailoptionalstring · email

maximum length 320

phoneoptionalstring

minimum length 1 · maximum length 64

consentStatusoptionalunknown | opted_in | opted_out

default unknown

noticeVersionoptionalstring

Merchant notice or consent-policy version shown to the member.

Request body

{
  "externalCustomerId": "<external-customer-id>",
  "displayName": "<display-name>",
  "email": "<customer-email>",
  "consentStatus": "opted_in",
  "noticeVersion": "<identity-notice-version>"
}

Example response

{
  "requestId": "req_…",
  "member": {
    "id": "mem_…",
    "externalCustomerId": "<external-customer-id>",
    "status": "active",
    "consentStatus": "opted_in"
  },
  "idempotent": false
}

Typed responses

200

Existing member returned idempotently.

MemberCreateOutcome

requestIdrequiredstring
idempotentrequiredboolean
memberrequiredobject

201

Member identity, consent evidence, and audit event created; no program enrollment is created.

MemberCreateOutcome

requestIdrequiredstring
idempotentrequiredboolean
memberrequiredobject

401

Invalid credential or environment.

ApiError

errorrequiredobject

403

Credential lacks members:write.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

Member identity or consent fields are invalid, or legacy non-empty programIds requires the explicit program-enrollment operation.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error.

ApiError

errorrequiredobject

GET/api/v1/membersList and exactly filter members

List and exactly filter members. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires members:read.

Scope members:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

externalIdqueryoptionalstring

emailqueryoptionalstring · email

maximum length 320

statusqueryoptionalactive | suspended | closed | deleted

Typed responses

200

Request completed.

MemberListOutcome

requestIdrequiredstring
membersrequiredarray<MemberListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

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

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

externalIdpathrequiredstring

minimum length 1

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 }
      ]
    }
  ]
}

Typed responses

200

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

MemberDetailOutcome

requestIdrequiredstring
memberrequiredobject
programsrequiredarray<object>

401

Invalid credential or environment.

ApiError

errorrequiredobject

403

Credential lacks members:read.

ApiError

errorrequiredobject

404

Member was not found in the selected environment.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error.

ApiError

errorrequiredobject

PATCH/api/v1/members/{externalId}Update a member while preserving consent history

Updates supported profile, status, and consent fields without changing the stable external customer identity. Consent changes append evidence instead of overwriting history. Requires members:write. Email changes fail with 409 customer_verification_email_locked while an unexpired customer-link ceremony or pending/active Customer Verification link exists; use customer unlink or governed revoke-only recovery first. Email changes fail with 409 customer_verification_email_locked while an unexpired customer-link ceremony or pending/active Customer Verification link exists; use customer unlink or governed revoke-only recovery first.

Scope members:write

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

externalIdpathrequiredstring

minimum length 1

JSON body · `object`

displayNameoptionalstring

minimum length 1 · maximum length 200

emailoptionalstring | null · email

maximum length 320

phoneoptionalstring | null

minimum length 1 · maximum length 64

statusoptionalactive | suspended | closed

consentStatusoptionalunknown | opted_in | opted_out

noticeVersionoptionalstring

minimum length 1 · maximum length 100

Request body

PATCH /api/v1/members/customer-123
Authorization: Bearer <sandbox-key>
X-Environment: <sandbox-environment-id>
Content-Type: application/json

{
  "displayName": "Jordan Lee",
  "consentStatus": "opted_in",
  "noticeVersion": "rewards-notice-2026-08"
}

Example response

{
  "requestId": "req_…",
  "member": {
    "id": "mem_…",
    "externalCustomerId": "customer-123",
    "displayName": "Jordan Lee",
    "status": "active",
    "consentStatus": "opted_in"
  }
}

Typed responses

200

Member updated and audit evidence appended.

MemberUpdateOutcome

requestIdrequiredstring
memberrequiredobject

401

Invalid credential or environment.

ApiError

errorrequiredobject

403

Credential lacks members:write.

ApiError

errorrequiredobject

404

Member was not found in the selected environment.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The member update is invalid.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error.

ApiError

errorrequiredobject

DELETE/api/v1/members/{externalId}Anonymize a member under governed retention

Tombstones the member profile, withdraws consent, and scrubs known structured identifier copies in operational records. Governed value, transaction, consent, and audit records remain explainable, and merchant-supplied references or evidence remain subject to the merchant's documented legal and financial retention policy. This operation is not a promise that arbitrary merchant-authored text is globally de-identified.

Scope members:deleteIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

externalIdpathrequiredstring

minimum length 1

JSON body · `object`

deletionReferencerequiredstring

Merchant privacy case or erasure request reference.

reasonrequiredstring

minimum length 1

Typed responses

200

Identity anonymized or original response replayed. Retained record classes are explicit in the response.

MemberAnonymizationOutcome

requestIdrequiredstring
idempotentoptionalboolean
memberrequiredobject
retainedrequiredstring

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

PUT/api/v1/members/{externalId}/programs/{programId}Explicitly enroll a member in one program

Creates the member's program profile and available account under explicit opted-in consent evidence. Existing structurally consistent accounts and balances are preserved during re-enrollment; value is never reset. The member and program must be active and writable. Requires members:write and Idempotency-Key.

Scope members:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

externalIdpathrequiredstring

minimum length 1 · maximum length 200

programIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `MemberProgramEnrollmentRequest`

consentStatusrequiredconstant: opted_in

noticeVersionrequiredstring

minimum length 1 · maximum length 100

evidencerequiredobject

Merchant-controlled consent or withdrawal evidence. Do not place secrets in this object.

Typed responses

200

Existing enrollment completed or original result replayed.

MemberProgramEnrollmentOutcome

requestIdrequiredstring
idempotentrequiredboolean
enrollmentrequiredobject
receiptrequiredMemberProgramEnrollmentReceipt

201

Program profile or available account created.

MemberProgramEnrollmentOutcome

requestIdrequiredstring
idempotentrequiredboolean
enrollmentrequiredobject
receiptrequiredMemberProgramEnrollmentReceipt

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

DELETE/api/v1/members/{externalId}/programs/{programId}Governedly unenroll a member from one program

Removes only the program profile after proving available, pending, and reserved balances are zero and no reserved redemption remains. It expires scoped available choice awards and cancels scoped quoted redemption quotes while retaining ledger, transaction, consent, audit, and reward history. An already absent profile returns an idempotent 200 result. This corrective operation remains available while Production is locked. Requires members:write and Idempotency-Key.

Scope members:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

externalIdpathrequiredstring

minimum length 1 · maximum length 200

programIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `MemberProgramUnenrollmentRequest`

reasonrequiredstring

minimum length 1 · maximum length 1000

evidencerequiredobject

Merchant-controlled consent or withdrawal evidence. Do not place secrets in this object.

noticeVersionoptionalstring

minimum length 1 · maximum length 100

Typed responses

200

Program enrollment removed or confirmed absent.

MemberProgramUnenrollmentOutcome

requestIdrequiredstring
idempotentrequiredboolean
enrollmentrequiredobject
receiptrequiredvalue

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

12 operations

Redemptions

Quoted, reserved, committed, released, expired, reversed, fulfilled, and disputed point spends

POST/api/v1/redemption-quotesQuote a governed point redemption

Pins the program version, reward version, point cost, fulfillment type, inventory availability, balance, and point-lot lifetime for 30 to 900 seconds. A quote does not move value.

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

programIdrequiredstring

minimum length 1

externalCustomerIdrequiredstring

minimum length 1

sourceReferencerequiredstring

minimum length 1 · maximum length 200

rewardIdoptionalstring

minimum length 1

pointsoptionalinteger

minimum 1

ttlSecondsoptionalinteger

minimum 30 · maximum 900 · default 300

Typed responses

200

Original quote replayed for the same idempotency key and identical payload.

RedemptionQuoteOutcome

requestIdrequiredstring
idempotentoptionalboolean
quoterequiredobject

201

Bounded quote created without moving points or inventory.

RedemptionQuoteOutcome

requestIdrequiredstring
idempotentoptionalboolean
quoterequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptionsReserve points and reward inventory from a quote

Atomically consumes an unexpired quote, moves available points into a reserved account, preserves point-lot provenance, and reserves finite reward inventory.

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

quoteIdrequiredstring

minimum length 1

Typed responses

200

Original reservation replayed for the same idempotency key and identical payload.

RedemptionReservationOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

201

Points and any finite inventory reserved atomically.

RedemptionReservationOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/redemptionsList and filter redemptions

List and filter redemptions. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires redemptions:read.

Scope redemptions:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

externalCustomerIdqueryoptionalstring

sourceReferencequeryoptionalstring

statequeryoptionalreserved | committed | released | expired | reversed

Typed responses

200

Request completed.

RedemptionListOutcome

requestIdrequiredstring
redemptionsrequiredarray<RedemptionListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/redemptions/{redemptionId}Get redemption financial, fulfillment, and dispute state

Scope redemptions:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

minimum length 1

Typed responses

200

Current financial state, transaction links, fulfillment state, and disputes returned with no-store.

RedemptionDetailOutcome

requestIdrequiredstring
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/commitCommit a reserved redemption

Moves reserved points to program treasury. Coupon and external rewards require a provider and enter pending fulfillment; native entitlements are fulfilled in the same transaction.

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

JSON body · `object`

fulfillmentReferenceoptionalstring

Optional connector reference when it already exists.

provideroptionalstring

Required for coupon and external fulfillment types.

Typed responses

200

Original commit replayed.

RedemptionCommitOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

201

Redemption committed and fulfillment evidence recorded.

RedemptionCommitOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/releaseRelease a reservation

Returns still-valid reserved point lots to available balance, records expired portions, and releases finite inventory.

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

Typed responses

200

Original release replayed.

RedemptionReleaseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

201

Reservation released with point-lot provenance preserved.

RedemptionReleaseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/expireExpire a reservation after its deadline

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

Typed responses

200

Original expiration replayed.

RedemptionReleaseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

201

Past-due reservation expired; valid points returned and expired points recorded.

RedemptionReleaseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/reverseReverse a committed redemption

Creates a linked compensating transaction. A fulfilled reward also requires a fulfillmentCancellationReference.

Scope redemptions:reverseIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

JSON body · `object`

reasonCoderequiredstring

minimum length 1

descriptionrequiredstring

minimum length 1

fulfillmentCancellationReferenceoptionalstring

minimum length 1

Typed responses

200

Original reversal replayed.

RedemptionReverseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

201

Compensating reversal committed with evidence.

RedemptionReverseOutcome

requestIdrequiredstring
idempotentoptionalboolean
redemptionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/cancelCancel using the safe operation for current state

Derives release for a reservation or reversal for a committed redemption. A derived reversal additionally requires redemptions:reverse; fulfilled value may require an explicit dispute instead.

Scope redemptions:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

JSON body · `object`

reasonCodeoptionalstring

descriptionoptionalstring

fulfillmentCancellationReferenceoptionalstring

Typed responses

200

Original derived command replayed.

RedemptionCancelOutcome

201

Safe state-dependent cancellation completed.

RedemptionCancelOutcome

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/disputesOpen a redemption dispute with evidence

Opens a governed redemption dispute using a credential bound to a stable approval principal. Legacy credentials without a stable principal binding are rejected until rotated.

Scope disputes:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

JSON body · `object`

reasonCoderequiredstring

minimum length 1

descriptionrequiredstring

minimum length 1 · maximum length 2000

evidencerequiredobject

Inline JSON evidence metadata retained with the dispute. External files must be stored by the merchant and referenced from this object.

Typed responses

200

Original dispute replayed.

RedemptionDisputeOutcome

requestIdrequiredstring
idempotentoptionalboolean
disputerequiredobject

201

Open dispute recorded and linked to the redemption.

RedemptionDisputeOutcome

requestIdrequiredstring
idempotentoptionalboolean
disputerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemption-disputes/{disputeId}/resolveResolve an open redemption dispute

Resolves or rejects an open redemption dispute using maker-checker separation. The resolver credential must be bound to a stable approval principal different from the principal that opened the dispute; legacy unbound disputes and credentials fail closed.

Scope disputes:resolveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

disputeIdpathrequiredstring

JSON body · `object`

decisionrequiredresolved | rejected

resolutionrequiredstring

minimum length 1 · maximum length 2000

Typed responses

200

Original resolution replayed or dispute resolved.

RedemptionDisputeResolutionOutcome

requestIdrequiredstring
idempotentoptionalboolean
disputerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/redemptions/{redemptionId}/fulfillment-eventsRecord an idempotent fulfillment connector event

Advances the attached fulfillment through allowed states without changing the redemption's financial state. A fulfilled event requires fulfillmentReference, a failed event requires lastError, and moving an existing fulfilled reward to cancelled requires fulfillmentCancellationReference as durable connector cancellation evidence.

Scope fulfillments:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

redemptionIdpathrequiredstring

JSON body · `object`

staterequiredpending | fulfilled | failed | cancelled

fulfillmentReferenceoptionalstring

minimum length 1 · maximum length 500

fulfillmentCancellationReferenceoptionalstring

Durable merchant or connector cancellation evidence. Required when the stored fulfillment is fulfilled and the requested state is cancelled.

lastErroroptionalstring

minimum length 1 · maximum length 2000

Typed responses

200

Original connector event replayed or fulfillment updated.

RedemptionFulfillmentOutcome

requestIdrequiredstring
idempotentoptionalboolean
fulfillmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

6 operations

Adjustments

Evidence-backed, independently approved manual ledger corrections

POST/api/v1/adjustmentsRequest a governed ledger adjustment

Records an evidence-backed credit or debit in pending_approval. The requester’s immutable stable principal is barred from deciding it, including through another credential bound to the same human or service. Legacy credentials without a stable principal fail closed for governed requests.

Scope adjustments:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

programIdrequiredstring

minimum length 1

externalCustomerIdrequiredstring

minimum length 1

directionrequiredcredit | debit

pointsrequiredinteger

minimum 1

reasonCoderequiredstring

minimum length 1

descriptionrequiredstring

minimum length 1

evidencerequiredobject

Typed responses

200

Original request replayed.

AdjustmentRequestOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

202

Adjustment recorded pending independent approval.

AdjustmentRequestOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/adjustmentsList and filter governed adjustments

List and filter governed adjustments. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires adjustments:read.

Scope adjustments:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

externalCustomerIdqueryoptionalstring

statequeryoptionalstring

Typed responses

200

Request completed.

AdjustmentListOutcome

requestIdrequiredstring
adjustmentsrequiredarray<AdjustmentListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/adjustments/{adjustmentId}Get adjustment evidence and posting state

Scope adjustments:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

adjustmentIdpathrequiredstring

Typed responses

200

Adjustment, evidence, approval, and transaction links returned with no-store.

AdjustmentDetailOutcome

requestIdrequiredstring
adjustmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/adjustments/{adjustmentId}/approveIndependently approve and post an adjustment

The approver must have a different immutable stable principal from the requester; another credential bound to the same human or service principal cannot self-approve. Legacy credentials without a stable principal fail closed for governed approvals. Posting preserves balanced ledger and point-lot provenance.

Scope adjustments:approveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

adjustmentIdpathrequiredstring

JSON body · `object`

approvalReferencerequiredstring

minimum length 1

decisionNoterequiredstring

minimum length 1

Typed responses

200

Original decision replayed.

AdjustmentPostOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

201

Adjustment posted to the balanced ledger.

AdjustmentPostOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/adjustments/{adjustmentId}/rejectIndependently reject an adjustment

Scope adjustments:approveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

adjustmentIdpathrequiredstring

JSON body · `object`

approvalReferencerequiredstring

minimum length 1

decisionNoterequiredstring

minimum length 1

Typed responses

200

Adjustment rejected or original rejection replayed.

AdjustmentRejectOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/adjustments/{adjustmentId}/reversePost a compensating reversal for an adjustment

Scope adjustments:approveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

adjustmentIdpathrequiredstring

JSON body · `object`

approvalReferencerequiredstring

minimum length 1

decisionNoterequiredstring

minimum length 1

Typed responses

200

Original reversal replayed.

AdjustmentPostOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

201

Linked compensating transaction posted.

AdjustmentPostOutcome

requestIdrequiredstring
idempotentoptionalboolean
adjustmentrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

8 operations

Programs

Validated, immutable program manifests with optimistic concurrency and controlled publishing

POST/api/v1/program-configurations/validateValidate and normalize a program manifest

Returns a checksum, normalized manifest, impact counts, and policy warnings without creating or changing a program.

Scope programs:write

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `ProgramManifestInput`

schemaVersionrequiredconstant: loyumi.program/v1

programrequiredobject

rulesrequiredarray<object>

minimum 1 item

tiersoptionalarray<object>

At most 16 active tier definitions are supported in one program version.

rewardsoptionalarray<object>

default

campaignsoptionalarray<object>

default

Typed responses

200

Manifest is valid and normalized.

ProgramValidationOutcome

requestIdrequiredstring
validrequiredconstant: true
checksumrequiredstring
summaryrequiredProgramConfigurationSummary
normalizedrequiredProgramManifest
warningsrequiredarray<string>

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/programsList programs and latest managed revisions

Scope programs:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

Typed responses

200

Environment programs and their newest immutable configuration revision returned.

ProgramListOutcome

requestIdrequiredstring
programsrequiredarray<object>

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/programsCreate a draft program from a validated manifest

Creates version 1 as an immutable draft. It does not publish or activate the program.

Scope programs:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `ProgramManifestInput`

schemaVersionrequiredconstant: loyumi.program/v1

programrequiredobject

rulesrequiredarray<object>

minimum 1 item

tiersoptionalarray<object>

At most 16 active tier definitions are supported in one program version.

rewardsoptionalarray<object>

default

campaignsoptionalarray<object>

default

Typed responses

200

Original create response replayed.

ProgramCreateOutcome

requestIdrequiredstring
idempotentoptionalboolean
programrequiredobject
revisionrequiredobject

201

Draft program and immutable version 1 created.

ProgramCreateOutcome

requestIdrequiredstring
idempotentoptionalboolean
programrequiredobject
revisionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/programs/{programId}/configurationGet the current or a specific immutable program manifest

Scope programs:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

programIdpathrequiredstring

versionqueryoptionalinteger

minimum 1

Typed responses

200

Immutable manifest and checksum returned. The ETag header is required for the next revision mutation.

ProgramConfigurationOutcome

requestIdrequiredstring
programrequiredobject
revisionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/programs/{programId}/revisionsList immutable program revision history

Scope programs:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

programIdpathrequiredstring

Typed responses

200

Revision versions, status, checksum, provenance, and timestamps returned.

ProgramRevisionListOutcome

requestIdrequiredstring
revisionsrequiredarray<object>

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/programs/{programId}/revisionsCreate the next immutable draft revision

Requires the latest ETag in If-Match. Returns 428 when absent and 412 when stale.

Scope programs:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

If-Matchheaderrequiredstring

minimum length 1

programIdpathrequiredstring

JSON body · `ProgramManifestInput`

schemaVersionrequiredconstant: loyumi.program/v1

programrequiredobject

rulesrequiredarray<object>

minimum 1 item

tiersoptionalarray<object>

At most 16 active tier definitions are supported in one program version.

rewardsoptionalarray<object>

default

campaignsoptionalarray<object>

default

Typed responses

200

Original revision response replayed.

ProgramRevisionCreateOutcome

requestIdrequiredstring
idempotentoptionalboolean
revisionrequiredobject

201

Next immutable draft created with a new ETag.

ProgramRevisionCreateOutcome

requestIdrequiredstring
idempotentoptionalboolean
revisionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

412

If-Match does not equal the latest immutable configuration ETag.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

428

If-Match is required for this configuration mutation.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/programs/{programId}/revisions/{version}/publishPublish one exact draft revision

Requires the draft's exact ETag, expands its keyed objects into runtime records, archives the prior published version, and advances currentVersion behind a same-transaction monotonic fence. A draft at or behind the current published version is rejected; historical rollback must use restore to create a new draft.

Scope programs:publishIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

If-Matchheaderrequiredstring

minimum length 1

programIdpathrequiredstring

versionpathrequiredinteger

minimum 1

JSON body · `object`

approvalReferenceoptionalstring

minimum length 1

Typed responses

200

Original publish response replayed.

ProgramPublishOutcome

requestIdrequiredstring
idempotentoptionalboolean
programrequiredobject
revisionrequiredobject

201

Exact revision published atomically.

ProgramPublishOutcome

requestIdrequiredstring
idempotentoptionalboolean
programrequiredobject
revisionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

412

If-Match does not equal the latest immutable configuration ETag.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

428

If-Match is required for this configuration mutation.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/programs/{programId}/revisions/{version}/restoreCopy an old manifest into a new draft revision

Restore never mutates history or silently publishes. It copies the selected source version into the next immutable draft and requires the latest ETag.

Scope programs:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

If-Matchheaderrequiredstring

minimum length 1

programIdpathrequiredstring

versionpathrequiredinteger

minimum 1

JSON body · `object`

reasonrequiredstring

minimum length 1

Typed responses

200

Original restore response replayed.

ProgramRestoreOutcome

requestIdrequiredstring
idempotentoptionalboolean
revisionrequiredobject

201

Historical manifest copied into a new draft with a new ETag.

ProgramRestoreOutcome

requestIdrequiredstring
idempotentoptionalboolean
revisionrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

412

If-Match does not equal the latest immutable configuration ETag.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

428

If-Match is required for this configuration mutation.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

30 operations

Gifts

Durable, personalized, recipient-bound catalog-entitlement gifts with readiness/onboarding, one-to-four reward choice, independently verified decisions, purpose-bound delivery evidence, first-party wallets, single-use entitlement evidence, exact restoration, and governed recovery. Reward Gifts never create cash, a transferable balance, or a points-transfer rail.

POST/api/v1/reward-gift-quotesQuote one recipient-bound catalog reward gift

Resolves two active enrolled members, enforces program gift policy, inventory, velocity, open-gift, balance, and point-lot-expiry limits, then returns an immutable exact disclosure. It moves no value and requires gifts:write plus Idempotency-Key on an isolated value credential. If the sender's eligible balance exceeds the bounded reversible source-lot batch, the operation fails before reservation with 409 reward_gift_source_lot_limit_exceeded; compact the point lots and exact-replay the same business operation.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

Typed responses

200

Exact quote replayed idempotently.

RewardGiftQuoteOutcome

requestIdrequiredstring
rewardGiftQuoterequiredRewardGiftQuote
idempotentoptionalconstant: true

201

Exact gift quote created without reserving value.

RewardGiftQuoteOutcome

requestIdrequiredstring
rewardGiftQuoterequiredRewardGiftQuote
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-giftsReserve an independently approved reward gift

Atomically revalidates the exact sender approval, immutable disclosure, participants, gift policy, original point lots, and reward inventory before reserving value. The private raw claim token is returned only on create or exact idempotent replay and must remain on the merchant server. If the sender's eligible balance exceeds the bounded reversible source-lot batch, the operation fails before reservation with 409 reward_gift_source_lot_limit_exceeded; compact the point lots and exact-replay the same business operation.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `RewardGiftCreateRequest`

quoteIdrequiredstring

minimum length 1 · maximum length 200

approvalIdrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Exact reservation replayed with the same private claim capability.

RewardGiftCreateOutcome

201

Gift value and inventory reserved.

RewardGiftCreateOutcome

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reward-giftsList durable reward gifts for reconciliation

Returns tenant-scoped, deterministic cursor pages without claim tokens, browser handoffs, provider fulfillment references, member IDs, or other authority material.

Scope gifts:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

minimum length 1 · maximum length 200

senderExternalCustomerIdqueryoptionalstring

minimum length 1 · maximum length 320

recipientExternalCustomerIdqueryoptionalstring

minimum length 1 · maximum length 320

fromqueryoptionalstring · date-time

toqueryoptionalstring · date-time

Typed responses

200

Reward gifts returned.

RewardGiftListOutcome

requestIdrequiredstring
rewardGiftsrequiredarray<RewardGiftListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reward-gifts/{giftId}Read the authoritative merchant reward-gift receipt

Returns the environment-scoped sender/merchant projection with exact terminal and restoration evidence. It never returns the raw claim token, participant member IDs, provider identity, or browser-session authority.

Scope gifts:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Authoritative gift receipt returned with no-store.

RewardGiftOutcome

requestIdrequiredstring
rewardGiftrequiredvalue
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-claim-handoffsConvert a server-held claim token into a one-use browser handoff

Converts a server-held claim capability into a 60-second one-use browser handoff. Requires Idempotency-Key: an exact replay while the code is still live returns the same code with idempotent:true; replay after consumption or expiry is rejected. A new key may issue a new generation only after no live handoff remains. Never place the raw claim token or recipient contact data in the key, browser, URL, analytics, or logs.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `RewardGiftClaimHandoffRequest`

giftIdrequiredstring

minimum length 1 · maximum length 200

claimTokenrequiredstring

Typed responses

200

Exact replay returned the same still-live one-use handoff.

RewardGiftClaimHandoffReplayOutcome

requestIdrequiredstring
claimHandoffrequiredobject
idempotentrequiredconstant: true

201

A new one-use recipient handoff generation was issued.

RewardGiftClaimHandoffOutcome

requestIdrequiredstring
claimHandoffrequiredobject
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-claim-handoffs/exchangeExchange a one-use recipient handoff for a closure-only gift session

Trusted Loyumi frame only. At the authoritative same origin, the independently member-bound Widget session consumes the handoff once and receives a 10-minute gift session for closure-memory use. The session is no-store and the embedded flow has no third-party-cookie dependency.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `RewardGiftClaimHandoffExchangeRequest`

giftIdrequiredstring

handoffCoderequiredstring

Typed responses

201

Gift-scoped recipient claim session created.

RewardGiftClaimSessionOutcome

requestIdrequiredstring
claimSessionrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-approvalsStart or recover exact sender gift approval

Starts or recovers a quote-bound sender approval intent from the live Loyumi-hosted frame. Intent issuance never approves the quote; the cooled linked sender must complete a fresh top-level provider authorization and explicit exact-term click.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `RewardGiftApprovalIntentRequest`

quoteIdrequiredstring

minimum length 1 · maximum length 200

disclosureFingerprintrequiredstring

confirmationNoncerequiredstring

Typed responses

200

Existing exact approval intent recovered.

RewardGiftApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredRewardGiftApprovalIntent
idempotentoptionalconstant: true

201

Quote-bound sender approval intent created.

RewardGiftApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredRewardGiftApprovalIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-approvals/{intentId}Poll authoritative sender approval status

Returns only the current quote-bound approval status for the verified linked sender.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Approval status returned.

RewardGiftApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredRewardGiftApprovalIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-approvals/{intentId}/step-upStart fresh provider authorization for sender approval

Top-level Loyumi-origin transport operation. It records a one-use intent-bound provider ceremony marker and returns the provider callback; it does not approve or reserve the gift.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Provider authorization callback created with no-store.

RewardGiftProviderStepUpOutcome

requestIdrequiredstring
stepUprequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-approvals/{intentId}/approveExplicitly approve the exact gift quote after provider step-up

Requires the exact cooled linked provider user/account, a fresh intent-bound authorization marker, a current Loyumi customer session, and an explicit CSRF-bound click. Approval does not move value.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftExplicitActionRequest`

csrfrequiredstring

minimum length 1 · maximum length 512

Typed responses

200

Exact prior approval returned.

RewardGiftApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredRewardGiftApprovalIntent
idempotentoptionalconstant: true

201

Exact immutable gift quote approved.

RewardGiftApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredRewardGiftApprovalIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-claims/{giftId}Read the intended recipient gift projection

Requires both the intended recipient Widget session and the closure-only gift session header. Returns the immutable participant-safe receipt and current accept/decline capabilities; the claim capability itself is never returned.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Private recipient gift projection returned.

RewardGiftClaimOutcome

requestIdrequiredstring
rewardGiftrequiredRewardGiftParticipantReceipt
capabilitiesrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-claims/{giftId}/acceptStart acceptance for the exact recipient gift

Starts or recovers a accept intent bound to the verified recipient, closure-only gift session header, and immutable disclosure. It does not itself accept or move value; a fresh provider ceremony and explicit click are still required.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftAcceptanceRequest`

disclosureFingerprintrequiredstring

selectedRewardIdoptionalstring

minimum length 1 · maximum length 200

Typed responses

200

Existing exact decision intent recovered.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

201

Recipient decision intent created.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-claims/{giftId}/declineStart decline for the exact recipient gift

Starts or recovers a decline intent bound to the verified recipient, closure-only gift session header, and immutable disclosure. It does not itself decline or move value; a fresh provider ceremony and explicit click are still required.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftDecisionRequest`

disclosureFingerprintrequiredstring

Typed responses

200

Existing exact decision intent recovered.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

201

Recipient decision intent created.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gifts/{giftId}/cancelStart sender cancellation for a pending gift

Starts or recovers cancellation bound to the verified sender and immutable pending gift. It does not itself cancel or release value; a fresh provider ceremony and explicit click are still required.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftDecisionRequest`

disclosureFingerprintrequiredstring

Typed responses

200

Existing exact cancellation intent recovered.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

201

Sender cancellation intent created.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-actions/{intentId}Poll authoritative accept, decline, or cancel status

Returns only the intent belonging to the verified linked actor. Recipient intents additionally require X-Loyumi-Gift-Session from the trusted frame closure; sender cancellation never sends or accepts recipient claim authority.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Gift action status returned.

RewardGiftActionIntentOutcome

requestIdrequiredstring
giftActionIntentrequiredRewardGiftActionIntent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-actions/{intentId}/step-upStart fresh provider authorization for a gift decision

Top-level Loyumi-origin transport operation. It records a one-use action-intent provider ceremony marker and returns the provider callback; it does not change gift value.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Provider authorization callback created with no-store.

RewardGiftProviderStepUpOutcome

requestIdrequiredstring
stepUprequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-actions/{intentId}/completeExplicitly complete verified acceptance, decline, or cancellation

Requires the exact cooled linked provider user/account, a fresh intent-bound authorization marker, a current Loyumi customer session, and explicit CSRF-bound click. The mutation is atomic: acceptance commits sender value and creates recipient fulfillment; decline or cancellation releases inventory and restores only eligible original lots.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftExplicitActionRequest`

csrfrequiredstring

minimum length 1 · maximum length 512

Typed responses

200

Exact prior terminal decision returned.

RewardGiftActionOutcome

requestIdrequiredstring
rewardGiftrequiredRewardGiftParticipantReceipt
restorationoptionalobject
idempotentoptionalconstant: true

201

Verified terminal gift decision committed.

RewardGiftActionOutcome

requestIdrequiredstring
rewardGiftrequiredRewardGiftParticipantReceipt
restorationoptionalobject
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/reward-gifts/{giftId}/recoverGoverned post-acceptance gift reversal

Atomically reverses one fulfilled recipient entitlement only after exact cancellation evidence and a matching resolved dispute. Its isolated gifts:reverse principal must differ from both dispute principals. This is not sender cancellation, retry, or claim recovery.

Scope gifts:reverseIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftRecoveryRequest`

disputeIdrequiredstring

minimum length 1 · maximum length 200

reasonCoderequiredfraud | fulfillment_failure | recipient_ineligible | merchant_cancellation | legal_requirement

descriptionrequiredstring

minimum length 1 · maximum length 2000

fulfillmentCancellationReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact governed reversal replayed idempotently.

RewardGiftRecoveryOutcome

requestIdrequiredstring
rewardGiftrequiredRewardGiftParticipantReceipt
idempotentoptionalconstant: true

201

Governed gift reversal committed.

RewardGiftRecoveryOutcome

requestIdrequiredstring
rewardGiftrequiredRewardGiftParticipantReceipt
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gifts/{giftId}/fulfillment-eventsRecord reward-entitlement cancellation evidence

Records an exact cancellation reference on an already fulfilled recipient-bound entitlement. The fulfillment and gift remain fulfilled; this evidence-only operation cannot restore points. Governed reversal separately requires an independently opened and resolved dispute plus an isolated gifts:reverse principal. Requires fulfillments:write.

Scope fulfillments:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftFulfillmentCancellationRequest`

staterequiredconstant: cancelled

fulfillmentCancellationReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Cancellation evidence recorded or exactly replayed.

RewardGiftFulfillmentCancellationOutcome

requestIdrequiredstring
fulfillmentrequiredRewardGiftFulfillmentCancellation
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gifts/{giftId}/disputesOpen an independently governed reward-gift dispute

Opens a governed recovery case only after an accepted entitlement has exact cancellation evidence. The opener is bound to a stable principal; opening the case does not restore points. Requires disputes:write and an idempotency key.

Scope disputes:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftDisputeRequest`

reasonCoderequiredfraud | fulfillment_failure | recipient_ineligible | merchant_cancellation | legal_requirement

descriptionrequiredstring

minimum length 1 · maximum length 2000

evidencerequiredRewardGiftDisputeEvidence

Typed responses

200

Exact dispute replayed idempotently.

RewardGiftDisputeOutcome

requestIdrequiredstring
disputerequiredRewardGiftDispute
idempotentoptionalconstant: true

201

Reward-gift dispute opened.

RewardGiftDisputeOutcome

requestIdrequiredstring
disputerequiredRewardGiftDispute
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-disputes/{disputeId}/resolveResolve or reject an open reward-gift dispute

Resolves or rejects an open reward-gift dispute. A different stable principal from the opener is mandatory. Resolution does not restore points. Requires disputes:resolve and an idempotency key.

Scope disputes:resolveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

disputeIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftDisputeResolutionRequest`

decisionrequiredresolved | rejected

resolutionrequiredstring

minimum length 1 · maximum length 2000

Typed responses

200

Dispute resolved, rejected, or exactly replayed.

RewardGiftDisputeOutcome

requestIdrequiredstring
disputerequiredRewardGiftDispute
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-invitationsCreate a durable personalized reward-gift invitation

Creates a pre-value, privacy-safe invitation for one to four catalog-entitlement choices. It may return onboarding readiness, but never promises reward availability or sender cost before reservation. Contact destinations remain opaque merchant vault references.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `RewardGiftInvitationCreateRequest`

programIdrequiredstring

minimum length 1 · maximum length 200

senderExternalCustomerIdrequiredstring

minimum length 1 · maximum length 320

recipientExternalCustomerIdrequiredstring

minimum length 1 · maximum length 320

rewardIdsrequiredarray<string>

minimum 1 item · maximum 4 items

sourceReferenceoptionalstring

minimum length 1 · maximum length 200

personalizationrequiredRewardGiftInvitationPersonalizationInput

deliveryrequiredobject

Typed responses

200

Exact invitation replayed.

RewardGiftInvitationOutcome

requestIdrequiredstring
rewardGiftInvitationrequiredRewardGiftInvitation
eligibilityNoticerequiredvalue
idempotentoptionalconstant: true

202

Invitation durably accepted for readiness or sender approval.

RewardGiftInvitationOutcome

requestIdrequiredstring
rewardGiftInvitationrequiredRewardGiftInvitation
eligibilityNoticerequiredvalue
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-invitationsList durable reward-gift invitations

Returns cursor-paged invitation, readiness, option, and delivery evidence without member IDs, contact addresses, claim capabilities, provider secrets, or customer-session authority.

Scope gifts:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

minimum length 1 · maximum length 200

Typed responses

200

Invitations returned.

RewardGiftInvitationListOutcome

requestIdrequiredstring
rewardGiftInvitationsrequiredarray<RewardGiftInvitation>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-invitations/{invitationId}Read one authoritative reward-gift invitation

Returns the current invitation, readiness, choices, and delivery evidence. The response is no-store and contains only opaque destination/provider references.

Scope gifts:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

invitationIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Invitation returned.

RewardGiftInvitationOutcome

requestIdrequiredstring
rewardGiftInvitationrequiredRewardGiftInvitation
eligibilityNoticerequiredvalue
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-invitations/{invitationId}/readinessRefresh recipient readiness for an invitation

Re-evaluates enrollment, provider verification, identity cooling, and option compatibility without reserving value or promising an outcome.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

invitationIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftInvitationReadinessRequest`

recipientExternalCustomerIdrequiredstring

minimum length 1 · maximum length 320

Typed responses

200

Readiness returned or exactly replayed.

RewardGiftInvitationReadinessOutcome

requestIdrequiredstring
invitationIdrequiredstring
staterequiredonboarding | ready | quoted | reserved | accepted | declined | cancelled | expired | reversed | revoked
readinessrequiredRewardGiftInvitationReadiness
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-invitations/{invitationId}/deliveriesSchedule a purpose-bound invitation delivery

Schedules onboarding or reserved-gift notification evidence. Requires the isolated gifts:delivery authority; a provider worker must re-read authoritative invitation and gift state immediately before sending. The 60-second claim handoff is never notification content.

Scope gifts:deliveryIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

invitationIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftInvitationDeliveryRequest`

phaserequiredonboarding_notice | gift_ready

kindrequiredinitial | reminder | resend

scheduledForoptionalstring · date-time

Typed responses

200

Exact delivery schedule replayed.

RewardGiftInvitationDeliveryOutcome

requestIdrequiredstring
deliveryrequiredRewardGiftInvitationScheduledDelivery
contentBoundaryrequiredRewardGiftInvitationDeliveryContentBoundary
idempotentoptionalconstant: true

201

Delivery attempt scheduled.

RewardGiftInvitationDeliveryOutcome

requestIdrequiredstring
deliveryrequiredRewardGiftInvitationScheduledDelivery
contentBoundaryrequiredRewardGiftInvitationDeliveryContentBoundary
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-invitations/{invitationId}/arrivalsCreate a just-in-time recipient arrival handoff

After the intended recipient authenticates through a delivered gift-ready attempt, issues one 60-second one-use handoff for the trusted Loyumi frame. The handoff is never the durable invitation and must not enter notification content, URLs, logs, analytics, or storage.

Scope gifts:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

invitationIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftInvitationArrivalRequest`

recipientExternalCustomerIdrequiredstring

minimum length 1 · maximum length 320

deliveryIdrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Exact still-live arrival generation replayed.

RewardGiftInvitationArrivalOutcome

requestIdrequiredstring
invitationIdrequiredstring
giftIdrequiredstring
claimHandoffrequiredobject
idempotentoptionalconstant: true

201

Just-in-time arrival handoff created.

RewardGiftInvitationArrivalOutcome

requestIdrequiredstring
invitationIdrequiredstring
giftIdrequiredstring
claimHandoffrequiredobject
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gift-invitation-deliveries/{deliveryId}/eventsRecord provider delivery outcome evidence

Attests sent, delivered, or failed state using only opaque provider evidence under the isolated gifts:delivery authority. Database-time due and live-gift fences prevent stale gift-ready sends; terminal invitation or gift state cancels scheduled attempts.

Scope gifts:deliveryIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

deliveryIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftInvitationDeliveryEventRequest`

staterequiredsent | delivered | failed

providerReferenceoptionalstring

minimum length 1 · maximum length 500

failureCodeoptionalstring

Typed responses

200

Delivery outcome recorded or exactly replayed.

RewardGiftInvitationDeliveryEventOutcome

requestIdrequiredstring
deliveryrequiredRewardGiftInvitationDeliveryEvent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reward-gift-walletRead a participant's first-party sent or received gift wallet

Loyumi-hosted popup only. Requires a live member-bound Widget session, a fresh matching provider identity, Sec-Fetch-Site: same-origin, and an exact Loyumi Origin when supplied. No wallet item, one-use Widget code, or customer session crosses to merchant JavaScript or postMessage.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

viewqueryrequiredsent | received

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

Typed responses

200

First-party wallet page returned with no-store.

RewardGiftWalletOutcome

requestIdrequiredstring
viewrequiredsent | received
itemsrequiredarray<value>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/reward-gifts/{giftId}/use-eventsRecord the single recipient-bound entitlement use

Records one real-world use under the isolated fulfillment authority. The event time must fall between issuance and expiry and no more than five minutes in the server future. It cannot spend points, transfer value, reload the entitlement, or consume it twice.

Scope fulfillments:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

giftIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `RewardGiftEntitlementUseRequest`

sourceReferencerequiredstring

minimum length 1 · maximum length 500

occurredAtrequiredstring · date-time

Typed responses

200

Exact entitlement-use replay returned.

RewardGiftEntitlementUseOutcome

requestIdrequiredstring
rewardGiftEntitlementrequiredRewardGiftEntitlement
useEventrequiredRewardGiftEntitlementUseEvent
idempotentoptionalconstant: true

201

Entitlement use recorded.

RewardGiftEntitlementUseOutcome

requestIdrequiredstring
rewardGiftEntitlementrequiredRewardGiftEntitlement
useEventrequiredRewardGiftEntitlementUseEvent
idempotentoptionalconstant: true

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

31 operations

Partners

Bilateral exchange agreements, private member links, conversion quotes, exchanges, and settlement evidence

POST/api/v1/partner-agreementsPropose versioned bilateral exchange terms

Creates source-approved terms in proposed state between two different merchants. Before storing any economics, partnerName must confirm the destination's registered merchant name. The immutable terms pin the destination point-expiration policy; no exchange is possible until the destination independently accepts the exact termsHash.

Scope partners:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

sourceProgramIdrequiredstring

minimum length 1

destinationOrganizationIdrequiredstring

minimum length 1

destinationEnvironmentIdrequiredstring

minimum length 1

destinationProgramIdrequiredstring

minimum length 1

partnerNamerequiredstring

Must match the destination organization's registered name, ignoring case. The canonical registered name is persisted.

sourceApprovalReferencerequiredstring

minimum length 1

sourceRaterequiredinteger

minimum 1

destinationRaterequiredinteger

minimum 1

settlementMinorPerBlockrequiredinteger

minimum 1

settlementCurrencyoptionalstring

default USD

monthlySettlementCapMinorrequiredinteger

minimum 1

minimumSourcePointsoptionalinteger

Defaults to sourceRate. Must be at least sourceRate and an exact multiple of sourceRate.

maximumSourcePointsoptionalinteger

Zero means unlimited; otherwise it must be an exact sourceRate multiple at least minimumSourcePoints.

endsAtoptionalstring · date-time

maximum length 64

destinationExpirationRuleIdoptionalstring

Current published destination rule to pin when destination rules have different expiration periods. May be omitted only when every current destination rule has one uniform expiration period.

Typed responses

200

Original proposal replayed.

PartnerAgreementProposalOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

201

Version 1 proposed with immutable termsHash.

PartnerAgreementProposalOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/partner-agreementsList bilateral agreement corridors and current cap usage

Returns only agreements where the credential's current environment is the source or destination participant. Each item includes the exact hash-matched canonical version document and current UTC-month settlement-cap exposure, without credential secrets or member identity. Results are cursor-paged and ordered by creation time then ID descending. Requires partners:read.

Scope partners:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

rolequeryoptionalsource | destination

programIdqueryoptionalstring

minimum length 1 · maximum length 200

Typed responses

200

Participant-scoped agreement corridors and current usage returned.

PartnerAgreementListOutcome

requestIdrequiredstring
agreementsrequiredarray<PartnerAgreementListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/acceptAccept the exact bilateral agreement terms

Callable only by the destination tenant named in the proposal. Activates only when termsHash matches exactly.

Scope partners:approveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

JSON body · `object`

termsHashrequiredstring

minimum length 1

acceptanceReferencerequiredstring

minimum length 1

Typed responses

200

Exact terms accepted or original acceptance replayed.

PartnerAgreementAcceptanceOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-member-tokensCreate an opaque one-time destination member link

The destination participant consumes a one-time source member-link challenge and supplies its own consent evidence while exchanging its external customer ID for a five-minute opaque token. The resulting token is cryptographically random and server-bound to both merchant member records without disclosing either identifier across the corridor.

Scope exchanges:member-link

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

agreementIdrequiredstring

minimum length 1

externalCustomerIdrequiredstring

minimum length 1

sourceLinkChallengerequiredstring

minimum length 1 · maximum length 256

consentReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

201

Single-use 5-minute member token returned once with no-store.

PartnerMemberTokenOutcome

requestIdrequiredstring
memberTokenrequiredstring
agreementIdrequiredstring
expiresAtrequiredstring · date-time
expiresInrequiredconstant: 300
noticerequiredstring

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-quotesQuote conversion and clearing economics

Consumes the consent-bound opaque destination member token, requires sourcePoints to be an exact multiple of the agreement's sourceRate, verifies the current destination expiration policy still matches the accepted canonical policy, pins the exact current rule for commit, checks source balance and point-lot lifetime, and returns a quote without moving value. Quote expiry is the earliest of five minutes, agreement end, source Production readiness expiry, and destination Production readiness expiry.

Scope exchanges:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

agreementIdrequiredstring

minimum length 1

sourceExternalCustomerIdrequiredstring

minimum length 1

destinationMemberTokenrequiredstring

minimum length 1

sourceReferencerequiredstring

minimum length 1

sourcePointsrequiredinteger

Must be a positive exact multiple of the selected agreement's sourceRate; this prevents silent fractional destination-point loss.

Typed responses

200

Original quote replayed.

PartnerExchangeQuoteOutcome

requestIdrequiredstring
idempotentoptionalboolean
quoterequiredobject

201

Pinned conversion and settlement quote created without moving value.

PartnerExchangeQuoteOutcome

requestIdrequiredstring
idempotentoptionalboolean
quoterequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchangesReserve source points and agreement capacity

Reserves source points only after the source value-authority service supplies the exact one-use assertion issued for an approved prelinked-provider intent. No single merchant credential may combine Widget-session authority and value authority. The assertion is atomically consumed and binds the exact quote, both member records, Widget deployment/session, approved intent, fingerprint, nonce, and expiry.

Scope exchanges:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

quoteIdrequiredstring

minimum length 1

confirmationAssertionrequiredstring

Typed responses

200

Original reservation replayed.

PartnerExchangeReservationOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

201

Source points and monthly settlement capacity reserved atomically.

PartnerExchangeReservationOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/partner-exchangesList participant-scoped exchanges for recovery and reconciliation

Returns only exchanges where the credential's environment is a source or destination participant. The cursor-paged projection omits member, reservation, lot, and ledger identifiers. Source references are visible and filterable only to the source participant. Partial returns expose exact returnedSourcePoints and expiredSourcePoints evidence. Requires exchanges:read.

Scope exchanges:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

rolequeryoptionalsource | destination

agreementIdqueryoptionalstring

minimum length 1 · maximum length 200

programIdqueryoptionalstring

minimum length 1 · maximum length 200

sourceReferencequeryoptionalstring

minimum length 1 · maximum length 200

Typed responses

200

Participant-scoped exchange page returned.

PartnerExchangeListOutcome

requestIdrequiredstring
exchangesrequiredarray<PartnerExchangeListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/partner-exchanges/{exchangeId}Get bilateral exchange and reconciliation state

Returns a participant-safe exchange projection to either bilateral participant. sourceReference and confirmationReference are returned only to the source participant and are null for the destination participant; the non-secret quote fingerprint and confirmation time provide shared evidence. Requires exchanges:read.

Scope exchanges:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

exchangeIdpathrequiredstring

Typed responses

200

Exchange state and participant-safe reconciliation evidence returned with no-store.

PartnerExchangeDetailOutcome

requestIdrequiredstring
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchanges/{exchangeId}/commitCommit both sides of a reserved exchange

Posts separate balanced source debit and destination credit transactions, creates the destination point lot, and converts reserved monthly cap usage into committed usage.

Scope exchanges:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

exchangeIdpathrequiredstring

Typed responses

200

Exchange committed or original commit replayed.

PartnerExchangeCommitOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchanges/{exchangeId}/releaseRelease a reserved exchange

Returns still-valid source point lots, records expired portions, and releases reserved monthly settlement capacity. This corrective restoration remains available while Production is locked or readiness evidence is expired.

Scope exchanges:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

exchangeIdpathrequiredstring

JSON body · `object`

reasonCodeoptionalstring

default merchant_release

Typed responses

200

Exchange released or original release replayed.

PartnerExchangeReleaseOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchanges/{exchangeId}/settleRecord external clearing settlement evidence

Records the external settlement reference and reconciles settled usage to the committed agreement amount; it does not initiate a bank payment.

Scope settlements:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

exchangeIdpathrequiredstring

JSON body · `object`

settlementReferencerequiredstring

minimum length 1

Typed responses

200

Settlement evidence recorded or original settlement replayed.

PartnerExchangeSettlementOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchanges/{exchangeId}/reverseReverse both program transactions and cap usage

Posts linked compensating source and destination transactions. A settled exchange additionally requires settlementReversalReference. This corrective restoration remains available while Production is locked or readiness evidence is expired. Expired source lots are replaced with an expiration window at least as long as their original lifetime and never shorter than 30 days; the exact recovery policy is returned and audited.

Scope exchanges:reverseIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

exchangeIdpathrequiredstring

JSON body · `object`

reasonCoderequiredstring

minimum length 1

descriptionrequiredstring

minimum length 1

settlementReversalReferenceoptionalstring

minimum length 1

Typed responses

200

Exchange reversed or original reversal replayed.

PartnerExchangeReverseOutcome

requestIdrequiredstring
idempotentoptionalboolean
exchangerequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-member-link-challengesCreate a consent-bound opaque source member challenge

The source participant creates a one-time five-minute challenge bound server-side to its active member, agreement, and source consent evidence. The customer carries only the opaque challenge to the destination; neither merchant receives the other's member identifier. Requires exchanges:member-link.

Scope exchanges:member-link

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `object`

agreementIdrequiredstring

minimum length 1

sourceExternalCustomerIdrequiredstring

minimum length 1

consentReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

201

One-time source member-link challenge returned once with no-store.

PartnerMemberLinkChallengeOutcome

requestIdrequiredstring
sourceLinkChallengerequiredstring
agreementIdrequiredstring
expiresAtrequiredstring · date-time
expiresInrequiredconstant: 300
noticerequiredstring

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/rejectReject an exact proposed agreement as the destination

Destination-only terminal decision for a proposed agreement. Records rejection evidence for both participants and never changes or deletes the canonical terms. Requires partners:approve and Idempotency-Key.

Scope partners:approveIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `PartnerAgreementRejectRequest`

termsHashrequiredstring

Exact SHA-256 hash of the canonical agreement version being acted on.

reasonCoderequiredstring

minimum length 1 · maximum length 100

descriptionrequiredstring

minimum length 1 · maximum length 2000

rejectionReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact lifecycle transition committed or replayed idempotently.

PartnerAgreementLifecycleOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/withdrawWithdraw an exact proposed agreement as the source

Source-only terminal decision for a proposed agreement. Records withdrawal evidence for both participants and never changes or deletes the canonical terms. Requires partners:write and Idempotency-Key.

Scope partners:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `PartnerAgreementWithdrawRequest`

termsHashrequiredstring

Exact SHA-256 hash of the canonical agreement version being acted on.

reasonCoderequiredstring

minimum length 1 · maximum length 100

descriptionrequiredstring

minimum length 1 · maximum length 2000

withdrawalReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact lifecycle transition committed or replayed idempotently.

PartnerAgreementLifecycleOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/pauseEmergency-pause an active agreement

Either participant may add its own independent emergency hold to an active or already-paused agreement with an incident reference. New quotes, reservations, and commits stop while any hold remains; corrective release and reversal paths remain available. Requires partners:manage and Idempotency-Key.

Scope partners:manageIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `PartnerAgreementPauseRequest`

termsHashrequiredstring

Exact SHA-256 hash of the canonical agreement version being acted on.

reasonCoderequiredstring

minimum length 1 · maximum length 100

descriptionrequiredstring

minimum length 1 · maximum length 2000

incidentReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact lifecycle transition committed or replayed idempotently.

PartnerAgreementLifecycleOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/resumeResume a paused agreement with explicit approval evidence

A participant may release only its own hold on the exact paused canonical version with an explicit approvalReference. The agreement becomes active only after every participant hold is released. Current environment readiness, matching Sandbox/Production kinds, and the agreement term are rechecked. Requires partners:manage and Idempotency-Key.

Scope partners:manageIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `PartnerAgreementResumeRequest`

termsHashrequiredstring

Exact SHA-256 hash of the canonical agreement version being acted on.

reasonCoderequiredstring

minimum length 1 · maximum length 100

descriptionrequiredstring

minimum length 1 · maximum length 2000

approvalReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact lifecycle transition committed or replayed idempotently.

PartnerAgreementLifecycleOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-agreements/{agreementId}/terminatePermanently terminate an agreement

Either participant may permanently terminate a proposed, active, or paused agreement with approval evidence. The versioned terms and audit history remain immutable and discoverable. Requires partners:manage and Idempotency-Key.

Scope partners:manageIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

agreementIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `PartnerAgreementTerminateRequest`

termsHashrequiredstring

Exact SHA-256 hash of the canonical agreement version being acted on.

reasonCoderequiredstring

minimum length 1 · maximum length 100

descriptionrequiredstring

minimum length 1 · maximum length 2000

approvalReferencerequiredstring

minimum length 1 · maximum length 500

Typed responses

200

Exact lifecycle transition committed or replayed idempotently.

PartnerAgreementLifecycleOutcome

requestIdrequiredstring
idempotentoptionalboolean
agreementrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-confirmationsIssue the one-use assertion for an approved exchange intent

Called only by the Loyumi-hosted frame with a live member-bound Widget session. A Widget token or forged Origin is insufficient: the route atomically requires an approved, one-use intent produced by a new provider authorization ceremony for the durable prelinked Google or Apple account and the customer's explicit top-level approval. The quote, member, deployment, fingerprint, nonce, provider account, and expiry are bound server-side. Exact retries replay the encrypted short-lived response; no merchant API credential is accepted.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `PartnerExchangeConfirmationRequest`

quoteIdrequiredstring

minimum length 1

approvalIntentIdrequiredstring

Opaque, quote-bound intent already approved in the top-level Loyumi customer-verification ceremony.

confirmationFingerprintrequiredstring

confirmationNoncerequiredstring

Typed responses

201

One short-lived customer assertion returned with no-store.

PartnerExchangeConfirmationOutcome

requestIdrequiredstring
idempotentrequiredboolean
confirmationAssertionrequiredstring
expiresAtrequiredstring · date-time
expiresInrequiredinteger

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/partner-exchange-receipts/{quoteId}Read a customer-safe authoritative exchange receipt

A Loyumi-hosted frame reads the exact member-bound quote and outcome using a live Widget session. The response contains immutable merchant/program/unit labels, conversion and finality disclosures, exact give/get amounts, partial-return evidence, and status. It never contains API credentials, member IDs, ledger IDs, settlement references, or durable customer-link identifiers. Historical final receipts remain readable after a deployment/program lock, while new approval remains fail-closed.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

quoteIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Customer-safe authoritative receipt returned with no-store.

PartnerExchangeCustomerReceiptOutcome

requestIdrequiredstring
receiptrequiredPartnerExchangeCustomerReceipt

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-approval-intentsStart or recover an exact quote-approval intent

Starts or recovers one quote-wide approval intent for the live member-bound Widget session. The source customer must already have a cooled durable provider link. Creating an intent never approves a quote; approval requires a separate top-level provider authorization ceremony and explicit click.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `PartnerExchangeApprovalIntentRequest`

quoteIdrequiredstring

minimum length 1 · maximum length 200

confirmationFingerprintrequiredstring

confirmationNoncerequiredstring

Typed responses

200

Existing exact intent recovered after an ambiguous response or Widget refresh.

PartnerExchangeApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredPartnerExchangeApprovalIntent

201

Quote-bound approval intent created.

PartnerExchangeApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredPartnerExchangeApprovalIntent

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/partner-exchange-approval-intents/{intentId}Poll authoritative quote-approval status

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Authoritative approval-intent status returned.

PartnerExchangeApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredPartnerExchangeApprovalIntent

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-approval-intents/{intentId}/step-upStart a new provider authorization for an exact quote

Top-level Loyumi-origin transport operation. It records a nonce-bound provider ceremony marker but never approves the quote. The exact immutable quote is rendered afterward and requires a separate explicit POST approval.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Provider authorization callback created with no-store.

PartnerExchangeProviderStepUpOutcome

requestIdrequiredstring
stepUprequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-approval-intents/{intentId}/approveExplicitly approve the immutable quote after provider authorization

Requires the exact prelinked Google or Apple user/account/provider, the intent-bound completed authorization marker, a Loyumi customer session, and an explicit CSRF-bound click. It approves only the immutable fingerprinted quote and does not move value.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `PartnerExchangeCustomerActionRequest`

csrfrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Exact prior approval replayed.

PartnerExchangeApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredPartnerExchangeApprovalIntent

201

Exact quote approved without moving value.

PartnerExchangeApprovalIntentOutcome

requestIdrequiredstring
approvalIntentrequiredPartnerExchangeApprovalIntent

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-linksStart, recover, or read Customer Verification prelink status

Starts the separate member-bound Customer Verification ceremony from a live Loyumi-hosted Widget frame. It cannot approve the current quote. Production links begin a DB-enforced 24-hour cooling period, and the member email is frozen from intent creation until governed revocation.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

Typed responses

200

Current link status or exact existing intent returned.

PartnerExchangeCustomerLinkOutcome

requestIdrequiredstring
customerLinkrequiredPartnerExchangeCustomerLink

201

Customer-link intent created.

PartnerExchangeCustomerLinkOutcome

requestIdrequiredstring
customerLinkrequiredPartnerExchangeCustomerLink

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-links/revocationsStart or recover customer-controlled unlink

Starts a one-way unlink ceremony for the exact current linked provider. It cannot create, rebind, or activate a link. A later relink is a brand-new ceremony and repeats the Production cooling period.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

Typed responses

200

Existing exact unlink intent recovered.

PartnerExchangeCustomerLinkRevocationStartOutcome

requestIdrequiredstring
customerLinkRevocationrequiredPartnerExchangeCustomerLinkRevocation

201

Unlink intent created.

PartnerExchangeCustomerLinkRevocationStartOutcome

requestIdrequiredstring
customerLinkRevocationrequiredPartnerExchangeCustomerLinkRevocation

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

GET/api/v1/partner-exchange-customer-links/{intentId}Poll customer-link or unlink status

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

Typed responses

200

Authoritative link status returned.

PartnerExchangeCustomerLinkOutcome

requestIdrequiredstring
customerLinkrequiredPartnerExchangeCustomerLink

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-links/{intentId}/step-upStart a new provider authorization for link or unlink

Top-level Loyumi-origin transport operation. Link accepts Google or Apple; unlink accepts only the exact current provider. It records a nonce-bound ceremony marker and never creates, revokes, or rebinds a link by itself.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `PartnerExchangeProviderStepUpRequest`

providerrequiredgoogle | apple

Typed responses

200

Provider authorization callback created with no-store.

PartnerExchangeProviderStepUpOutcome

requestIdrequiredstring
stepUprequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-links/{intentId}/completeCreate a durable Customer Verification link

Requires a new Google or Apple authorization ceremony proving control of an unambiguous verified account, an explicit CSRF-bound click, and an exact match to the frozen member email. Production creates a pending link with a DB-time 24-hour cooling fence. It cannot approve a quote.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `PartnerExchangeCustomerActionRequest`

csrfrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Exact completed link replayed.

PartnerExchangeCustomerLinkOutcome

requestIdrequiredstring
customerLinkrequiredPartnerExchangeCustomerLink

201

Customer link created; Production activation remains cooling-period gated.

PartnerExchangeCustomerLinkOutcome

requestIdrequiredstring
customerLinkrequiredPartnerExchangeCustomerLink

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-links/{intentId}/revokeCustomer-control unlink the exact provider link

Requires a new authorization ceremony for the exact current linked provider account and an explicit CSRF-bound click. Revocation atomically invalidates and scrubs the link, open approval intents, active confirmations, and unreserved quotes. The operation is one-way and exact retries replay the receipt; rebind is impossible here.

Scope See operation

Parameters

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

intentIdpathrequiredstring

minimum length 1 · maximum length 200

JSON body · `PartnerExchangeCustomerActionRequest`

csrfrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Customer link revoked or exact prior result replayed.

PartnerExchangeCustomerLinkRevokedOutcome

requestIdrequiredstring
idempotentrequiredboolean
customerLinkrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

POST/api/v1/partner-exchange-customer-links/governed-revocationsGoverned revoke-only recovery after the linked provider is lost

A narrowly scoped server-side recovery for a customer who can no longer authorize with the exact linked provider. It requires an isolated identity-authority credential, three distinct stable opaque merchant-attested identity-review and customer-notification references, a recent verification time, and Idempotency-Key. Loyumi enforces reference shape and separation and records, but does not certify, the merchant's reviewer identity, review, or customer notification. The transaction only revokes and scrubs the current link, open link/approval intents, active assertions, and unreserved quotes. It cannot create, rebind, activate, or bypass cooling; a future relink is a brand-new customer ceremony with the full Production cooling period. No provider, auth-account, member, or link identifier is returned.

Scope members:deleteIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `PartnerExchangeGovernedLinkRevocationRequest`

externalCustomerIdrequiredstring

minimum length 1 · maximum length 200

programIdrequiredstring

minimum length 1 · maximum length 200

reasonrequiredlost_provider_access | provider_account_deleted | provider_access_unrecoverable

customerNotificationReferencerequiredstring

Stable opaque merchant-attested reference that the customer was notified. Must differ from both identity-review references. Loyumi records but does not certify the underlying notification.

evidencerequiredobject

Typed responses

200

Customer Verification revoked or the exact receipt replayed.

PartnerExchangeGovernedLinkRevocationOutcome

requestIdrequiredstring
idempotentrequiredboolean
customerLinkrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

4 operations

Imports

Validated, idempotent, resumable member snapshot imports with explicit exception evidence

POST/api/v1/importsValidate and stage a member snapshot import

Validates up to 5,000 member opening-balance records, stores row-level evidence, and returns a checksum-bound batch without changing members or balances. In Production this operation is available only while the environment is locked in its prelaunch migration window. Requesting activation atomically seals the reconciled import set and closes that window permanently. Reusing the Idempotency-Key with the identical payload returns the original batch. Requires imports:write.

Scope imports:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `MemberImportRequest`

programIdrequiredstring

minimum length 1

schemaVersionoptionalconstant: loyumi.members/v1

default loyumi.members/v1

modeoptionalconstant: snapshot

The 1.8 import contract supports snapshot mode only; every other mode is rejected.

recordsrequiredarray<MemberImportRecord>

minimum 1 item · maximum 5000 items

Request body

{
  "programId": "prg_…",
  "schemaVersion": "loyumi.members/v1",
  "mode": "snapshot",
  "records": [{
    "externalId": "<external-customer-id>",
    "displayName": "<display-name>",
    "points": 2400
  }]
}

Example response

{
  "requestId": "req_…",
  "batch": {
    "id": "imp_…", "operationId": "op_…", "programId": "prg_…",
    "schemaVersion": "loyumi.members/v1", "mode": "snapshot",
    "status": "validated", "checksum": "0000000000000000000000000000000000000000000000000000000000000000",
    "totalRows": 1, "validRows": 1, "exceptionRows": 0,
    "totalPoints": 2400, "applyAllowed": true
  }
}

Typed responses

201

Member snapshot validated and staged without applying customer value, or the original 201 receipt replayed for an identical idempotent command.

MemberImportResponse

requestIdrequiredstring
batchrequiredMemberImportBatch
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The member-import JSON body exceeds the 2 MiB staging limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/importsList member import batches

List member import batches. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires imports:read.

Scope imports:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

statusqueryoptionalvalidated | exceptions_review | applying | completed

Typed responses

200

Request completed.

ImportListOutcome

requestIdrequiredstring
importsrequiredarray<ImportListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/imports/{batchId}Inspect a staged or partially applied member import

Returns batch progress plus a stable row-number page of all, valid, exception, or applied records. Requires imports:read.

Scope imports:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

batchIdpathrequiredstring

minimum length 1

limitqueryoptionalinteger

minimum 1 · maximum 500 · default 100

afterRowqueryoptionalinteger

minimum 0 · default 0

statusqueryoptionalvalid | exception | applied

Request

GET /api/v1/imports/imp_…?status=exception&limit=100
Authorization: Bearer <sandbox-key>
X-Environment: <sandbox-environment-id>

Example response

{
  "requestId": "req_…",
  "batch": {
    "id": "imp_…", "operationId": "op_…", "programId": "prg_…",
    "schemaVersion": "loyumi.members/v1", "mode": "snapshot",
    "status": "validated", "checksum": "0000000000000000000000000000000000000000000000000000000000000000",
    "totalRows": 1, "validRows": 1, "exceptionRows": 0,
    "totalPoints": 2400, "appliedRows": 0, "remainingRows": 1,
    "applyAllowed": true, "appliedAt": null,
    "createdAt": "2026-08-03T08:00:00.000Z",
    "updatedAt": "2026-08-03T08:00:00.000Z"
  },
  "rows": [],
  "page": {
    "limit": 100, "afterRow": 0, "hasMore": false,
    "nextAfterRow": null, "status": "exception"
  }
}

Typed responses

200

Batch progress and row page returned.

MemberImportStatusResponse

requestIdrequiredstring
batchrequiredvalue
rowsrequiredarray<MemberImportRow>
pagerequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/imports/{batchId}/applyApply the next member import chunk

Applies the next validated snapshot rows in a bounded, resumable chunk and preserves row-level outcomes for inspection. Apply creates only missing members and never overwrites an existing member; a newly existing member becomes a snapshot_member_exists row exception. Reusing the same Idempotency-Key and body returns the original chunk outcome. Requires imports:apply.

Scope imports:applyIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

batchIdpathrequiredstring

minimum length 1

JSON body · `ApplyMemberImportRequest`

limitoptionalinteger

minimum 1 · maximum 100 · default 50

Request body

{
  "limit": 100
}

Example response

{
  "requestId": "req_…",
  "batch": {
    "id": "imp_…", "status": "completed", "totalRows": 1,
    "appliedRows": 1, "exceptionRows": 0, "remainingRows": 0,
    "complete": true
  },
  "chunk": { "attempted": 1, "applied": 1, "exceptions": 0 }
}

Typed responses

200

Chunk applied or original idempotent chunk outcome replayed; remaining progress returned.

ApplyMemberImportResponse

requestIdrequiredstring
idempotentoptionalboolean
batchrequiredobject
chunkrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

1 operation

Portability

Versioned, deterministic environment exports for migration and exit

GET/api/v1/exportsExport a versioned, secret-safe environment bundle

Returns 53 migration-critical, environment-scoped collections, including reconstructable reward-gift quote and gift evidence plus participant-safe bilateral exchange records. Gift approval/action intents, provider sessions, claim capabilities, one-use handoffs, and replay secrets are excluded and require explicit cutover actions. Each response is a best-effort request view, not a shared MVCC snapshot or lossless delta. Pause writes for the complete paginated export, drain source obligations, independently reconstruct and reconcile, then switch traffic. Requires exports:read.

Scope exports:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

Export one collection for cursor pagination.

afterqueryoptionalstring

maximum length 256

limitqueryoptionalinteger

minimum 1 · maximum 5000 · default 1000

Request

GET /api/v1/exports?collection=members&limit=1000
Authorization: Bearer <sandbox-key>
X-Environment: <sandbox-environment-id>

Example response

{
  "$schema": "https://app.loyumi.com/schemas/portability-export.v1.6.0.json",
  "version": "1.6.0",
  "requestId": "req_…",
  "generatedAt": "2026-08-17T08:00:00.000Z",
  "scope": { "organizationId": "org_…", "environmentId": "env_…" },
  "environment": {
    "id": "env_…", "name": "Sandbox", "kind": "sandbox", "status": "active"
  },
  "manifest": {
    "format": "application/json",
    "mode": "collection-page",
    "requestedCollection": "members",
    "ordering": "stable collection key, ascending",
    "consistencyModel": "best-effort-request-view",
    "consistency": "One request-time view; pause writes for exact cutover",
    "cutoverRequiresPausedWrites": true,
    "delta": { "supported": false, "reason": "Full or paged export only" },
    "includedCollections": ["members"],
    "excludedSensitiveCollections": [
      {
        "collection": "organizationUsers",
        "table": "organization_users",
        "category": "access-control",
        "transferred": false,
        "reason": "Operator role grants require destination approval.",
        "requiredAction": "Re-provision least-privilege access and review it."
      },
      {
        "collection": "webhookDeliveries",
        "table": "webhook_deliveries",
        "category": "transient",
        "transferred": false,
        "reason": "Delivery jobs remain with the source worker.",
        "requiredAction": "Drain and reconcile source deliveries before cutover."
      },
      {
        "collection": "apiIdempotencyRecords",
        "table": "api_idempotency_records",
        "category": "transient",
        "transferred": false,
        "reason": "Replay caches are runtime safety material.",
        "requiredAction": "Quiesce mutations through the agreed retry horizon."
      },
      {
        "collection": "couponCodes",
        "table": "coupon_codes",
        "category": "bearer-value",
        "transferred": false,
        "reason": "Live bearer-like coupons are not transferred.",
        "requiredAction": "Reconcile, revoke, and reissue destination codes."
      }
    ],
    "recordCounts": { "members": 0 },
    "pagination": {
      "limitPerCollection": 1000, "complete": true, "next": {},
      "instructions": "No next cursor"
    }
  },
  "data": { "members": [] }
}

Typed responses

200

Versioned portability manifest and requested records. Response is no-store and attachment-ready.

PortabilityExport

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

2 operations

Widgets

Server-created sessions for personalized hosted loyalty widgets

POST/api/v1/widget-sessionsCreate a short-lived personalized widget session

Call this endpoint only from the merchant's server after authenticating the customer. Loyumi validates an active production environment (or sandbox), published program and deployment, active member enrollment, exact allowed origin, and requested least-privilege permissions before issuing an opaque one-time code that expires in 60 seconds. Never call it with a Loyumi API key from browser JavaScript or a mobile binary. Requesting rewards:redeem additionally requires widgets:redemptions on the same credential.

Scope widgets:sessions

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `WidgetSessionRequest`

deploymentIdrequiredstring

Published Widget Studio deployment ID.

externalCustomerIdrequiredstring

Customer ID from the merchant's authenticated server session.

originrequiredstring · uri

Exact merchant website origin configured on the widget deployment. Paths, queries, and fragments are rejected. HTTPS is required except for localhost development.

permissionsoptionalarray<string>

Least-privilege widget permissions. rewards:redeem is issued only when redemption is enabled on the deployment and the server credential has both widgets:sessions and widgets:redemptions.

Request body

{
  "deploymentId": "wdg_…",
  "externalCustomerId": "customer-123",
  "origin": "https://rewards.example.com",
  "permissions": ["profile:read"]
}

Example response

{
  "requestId": "req_…",
  "sessionCode": "<single-use-opaque-code>",
  "expiresAt": "2026-08-02T08:01:00.000Z",
  "expiresIn": 60,
  "runtimeMajor": 1
}

Typed responses

201

An opaque single-use 60-second iframe handoff code was created. The response includes Cache-Control: no-store.

WidgetSessionCodeResponse

requestIdrequiredstring
sessionCoderequiredstring
expiresAtrequiredstring · date-time
expiresInrequiredconstant: 60
runtimeMajorrequiredconstant: 1

400

The deployment ID, external customer ID, origin, or request body is invalid.

ApiError

errorrequiredobject

401

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

ApiError

errorrequiredobject

403

Credential lacks widgets:sessions; rewards:redeem additionally lacks widgets:redemptions; or a requested permission is not enabled on the deployment.

ApiError

errorrequiredobject

404

The published deployment is unavailable for the exact origin, or the active member is not enrolled in its program.

ApiError

errorrequiredobject

409

Production is locked or the deployment's loyalty program is no longer published. No code is issued.

ApiError

errorrequiredobject

413

JSON body exceeds the accepted request limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

429

Rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Do not reuse or persist failed session material.

ApiError

errorrequiredobject

POST/api/v1/widget-sessions/exchangeExchange a one-time code inside the hosted iframe

This browser endpoint is called only by the same-origin Loyumi hosted iframe. It atomically consumes the exact deployment- and merchant-origin-bound code once, then revalidates the active production environment (or sandbox), published program and deployment, active member, and issuing credential before returning a signed session to iframe memory. A code stays consumed when any mutable authorization check fails, so later re-enabling a resource cannot revive it. Merchant parent pages and backend integrations must not call this endpoint.

Scope See operation

JSON body · `WidgetSessionExchangeRequest`

sessionCoderequiredstring

deploymentIdrequiredstring

minimum length 1

originrequiredstring · uri

Exact merchant origin bound to the one-time code.

Typed responses

201

The code was consumed and a signed 10-minute iframe session was created with Cache-Control: no-store.

WidgetSessionExchangeResponse

requestIdrequiredstring
sessionTokenrequiredstring
expiresAtrequiredstring · date-time
expiresInrequiredconstant: 600
runtimeMajorrequiredconstant: 1

400

The request body or exact merchant origin is invalid.

ApiError

errorrequiredobject

401

The code is invalid, expired, already consumed, mismatched, or no longer authorized.

ApiError

errorrequiredobject

403

The exchange did not originate from the same-origin hosted iframe.

ApiError

errorrequiredobject

413

JSON body exceeds 16 KiB.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

429

Iframe exchange velocity exceeded its limit. Honor Retry-After.

ApiError

errorrequiredobject

2 operations

Transactions

Cursor-paged ledger transaction search and balanced entry inspection

GET/api/v1/transactionsList and filter posted ledger transactions

List and filter posted ledger transactions. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires transactions:read.

Scope transactions:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

programIdqueryoptionalstring

externalCustomerIdqueryoptionalstring

eventTypequeryoptionalstring

sourceReferencequeryoptionalstring

statequeryoptionalcommitted | reversed

fromqueryoptionalstring · date-time

toqueryoptionalstring · date-time

Typed responses

200

Request completed.

TransactionListOutcome

requestIdrequiredstring
transactionsrequiredarray<TransactionListItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/transactions/{transactionId}Get a transaction and its balanced entries

Scope transactions:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

transactionIdpathrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Request completed.

TransactionDetailOutcome

requestIdrequiredstring
transactionrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

3 operations

Operations

Import and maintenance operation visibility plus environment-scoped audit evidence

GET/api/v1/operationsList operational runs

List operational runs. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires operations:read.

Scope operations:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

typequeryoptionalstring

statusqueryoptionalstring

Typed responses

200

Request completed.

OperationListOutcome

requestIdrequiredstring
operationsrequiredarray<OperationItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/operations/{operationId}Get operation progress and related import evidence

Scope operations:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

operationIdpathrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Request completed.

OperationDetailOutcome

requestIdrequiredstring
operationrequiredvalue

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/audit-eventsList environment-attributed audit evidence

List environment-attributed audit evidence. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires audit:read.

Scope audit:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

actionqueryoptionalstring

targetTypequeryoptionalstring

targetIdqueryoptionalstring

actorIdqueryoptionalstring

Typed responses

200

Request completed.

AuditEventListOutcome

requestIdrequiredstring
auditEventsrequiredarray<AuditEventItem>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

2 operations

Analytics

Bounded, descriptive ledger aggregates without attribution claims

GET/api/v1/analytics/ledger-summaryGet bounded descriptive ledger analytics

Returns real ledger and operational aggregates for a positive window of at most 90 days. programId filters member, transaction, movement, balance, and redemption metrics; webhook delivery counts remain environment-wide because deliveries are not program-attributed. Values are a best-effort request view, not revenue attribution, an incremental-lift claim, or a financial-close report.

Scope analytics:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

programIdqueryoptionalstring

fromqueryoptionalstring · date-time

toqueryoptionalstring · date-time

Typed responses

200

Request completed.

LedgerAnalyticsOutcome

requestIdrequiredstring
asOfrequiredstring · date-time
windowrequiredobject
programIdrequiredstring | null
consistencyrequiredobject
membersCreatedByStatusrequiredobject
transactionsrequiredobject
memberAvailableMovementsrequiredobject
currentMemberBalancesrequiredobject
redemptionsByStaterequiredobject
webhookDeliveriesByStatusrequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

GET/api/v1/reports/ledger-closeGenerate exact program-period ledger close evidence

Returns a deterministic program-period point roll-forward, movement by event type, double-entry control totals, finance-policy valuation in merchant-currency micros, readiness checks, and a SHA-256 evidence hash. Decimal strings prevent JavaScript precision loss. The report is system-generated evidence, not an independent audit, contractual financial statement, revenue attribution, or proof that upstream commerce data was complete. Requires analytics:read.

Scope analytics:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

programIdqueryrequiredstring

minimum length 1 · maximum length 200

fromqueryoptionalstring · date-time

Inclusive ISO-8601 start. Defaults to the first instant of the UTC month containing to.

toqueryoptionalstring · date-time

Exclusive ISO-8601 end. Defaults to the current instant.

Typed responses

200

Exact ledger close control evidence generated.

LedgerCloseReportOutcome

requestIdrequiredstring
reportIdrequiredstring
generatedAtrequiredstring · date-time
integrityrequiredobject
evidencerequiredLedgerCloseEvidence
assurancerequiredobject

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

8 operations

Webhooks

Secret-safe endpoint management, delivery inspection, tests, and governed retry

GET/api/v1/webhook-endpointsList secret-safe webhook endpoints

List secret-safe webhook endpoints. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires webhooks:read.

Scope webhooks:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

Typed responses

200

Request completed.

WebhookEndpointListOutcome

requestIdrequiredstring
webhookEndpointsrequiredarray<WebhookEndpoint>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/webhook-endpointsCreate a disabled webhook endpoint

Creates an endpoint disabled and returns its encrypted-at-rest signing secret exactly once. Idempotent replay never returns the secret. URL validation rejects credentials, obvious loopback/private literals, local hostnames, and redirects; production egress and DNS controls remain deployment responsibilities.

Scope webhooks:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

JSON body · `WebhookEndpointCreateRequest`

urlrequiredstring · uri

maximum length 2048

eventTypesrequiredarray<string>

minimum 1 item · maximum 33 items

Typed responses

200

Idempotent replay without signing secret.

WebhookEndpointOutcome

requestIdrequiredstring
endpointrequiredWebhookEndpoint
signingSecretoptionalstring
signingSecretAvailableoptionalboolean
noticeoptionalstring
idempotentoptionalboolean

201

Endpoint created; signing secret returned once.

WebhookEndpointOutcome

requestIdrequiredstring
endpointrequiredWebhookEndpoint
signingSecretoptionalstring
signingSecretAvailableoptionalboolean
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

503

Webhook secret encryption is unavailable.

ApiError

errorrequiredobject

GET/api/v1/webhook-endpoints/{endpointId}Get a secret-safe webhook endpoint

Scope webhooks:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

endpointIdpathrequiredstring

minimum length 1 · maximum length 256

Typed responses

200

Request completed.

WebhookEndpointOutcome

requestIdrequiredstring
endpointrequiredWebhookEndpoint
signingSecretoptionalstring
signingSecretAvailableoptionalboolean
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

PATCH/api/v1/webhook-endpoints/{endpointId}Update or activate a webhook endpoint

Updates URL, supported event types, or state. A URL change forces disabled state. Requires Idempotency-Key.

Scope webhooks:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

endpointIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `WebhookEndpointUpdateRequest`

urloptionalstring · uri

maximum length 2048

eventTypesoptionalarray<string>

minimum 1 item · maximum 33 items

statusoptionalactive | disabled

Typed responses

200

Request completed.

WebhookEndpointOutcome

requestIdrequiredstring
endpointrequiredWebhookEndpoint
signingSecretoptionalstring
signingSecretAvailableoptionalboolean
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/webhook-endpoints/{endpointId}/rotate-secretRotate once-visible signing secret and disable endpoint

Replaces the encrypted signing secret, increments its version, disables the endpoint, and returns the new secret only in the original response.

Scope webhooks:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

endpointIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `EmptyCommand`

Typed responses

200

Request completed.

WebhookEndpointOutcome

requestIdrequiredstring
endpointrequiredWebhookEndpoint
signingSecretoptionalstring
signingSecretAvailableoptionalboolean
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

503

Webhook secret encryption is unavailable.

ApiError

errorrequiredobject

POST/api/v1/webhook-endpoints/{endpointId}/testSend an idempotent non-PII test delivery

Persists an immutable idempotency receipt and leased delivery record before sending a non-PII test, rejects redirects, and resolves every replay from the current durable delivery state without returning its payload. A post-send finalization failure is recovered after the bounded sending lease with the same eventId and payload, but a fresh timestamp/signature; delivery is at least once, so consumers must deduplicate eventId and must not assume exactly once.

Scope webhooks:writeIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

endpointIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `EmptyCommand`

Typed responses

200

Request completed.

WebhookDeliveryOutcome

requestIdrequiredstring
deliveryrequiredWebhookDelivery
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

503

Webhook secret encryption is unavailable.

ApiError

errorrequiredobject

GET/api/v1/webhook-deliveriesList PII-safe webhook delivery evidence

List PII-safe webhook delivery evidence. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires webhooks:read.

Scope webhooks:read

Parameters

X-Environmentheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

limitqueryoptionalinteger

minimum 1 · maximum 200 · default 50

cursorqueryoptionalstring

maximum length 512

endpointIdqueryoptionalstring

eventTypequeryoptionalstring

statusqueryoptionalpending | sending | failed | delivered | dead_letter

Typed responses

200

Request completed.

WebhookDeliveryListOutcome

requestIdrequiredstring
webhookDeliveriesrequiredarray<WebhookDelivery>
pagerequiredCursorPage

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

POST/api/v1/webhook-deliveries/{deliveryId}/retryIdempotently re-queue a failed delivery

Re-queues the existing failed or dead-letter record only when its endpoint is active. It does not create a duplicate record or synchronously contact the merchant endpoint.

Scope webhooks:retryIdempotency required

Parameters

X-Environmentheaderrequiredstring

minimum length 1

Idempotency-Keyheaderrequiredstring

minimum length 1

X-Request-Idheaderoptionalstring

Caller-provided trace identifier. Loyumi creates one when omitted.

deliveryIdpathrequiredstring

minimum length 1 · maximum length 256

JSON body · `EmptyCommand`

Typed responses

200

Request completed.

WebhookDeliveryOutcome

requestIdrequiredstring
deliveryrequiredWebhookDelivery
noticeoptionalstring
idempotentoptionalboolean

400

Malformed JSON, required header missing, or unsupported command.

ApiError

errorrequiredobject

401

Credential, environment, or one-time member token is invalid.

ApiError

errorrequiredobject

403

Credential lacks the operation's required scope or violates two-person control.

ApiError

errorrequiredobject

404

The environment-scoped resource was not found.

ApiError

errorrequiredobject

409

State, balance, inventory, version, approval, or idempotency payload conflicts with the request.

ApiError

errorrequiredobject

410

IdempotencyReceiptPrivacyScrubbedError

errorrequiredobject

413

The JSON request body exceeds the operation's 128 KiB limit.

ApiError

errorrequiredobject

415

Content-Type must be application/json.

ApiError

errorrequiredobject

422

The request is well-formed JSON but violates the operation contract.

ApiError

errorrequiredobject

429

Credential rate limit exceeded. Honor Retry-After.

ApiError

errorrequiredobject

500

Internal processing error. Retry an idempotent mutation with the same key and identical body.

ApiError

errorrequiredobject

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.

Every request is environment-scoped.

Endpoint reference.

Parameters

JSON body · PurchaseRequest

Typed responses

Parameters

JSON body · ReturnRequest

Typed responses

Parameters

JSON body · OfferEvaluationRequest

Typed responses

Parameters

JSON body · CustomEventRequest

Typed responses

Parameters

JSON body · ChoiceBenefitRequest

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

Typed responses

Parameters

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · MemberProgramEnrollmentRequest

Typed responses

Parameters

JSON body · MemberProgramUnenrollmentRequest

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

Typed responses

Parameters

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

Typed responses

Parameters

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

Typed responses

Parameters

Typed responses

Parameters

JSON body · object

Typed responses

Parameters

JSON body · object

JSON body · `PurchaseRequest`

JSON body · `ReturnRequest`

JSON body · `OfferEvaluationRequest`

JSON body · `CustomEventRequest`

JSON body · `ChoiceBenefitRequest`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `MemberProgramEnrollmentRequest`

JSON body · `MemberProgramUnenrollmentRequest`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `object`

JSON body · `ProgramManifestInput`

JSON body · `ProgramManifestInput`

JSON body · `ProgramManifestInput`

JSON body · `object`

JSON body · `object`

JSON body · `RewardGiftCreateRequest`

JSON body · `RewardGiftClaimHandoffRequest`

JSON body · `RewardGiftClaimHandoffExchangeRequest`

JSON body · `RewardGiftApprovalIntentRequest`

JSON body · `RewardGiftExplicitActionRequest`

JSON body · `RewardGiftAcceptanceRequest`

JSON body · `RewardGiftDecisionRequest`