{ "openapi": "3.1.0", "info": { "title": "Loyumi Public API", "version": "1.13.0", "description": "Environment-scoped APIs for governed loyalty value, durable recipient-bound catalog-entitlement gift invitations and choice, purpose-bound delivery evidence, first-party participant wallets, single-use entitlement evidence, lifecycle webhooks, cursor-paged operations, and portable program state." }, "servers": [ { "url": "https://app.loyumi.com/api/v1", "description": "Loyumi API; the key and X-Environment header select Sandbox or production" } ], "tags": [ { "name": "Commerce", "description": "Earn, return, and offer-evaluation operations" }, { "name": "Engagement", "description": "Registered custom events and milestone benefits" }, { "name": "Members", "description": "Member enrollment, profile updates, and balance reads" }, { "name": "Redemptions", "description": "Quoted, reserved, committed, released, expired, reversed, fulfilled, and disputed point spends" }, { "name": "Adjustments", "description": "Evidence-backed, independently approved manual ledger corrections" }, { "name": "Programs", "description": "Validated, immutable program manifests with optimistic concurrency and controlled publishing" }, { "name": "Gifts", "description": "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." }, { "name": "Partners", "description": "Bilateral exchange agreements, private member links, conversion quotes, exchanges, and settlement evidence" }, { "name": "Imports", "description": "Validated, idempotent, resumable member snapshot imports with explicit exception evidence" }, { "name": "Portability", "description": "Versioned, deterministic environment exports for migration and exit" }, { "name": "Widgets", "description": "Server-created sessions for personalized hosted loyalty widgets" }, { "name": "Transactions", "description": "Cursor-paged ledger transaction search and balanced entry inspection" }, { "name": "Operations", "description": "Import and maintenance operation visibility plus environment-scoped audit evidence" }, { "name": "Analytics", "description": "Bounded, descriptive ledger aggregates without attribution claims" }, { "name": "Webhooks", "description": "Secret-safe endpoint management, delivery inspection, tests, and governed retry" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Environment-specific server credential. Never embed it in browser JavaScript or a mobile binary." }, "widgetSessionAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Short-lived member-bound Widget session sent as `Authorization: Widget `. This is issued only to a Loyumi-hosted frame and is never a merchant API credential. Origin checks are transport controls, not customer proof." }, "customerSessionAuth": { "type": "apiKey", "in": "cookie", "name": "__Secure-better-auth.session_token", "description": "Loyumi customer session established by a new Google or Apple provider authorization ceremony. Quote approval additionally requires an intent-bound CSRF value and the exact prelinked provider account." }, "rewardGiftClaimSessionAuth": { "type": "apiKey", "in": "header", "name": "X-Loyumi-Gift-Session", "description": "Ephemeral gift-bound session held only in the authoritative Loyumi frame closure. It is accepted only from the same origin with the matching live Widget session JTI, deployment, tenant, environment, program, member, gift, and consumed handoff. It must never enter merchant JavaScript, postMessage, DOM, storage, URLs, analytics, or logs." } }, "parameters": { "environment": { "name": "X-Environment", "in": "header", "required": true, "description": "Environment ID that owns the bearer credential.", "schema": { "type": "string", "minLength": 1 } }, "idempotency": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable identity for one business mutation. Reuse the same key and identical body when retrying. A governed privacy deletion can supersede historic replay with HTTP 410 idempotency_receipt_privacy_scrubbed.", "schema": { "type": "string", "minLength": 1 } }, "requestId": { "name": "X-Request-Id", "in": "header", "required": false, "description": "Caller-provided trace identifier. Loyumi creates one when omitted.", "schema": { "type": "string" } }, "ifMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Exact ETag returned by the current program configuration or latest revision. Prevents an operator from overwriting a concurrent change.", "schema": { "type": "string", "minLength": 1 } } }, "responses": { "BadRequest": { "description": "Malformed JSON, required header missing, or unsupported command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Unauthorized": { "description": "Credential, environment, or one-time member token is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "Credential lacks the operation's required scope or violates two-person control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "The environment-scoped resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Conflict": { "description": "State, balance, inventory, version, approval, or idempotency payload conflicts with the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "PreconditionRequired": { "description": "If-Match is required for this configuration mutation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "PreconditionFailed": { "description": "If-Match does not equal the latest immutable configuration ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Unprocessable": { "description": "The request is well-formed JSON but violates the operation contract.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "PayloadTooLarge": { "description": "The JSON request body exceeds the operation's 128 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "UnsupportedMediaType": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "ImportPayloadTooLarge": { "description": "The member-import JSON body exceeds the 2 MiB staging limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "RateLimited": { "description": "Credential rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "InternalError": { "description": "Internal processing error. Retry an idempotent mutation with the same key and identical body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "IdempotencyReceiptPrivacyScrubbed": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyReceiptPrivacyScrubbedError" } } } } }, "schemas": { "CartItem": { "type": "object", "description": "Normalized commerce line used for offer decisions, purchase attribution, and precise line-selected returns. Monetary fields use the request currency's minor units.", "required": [ "sku", "quantity", "unitPriceMinor" ], "properties": { "lineReference": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Stable merchant line identity. Required on purchases that may later use line-selected returns." }, "lineId": { "type": "string", "minLength": 1, "maxLength": 200, "deprecated": true, "description": "Deprecated compatibility alias for lineReference. Send lineReference in new integrations. If both are present, lineReference takes precedence." }, "sku": { "type": "string", "minLength": 1 }, "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "category": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "unitPriceMinor": { "type": "integer", "minimum": 1, "description": "Price for one unit in integer minor currency units." }, "discountMinor": { "type": "integer", "minimum": 0, "default": 0, "description": "Total discount allocated to this line." }, "taxMinor": { "type": "integer", "minimum": 0, "default": 0, "description": "Total tax allocated to this line." }, "eligibleAmountMinor": { "type": "integer", "minimum": 0, "description": "Line value eligible to earn points; defaults to the reconciled line amount." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Merchant product facts retained as normalized line evidence. Current built-in purchase rules do not interpret arbitrary attribute keys." } } }, "CommerceTotals": { "type": "object", "additionalProperties": false, "required": [ "amountMinor", "subtotalMinor", "discountMinor", "taxMinor", "shippingMinor", "eligibleAmountMinor" ], "properties": { "amountMinor": { "type": "integer", "minimum": 1 }, "subtotalMinor": { "type": "integer", "minimum": 0 }, "discountMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "shippingMinor": { "type": "integer", "minimum": 0 }, "eligibleAmountMinor": { "type": "integer", "minimum": 0 } }, "description": "Normalized totals satisfying subtotalMinor - discountMinor + taxMinor + shippingMinor = amountMinor. eligibleAmountMinor is the value evaluated for earning." }, "LinePointAttribution": { "type": "object", "additionalProperties": false, "required": [ "lineReference", "points" ], "properties": { "lineReference": { "type": "string" }, "points": { "type": "integer", "minimum": 0 } } }, "ApiError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": true, "description": "Optional machine-readable conflict or policy context." } } } } }, "PurchaseRequest": { "type": "object", "description": "A completed order evaluated at receipt time by default. A late event can explicitly select event-time evaluation by supplying occurredAt and context.attributes.loyumiEvaluation with an immutable configurationVersion and historical memberTier.", "additionalProperties": false, "required": [ "type", "programId", "externalCustomerId", "amountMinor", "sourceReference" ], "properties": { "type": { "const": "purchase.completed" }, "programId": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "minLength": 1 }, "amountMinor": { "type": "integer", "minimum": 1, "description": "Merchant-normalized completed order value in the configured program currency's integer minor units." }, "channel": { "type": "string", "enum": [ "web", "store", "app", "partner", "marketplace", "call_center" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 transaction currency. Must match the program's configured currency." }, "occurredAt": { "type": "string", "format": "date-time", "description": "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." }, "storeId": { "type": "string", "minLength": 1, "maxLength": 200 }, "terminalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "market": { "type": "string", "minLength": 1, "maxLength": 100 }, "locale": { "type": "string", "minLength": 1, "maxLength": 100 }, "deviceType": { "type": "string", "minLength": 1, "maxLength": 100 }, "orderType": { "type": "string", "minLength": 1, "maxLength": 100 }, "salesAssociateId": { "type": "string", "minLength": 1, "maxLength": 200 }, "customerTags": { "type": "array", "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "attributes": { "$ref": "#/components/schemas/PurchaseAttributes" }, "context": { "$ref": "#/components/schemas/PurchaseNestedContext" }, "subtotalMinor": { "type": "integer", "minimum": 0 }, "discountMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "shippingMinor": { "type": "integer", "minimum": 0 }, "eligibleAmountMinor": { "type": "integer", "minimum": 0 }, "sourceAmountMinor": { "type": "integer", "minimum": 1, "description": "Original pre-normalization transaction amount; requires the complete FX evidence group." }, "sourceCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fxRate": { "type": "string", "pattern": "^(?:0\\.(?:0*[1-9]\\d*)|[1-9]\\d*(?:\\.\\d{1,12})?)$" }, "fxRateSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "fxRateAt": { "type": "string", "format": "date-time" }, "sourceReference": { "type": "string", "minLength": 1, "description": "Stable order reference from the commerce system." }, "couponCode": { "type": "string", "description": "Optional coupon code associated with this purchase." }, "items": { "type": "array", "maxItems": 500, "description": "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.", "items": { "$ref": "#/components/schemas/CartItem" } } }, "dependentRequired": { "sourceAmountMinor": [ "sourceCurrency", "fxRate", "fxRateSource", "fxRateAt" ], "sourceCurrency": [ "sourceAmountMinor", "fxRate", "fxRateSource", "fxRateAt" ], "fxRate": [ "sourceAmountMinor", "sourceCurrency", "fxRateSource", "fxRateAt" ], "fxRateSource": [ "sourceAmountMinor", "sourceCurrency", "fxRate", "fxRateAt" ], "fxRateAt": [ "sourceAmountMinor", "sourceCurrency", "fxRate", "fxRateSource" ] } }, "CampaignDecision": { "type": "object", "additionalProperties": false, "required": [ "campaignId", "name", "award", "applied", "reason", "maxAwardsPerMember", "ruleDecisions" ], "properties": { "campaignId": { "type": "string" }, "name": { "type": "string" }, "award": { "type": "integer", "minimum": 0 }, "applied": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "applied", "blocked_by_exclusive_campaign", "lower_value_candidate", "not_selected", "audience_not_matched", "rule_conditions_not_met", "award_limit_reached", "budget_exceeded" ] }, "maxAwardsPerMember": { "type": "integer", "minimum": 0 }, "ruleDecisions": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRuleDecision" } } } }, "PurchaseOutcome": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "requestId", "evaluationMode", "evaluationAt", "configurationVersion", "occurredAt", "receivedAt", "evaluatedAt", "currency", "totals", "linePointAttribution", "member", "award", "ruleDecisions", "campaigns", "referral", "coupon" ], "properties": { "id": { "type": "string" }, "status": { "const": "committed" }, "requestId": { "type": "string" }, "evaluationMode": { "type": "string", "enum": [ "receipt_time_current_configuration", "event_time_pinned_configuration" ], "description": "The policy clock used for rule, tier, and campaign decisions." }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "totals": { "$ref": "#/components/schemas/CommerceTotals" }, "linePointAttribution": { "type": "array", "items": { "$ref": "#/components/schemas/LinePointAttribution" } }, "member": { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "tier" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": "string" }, "tier": { "type": "string" } } }, "award": { "type": "object", "additionalProperties": false, "required": [ "points", "basePoints", "campaignPoints", "loyaltyUnitPrecision" ], "properties": { "points": { "type": "integer" }, "basePoints": { "type": "integer" }, "campaignPoints": { "type": "integer" }, "loyaltyUnitPrecision": { "type": "integer", "minimum": 0, "maximum": 9 } } }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignDecision" } }, "referral": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "id", "status", "rewardPoints", "transactionId" ], "properties": { "id": { "type": "string" }, "status": { "const": "qualified" }, "rewardPoints": { "type": "integer", "minimum": 0 }, "transactionId": { "type": [ "string", "null" ] } } } ] }, "coupon": { "type": [ "string", "null" ] }, "evaluationAt": { "type": "string", "format": "date-time" }, "configurationVersion": { "type": "integer", "minimum": 1 }, "ruleDecisions": { "type": "array", "items": { "$ref": "#/components/schemas/EarnRuleDecision" } } } }, "IdempotentOutcome": { "type": "object", "required": [ "id", "idempotent", "requestId" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "state": { "type": "string" }, "idempotent": { "const": true }, "requestId": { "type": "string" } } }, "ReturnRequest": { "type": "object", "description": "A full or partial return selected by stable purchase line and quantity, by legacy monetary amount, or by both. When both are supplied, returnAmountMinor must match the amount computed from the selected original lines.", "additionalProperties": false, "required": [ "sourceReference", "returnReference" ], "properties": { "sourceReference": { "type": "string", "minLength": 1, "description": "Reference of the original completed order." }, "returnReference": { "type": "string", "minLength": 1, "description": "Stable identity for this full or partial return." }, "returnAmountMinor": { "type": "integer", "minimum": 1, "description": "Legacy amount-based return value, or an integrity check for an item-selected return." }, "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "quantity" ], "properties": { "lineReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "lineId": { "type": "string", "minLength": 1, "maxLength": 200, "deprecated": true, "description": "Deprecated compatibility alias for lineReference. Send lineReference in new integrations. If both are present, lineReference takes precedence." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, "anyOf": [ { "required": [ "lineReference" ] }, { "required": [ "lineId" ] } ] } } }, "anyOf": [ { "required": [ "returnAmountMinor" ] }, { "required": [ "items" ] } ] }, "ReturnOutcome": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "requestId", "return" ], "properties": { "id": { "type": "string" }, "status": { "const": "committed" }, "requestId": { "type": "string" }, "return": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceReference", "returnReference", "returnAmountMinor", "pointsClawedBack", "orderStatus", "items" ], "properties": { "id": { "type": "string" }, "sourceReference": { "type": "string" }, "returnReference": { "type": "string" }, "returnAmountMinor": { "type": "integer", "minimum": 1 }, "pointsClawedBack": { "type": "integer", "minimum": 0 }, "orderStatus": { "type": "string", "enum": [ "partially_returned", "returned" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnedLineOutcome" } } } } } }, "ReturnedLineOutcome": { "type": "object", "additionalProperties": false, "required": [ "lineReference", "quantity", "amountMinor", "pointsClawedBack" ], "properties": { "lineReference": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "amountMinor": { "type": "integer", "minimum": 0 }, "pointsClawedBack": { "type": "integer", "minimum": 0 } } }, "ReturnIdempotentOutcome": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "idempotent", "requestId" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "idempotent": { "const": true }, "requestId": { "type": "string" }, "return": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "sourceReference", "returnReference", "returnAmountMinor", "pointsClawedBack", "items" ], "properties": { "sourceReference": { "type": "string" }, "returnReference": { "type": "string" }, "returnAmountMinor": { "type": "integer", "minimum": 1 }, "pointsClawedBack": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnedLineOutcome" } } } } ] } } }, "CustomEventRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "externalCustomerId", "sourceReference" ], "properties": { "type": { "type": "string", "minLength": 1, "description": "Name of an active event definition in the selected environment.", "maxLength": 200 }, "externalCustomerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "occurredAt": { "type": "string", "format": "date-time", "maxLength": 64 }, "attributes": { "type": "object", "additionalProperties": true } } }, "OfferEvaluationRequest": { "type": "object", "description": "Contextual, non-mutating offer evaluation. When externalCustomerId is supplied, the evaluator can resolve member-specific state. Built-in selectors evaluate program, member tier, channel, currency, store, market, customer tags, SKU, product ID, and category. Arbitrary attributes are accepted but are not interpreted by current built-in selectors. occurredAt is retained as merchant context, while current offers and configuration are selected at server receipt time.", "additionalProperties": false, "required": [ "items" ], "properties": { "programId": { "type": "string", "description": "Required to include program-scoped offers." }, "externalCustomerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "couponCode": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 1, "description": "Optional reconciled order total. When omitted, the evaluator derives it from normalized items and optional shippingMinor." }, "channel": { "type": "string", "enum": [ "web", "store", "app", "partner", "marketplace", "call_center" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "occurredAt": { "type": "string", "format": "date-time", "description": "Merchant business timestamp retained as decision context; it does not select a historical offer configuration." }, "storeId": { "type": "string", "minLength": 1, "maxLength": 200 }, "terminalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "market": { "type": "string", "minLength": 1, "maxLength": 100 }, "locale": { "type": "string", "minLength": 1, "maxLength": 100 }, "deviceType": { "type": "string", "minLength": 1, "maxLength": 100 }, "orderType": { "type": "string", "minLength": 1, "maxLength": 100 }, "salesAssociateId": { "type": "string", "minLength": 1, "maxLength": 200 }, "customerTags": { "type": "array", "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "attributes": { "type": "object", "additionalProperties": true }, "context": { "type": "object", "additionalProperties": true }, "subtotalMinor": { "type": "integer", "minimum": 0 }, "discountMinor": { "type": "integer", "minimum": 0 }, "taxMinor": { "type": "integer", "minimum": 0 }, "shippingMinor": { "type": "integer", "minimum": 0 }, "eligibleAmountMinor": { "type": "integer", "minimum": 0 }, "sourceAmountMinor": { "type": "integer", "minimum": 1 }, "sourceCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fxRate": { "type": "string", "pattern": "^(?:0\\.(?:0*[1-9]\\d*)|[1-9]\\d*(?:\\.\\d{1,12})?)$" }, "fxRateSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "fxRateAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/CartItem" } } }, "dependentRequired": { "externalCustomerId": [ "programId" ], "sourceAmountMinor": [ "sourceCurrency", "fxRate", "fxRateSource", "fxRateAt" ], "sourceCurrency": [ "sourceAmountMinor", "fxRate", "fxRateSource", "fxRateAt" ], "fxRate": [ "sourceAmountMinor", "sourceCurrency", "fxRateSource", "fxRateAt" ], "fxRateSource": [ "sourceAmountMinor", "sourceCurrency", "fxRate", "fxRateAt" ], "fxRateAt": [ "sourceAmountMinor", "sourceCurrency", "fxRate", "fxRateSource" ] } }, "OfferEvaluationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "evaluationMode", "occurredAt", "receivedAt", "evaluatedAt", "currency", "totals", "subtotalMinor", "discountMinor", "totalMinor", "member", "effects", "coupon" ], "properties": { "requestId": { "type": "string" }, "evaluationMode": { "const": "receipt_time_current_configuration" }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "totals": { "$ref": "#/components/schemas/CommerceTotals" }, "subtotalMinor": { "type": "integer", "minimum": 0 }, "discountMinor": { "type": "integer", "minimum": 0 }, "totalMinor": { "type": "integer", "minimum": 0 }, "member": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "tier" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": "string" }, "tier": { "type": [ "string", "null" ] } } } ] }, "effects": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "offerId", "name", "kind", "discountMinor", "stackingPolicy", "eligible", "reason", "eligibleAmountMinor", "matchedLineReferences", "applied" ], "properties": { "offerId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "percent_order", "fixed_order", "percent_items", "fixed_items" ] }, "discountMinor": { "type": "integer", "minimum": 0 }, "stackingPolicy": { "type": "string", "enum": [ "exclusive", "stack", "best_value" ] }, "eligible": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "eligible", "context_channels_mismatch", "context_currencies_mismatch", "context_storeIds_mismatch", "context_markets_mismatch", "context_memberTiers_mismatch", "context_customer_tags_mismatch", "product_selector_mismatch", "offer_expired", "program_mismatch", "minimum_spend_not_met", "coupon_required", "coupon_unavailable" ] }, "eligibleAmountMinor": { "type": "integer", "minimum": 0 }, "matchedLineReferences": { "type": "array", "items": { "type": "string" } }, "applied": { "type": "boolean" } } } }, "coupon": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "code", "valid" ], "properties": { "code": { "type": "string" }, "valid": { "type": "boolean" } } } ] } } }, "PortabilityExport": { "$ref": "https://app.loyumi.com/schemas/portability-export.v1.6.0.json" }, "MemberImportRecord": { "type": "object", "additionalProperties": false, "required": [ "externalId", "displayName", "points" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 300 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "points": { "type": "integer", "minimum": 0 } } }, "MemberImportRequest": { "type": "object", "additionalProperties": false, "required": [ "programId", "records" ], "properties": { "programId": { "type": "string", "minLength": 1 }, "schemaVersion": { "type": "string", "const": "loyumi.members/v1", "default": "loyumi.members/v1" }, "mode": { "type": "string", "const": "snapshot", "default": "snapshot", "description": "The 1.8 import contract supports snapshot mode only; every other mode is rejected." }, "records": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "$ref": "#/components/schemas/MemberImportRecord" } } } }, "MemberImportBatch": { "type": "object", "additionalProperties": false, "required": [ "id", "operationId", "programId", "schemaVersion", "mode", "status", "checksum", "totalRows", "validRows", "exceptionRows", "totalPoints", "applyAllowed" ], "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "programId": { "type": "string" }, "schemaVersion": { "const": "loyumi.members/v1" }, "mode": { "const": "snapshot" }, "status": { "type": "string", "enum": [ "validated", "exceptions_review", "applying", "completed" ] }, "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "totalRows": { "type": "integer", "minimum": 0 }, "validRows": { "type": "integer", "minimum": 0 }, "exceptionRows": { "type": "integer", "minimum": 0 }, "totalPoints": { "type": "integer", "minimum": 0 }, "applyAllowed": { "type": "boolean" }, "appliedRows": { "type": "integer", "minimum": 0 }, "remainingRows": { "type": "integer", "minimum": 0 }, "appliedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "MemberImportResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "batch" ], "properties": { "requestId": { "type": "string" }, "batch": { "$ref": "#/components/schemas/MemberImportBatch" }, "idempotent": { "type": "boolean" } } }, "MemberImportRow": { "type": "object", "additionalProperties": false, "required": [ "rowNumber", "externalId", "displayName", "email", "points", "status", "errorCode", "errorDetail" ], "properties": { "rowNumber": { "type": "integer", "minimum": 1 }, "externalId": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "points": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "valid", "exception", "applied" ] }, "errorCode": { "type": [ "string", "null" ] }, "errorDetail": { "type": [ "string", "null" ] } } }, "MemberImportStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "batch", "rows", "page" ], "properties": { "requestId": { "type": "string" }, "batch": { "allOf": [ { "$ref": "#/components/schemas/MemberImportBatch" }, { "required": [ "id", "operationId", "programId", "schemaVersion", "mode", "status", "checksum", "totalRows", "validRows", "exceptionRows", "totalPoints", "appliedRows", "remainingRows", "applyAllowed", "appliedAt", "createdAt", "updatedAt" ] } ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/MemberImportRow" } }, "page": { "type": "object", "additionalProperties": false, "description": "Stable row-number cursor state for this batch query.", "required": [ "limit", "afterRow", "hasMore", "nextAfterRow", "status" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "afterRow": { "type": "integer", "minimum": 0 }, "nextAfterRow": { "type": [ "integer", "null" ], "minimum": 1 }, "hasMore": { "type": "boolean" }, "status": { "type": [ "string", "null" ], "enum": [ "valid", "exception", "applied", null ] } } } } }, "ApplyMemberImportRequest": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "ApplyMemberImportResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "batch", "chunk" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this response replays the original outcome for the same Idempotency-Key and identical request." }, "batch": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "totalRows", "appliedRows", "exceptionRows", "remainingRows", "complete" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "applying", "exceptions_review", "completed" ] }, "totalRows": { "type": "integer", "minimum": 0 }, "appliedRows": { "type": "integer", "minimum": 0 }, "exceptionRows": { "type": "integer", "minimum": 0 }, "remainingRows": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean" } } }, "chunk": { "type": "object", "additionalProperties": false, "required": [ "attempted", "applied", "exceptions" ], "properties": { "attempted": { "type": "integer", "minimum": 0 }, "applied": { "type": "integer", "minimum": 0 }, "exceptions": { "type": "integer", "minimum": 0 } } } } }, "ChoiceBenefitRequest": { "type": "object", "additionalProperties": false, "required": [ "externalCustomerId", "choiceSetId", "rewardId", "sourceReference" ], "properties": { "externalCustomerId": { "type": "string", "minLength": 1 }, "choiceSetId": { "type": "string", "minLength": 1 }, "rewardId": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 } } }, "ProgramManifest": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "program", "rules", "tiers", "rewards", "campaigns" ], "properties": { "schemaVersion": { "const": "loyumi.program/v1" }, "program": { "type": "object", "additionalProperties": false, "required": [ "name", "unitName", "currency", "timezone", "locale", "marketCode", "negativeBalancePolicy" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 200 }, "currency": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 200 }, "locale": { "type": "string", "minLength": 1, "maxLength": 200 }, "marketCode": { "type": "string", "minLength": 1, "maxLength": 200 }, "negativeBalancePolicy": { "type": "string", "enum": [ "block", "allow" ] } } }, "rules": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "pointsPerCurrencyUnit" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100 }, "eventType": { "type": "string", "minLength": 1, "maxLength": 200, "default": "purchase.completed" }, "pointsPerCurrencyUnit": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "pendingDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 0 }, "expirationDays": { "type": "integer", "minimum": 0, "maximum": 36500, "default": 365 }, "perMemberDailyCap": { "type": "integer", "minimum": 0, "default": 0 }, "definition": { "$ref": "#/components/schemas/EarnRuleDefinition", "default": {} } } } }, "tiers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "rank", "qualificationPoints" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "rank": { "type": "integer", "minimum": 1, "maximum": 1000 }, "qualificationPoints": { "type": "integer", "minimum": 0 }, "multiplierBps": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 10000 }, "downgradePolicy": { "type": "string", "minLength": 1, "maxLength": 200, "default": "scheduled" }, "graceDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 30 }, "qualificationWindowDays": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 365 }, "benefits": { "type": "object", "additionalProperties": true, "default": {} } } }, "maxItems": 16, "description": "At most 16 active tier definitions are supported in one program version." }, "rewards": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "description", "pointsCost", "inventory", "fulfillmentType", "giftable", "giftClaimWindowDays", "giftValidityDays" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "pointsCost": { "type": "integer", "minimum": 1 }, "inventory": { "type": "integer", "minimum": -1, "default": -1 }, "fulfillmentType": { "type": "string", "enum": [ "entitlement", "coupon", "external" ], "default": "external" }, "giftable": { "type": "boolean" }, "giftClaimWindowDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "giftValidityDays": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "allOf": [ { "if": { "properties": { "giftable": { "const": true } }, "required": [ "giftable" ] }, "then": { "properties": { "fulfillmentType": { "const": "entitlement" } } } } ] } }, "campaigns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "objective", "budgetPoints", "startsAt", "endsAt" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "objective": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100 }, "stackingPolicy": { "type": "string", "enum": [ "stack", "exclusive", "best_value" ], "default": "stack" }, "budgetPoints": { "type": "integer", "minimum": 1 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "audience": { "$ref": "#/components/schemas/CampaignAudience", "default": {} }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "conditionType": { "type": "string", "default": "minimum_spend" }, "minimumSpendMinor": { "type": "integer", "minimum": 0, "default": 0 }, "channel": { "type": [ "string", "null" ] }, "memberTier": { "type": [ "string", "null" ] }, "effectType": { "type": "string", "default": "bonus_points" }, "bonusPoints": { "type": "integer", "minimum": 0, "default": 0 }, "multiplierBps": { "type": "integer", "minimum": 1, "default": 10000 }, "maxAwardsPerMember": { "type": "integer", "minimum": 0, "default": 0 } } }, "default": [] } } } } } }, "WidgetPublishedDocument": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "id", "name", "revision", "updatedAt", "theme", "canvas", "blocks" ], "properties": { "schemaVersion": { "type": "integer", "const": 1 }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "updatedAt": { "type": "string", "format": "date-time" }, "theme": { "type": "object", "additionalProperties": false, "required": [ "accent", "background", "surface", "text", "radius", "font" ], "properties": { "accent": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "surface": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "text": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "radius": { "type": "integer", "minimum": 0, "maximum": 32 }, "font": { "type": "string", "enum": [ "system", "serif" ] } } }, "canvas": { "type": "object", "additionalProperties": false, "required": [ "maxWidth", "gap" ], "properties": { "maxWidth": { "type": "integer", "minimum": 320, "maximum": 1440 }, "gap": { "type": "integer", "minimum": 6, "maximum": 40 } } }, "blocks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "props", "visibility" ], "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "balance", "tier-progress", "reward-catalog", "activity" ] }, "props": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "visibility": { "type": "object", "additionalProperties": false, "required": [ "mobile", "desktop" ], "properties": { "mobile": { "type": "boolean" }, "desktop": { "type": "boolean" } } } } } } } }, "WidgetPublishedConfiguration": { "type": "object", "additionalProperties": false, "description": "Security and business configuration captured with every immutable widget version and restored atomically on rollback.", "required": [ "programId", "name", "allowedOrigins", "allowRedemption", "document" ], "properties": { "programId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "allowedOrigins": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "format": "uri", "pattern": "^https://[^/]+(?::[0-9]+)?$|^http://(?:localhost|127\\.0\\.0\\.1)(?::[0-9]+)?$" } }, "allowRedemption": { "type": "boolean" }, "document": { "$ref": "#/components/schemas/WidgetPublishedDocument" } } }, "WidgetSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "deploymentId", "externalCustomerId", "origin" ], "properties": { "deploymentId": { "type": "string", "minLength": 1, "description": "Published Widget Studio deployment ID.", "maxLength": 200 }, "externalCustomerId": { "type": "string", "minLength": 1, "description": "Customer ID from the merchant's authenticated server session.", "maxLength": 200 }, "origin": { "type": "string", "format": "uri", "pattern": "^https://[^/]+(?::[0-9]+)?$|^http://(?:localhost|127\\.0\\.0\\.1)(?::[0-9]+)?$", "description": "Exact merchant website origin configured on the widget deployment. Paths, queries, and fragments are rejected. HTTPS is required except for localhost development.", "maxLength": 2048 }, "permissions": { "type": "array", "minItems": 1, "uniqueItems": true, "default": [ "profile:read" ], "items": { "type": "string", "enum": [ "profile:read", "rewards:redeem" ] }, "description": "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." } } }, "WidgetSessionCodeResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "sessionCode", "expiresAt", "expiresIn", "runtimeMajor" ], "properties": { "requestId": { "type": "string" }, "sessionCode": { "type": "string", "pattern": "^wsc_[A-Za-z0-9_-]{43}$", "description": "Opaque, random, single-use handoff code. Return it only to the same authenticated browser request; never log or persist it. The hosted iframe exchanges it and the parent page never receives the signed session token.", "x-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "const": 60, "description": "Single-use code lifetime in seconds." }, "runtimeMajor": { "type": "integer", "const": 1, "description": "Compatible major version of the hosted widget runtime." } } }, "WidgetSessionExchangeRequest": { "type": "object", "additionalProperties": false, "required": [ "sessionCode", "deploymentId", "origin" ], "properties": { "sessionCode": { "type": "string", "pattern": "^wsc_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "deploymentId": { "type": "string", "minLength": 1 }, "origin": { "type": "string", "format": "uri", "description": "Exact merchant origin bound to the one-time code.", "maxLength": 2048 } } }, "WidgetSessionExchangeResponse": { "type": "object", "additionalProperties": false, "required": [ "requestId", "sessionToken", "expiresAt", "expiresIn", "runtimeMajor" ], "properties": { "requestId": { "type": "string" }, "sessionToken": { "type": "string", "minLength": 1, "description": "Signed session held only in the hosted iframe's memory. Never return it to or persist it in the merchant parent page." }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "const": 600 }, "runtimeMajor": { "type": "integer", "const": 1 } } }, "ProgramConfigurationSummary": { "type": "object", "additionalProperties": false, "required": [ "rules", "tiers", "rewards", "campaigns", "campaignRules" ], "properties": { "rules": { "type": "integer", "minimum": 0 }, "tiers": { "type": "integer", "minimum": 0 }, "rewards": { "type": "integer", "minimum": 0 }, "campaigns": { "type": "integer", "minimum": 0 }, "campaignRules": { "type": "integer", "minimum": 0 } } }, "CustomEventOutcome": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "requestId" ], "properties": { "id": { "type": "string" }, "status": { "const": "accepted" }, "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "awards": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "challengeId", "points", "transactionId" ], "properties": { "challengeId": { "type": "string" }, "points": { "type": "integer", "minimum": 0 }, "transactionId": { "type": "string" } } } } } }, "ChoiceBenefitOutcome": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "requestId" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "choice": { "type": "object", "additionalProperties": false, "required": [ "setId", "rewardId", "rewardName", "choicesRemaining" ], "properties": { "setId": { "type": "string" }, "rewardId": { "type": "string" }, "rewardName": { "type": "string" }, "choicesRemaining": { "type": "integer", "minimum": 0 } } } } }, "MemberCreateOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "member" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "member": { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "status" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": "string" }, "status": { "type": "string" }, "consentStatus": { "type": "string" } } } } }, "MemberDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "member", "programs" ], "properties": { "requestId": { "type": "string" }, "member": { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "displayName", "email", "phone", "status", "consentStatus", "createdAt" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "consentStatus": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "programs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "programId", "tier", "qualificationPoints", "balances" ], "properties": { "programId": { "type": "string" }, "tier": { "type": "string" }, "qualificationPoints": { "type": "integer", "minimum": 0 }, "balances": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "accountType", "available", "pending", "reserved" ], "properties": { "accountType": { "type": "string" }, "available": { "type": "integer" }, "pending": { "type": "integer" }, "reserved": { "type": "integer" } } } } } } } } }, "MemberUpdateOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "member" ], "properties": { "requestId": { "type": "string" }, "member": { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "displayName", "email", "phone", "status", "consentStatus", "updatedAt" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "consentStatus": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "MemberAnonymizationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "member", "retained" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "member": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "anonymized", "deletedAt" ], "properties": { "id": { "type": "string" }, "status": { "const": "deleted" }, "anonymized": { "const": true }, "deletedAt": { "type": "string", "format": "date-time" } } }, "retained": { "type": "string" } } }, "RedemptionQuoteOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "quote" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "quote": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "programId", "externalCustomerId", "rewardId", "points", "availableBalance", "sourceReference", "fulfillmentType", "expiresAt", "terms" ], "properties": { "id": { "type": "string" }, "state": { "const": "quoted" }, "programId": { "type": "string" }, "externalCustomerId": { "type": "string" }, "rewardId": { "type": [ "string", "null" ] }, "points": { "type": "integer", "minimum": 1 }, "availableBalance": { "type": "integer" }, "sourceReference": { "type": "string" }, "fulfillmentType": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "terms": { "type": "object", "additionalProperties": false, "required": [ "programVersion", "points", "reward", "ttlSeconds" ], "properties": { "programVersion": { "type": "integer", "minimum": 1 }, "points": { "type": "integer", "minimum": 1 }, "reward": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "id", "version", "name", "fulfillmentType", "finiteInventory" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "fulfillmentType": { "type": "string" }, "finiteInventory": { "type": "boolean" } } } ] }, "ttlSeconds": { "type": "integer", "minimum": 1 } } } } } } }, "RedemptionReservationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemption" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "redemption": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "state", "points", "rewardId", "expiresAt", "reserveTransactionId" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "state": { "const": "reserved" }, "points": { "type": "integer", "minimum": 1 }, "rewardId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "reserveTransactionId": { "type": "string" } } } } }, "RedemptionDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemption" ], "properties": { "requestId": { "type": "string" }, "redemption": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "programId", "memberId", "rewardId", "points", "state", "expiresAt", "transactions", "fulfillment", "disputes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": [ "string", "null" ] }, "programId": { "type": "string" }, "memberId": { "type": "string" }, "rewardId": { "type": [ "string", "null" ] }, "points": { "type": "integer", "minimum": 1 }, "state": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "transactions": { "type": "object", "additionalProperties": false, "required": [ "committed", "released", "reversed" ], "properties": { "committed": { "type": [ "string", "null" ] }, "released": { "type": [ "string", "null" ] }, "reversed": { "type": [ "string", "null" ] } } }, "fulfillment": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "id", "state", "provider", "reference", "lastError" ], "properties": { "id": { "type": "string" }, "state": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] } } } ] }, "disputes": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "reasonCode", "state", "createdAt", "resolvedAt" ], "properties": { "id": { "type": "string" }, "reasonCode": { "type": "string" }, "state": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "RedemptionCommitOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemption" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "redemption": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "points", "transactionId", "fulfillmentId", "fulfillmentState" ], "properties": { "id": { "type": "string" }, "state": { "const": "committed" }, "points": { "type": "integer", "minimum": 1 }, "transactionId": { "type": "string" }, "fulfillmentId": { "type": [ "string", "null" ] }, "fulfillmentState": { "type": [ "string", "null" ] } } } } }, "RedemptionReleaseOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemption" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "redemption": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "transactionId", "returnedPoints", "expiredPoints" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "released", "expired" ] }, "transactionId": { "type": "string" }, "returnedPoints": { "type": "integer", "minimum": 0 }, "expiredPoints": { "type": "integer", "minimum": 0 } } } } }, "RedemptionReverseOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemption" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "redemption": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "transactionId", "restoredPoints", "replacementLotPoints", "fulfillmentState" ], "properties": { "id": { "type": "string" }, "state": { "const": "reversed" }, "transactionId": { "type": "string" }, "restoredPoints": { "type": "integer", "minimum": 1 }, "replacementLotPoints": { "type": "integer", "minimum": 0 }, "fulfillmentState": { "type": [ "string", "null" ] } } } } }, "RedemptionCancelOutcome": { "oneOf": [ { "$ref": "#/components/schemas/RedemptionReleaseOutcome" }, { "$ref": "#/components/schemas/RedemptionReverseOutcome" } ], "description": "Cancel derives either a release for a reservation or a governed reversal for a committed, unfulfilled redemption." }, "RedemptionDisputeOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "dispute" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "dispute": { "type": "object", "additionalProperties": false, "required": [ "id", "subjectType", "subjectId", "state", "reasonCode", "createdAt", "evidence" ], "properties": { "id": { "type": "string" }, "subjectType": { "const": "redemption" }, "subjectId": { "type": "string" }, "state": { "const": "open" }, "reasonCode": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Inline JSON evidence metadata retained with the dispute; this is not external file storage." } } } } }, "RedemptionDisputeResolutionOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "dispute" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "dispute": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "resolution", "resolvedAt", "evidence" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "resolved", "rejected" ] }, "resolution": { "type": "string" }, "resolvedAt": { "type": "string", "format": "date-time" }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Inline JSON evidence metadata retained with the dispute; this is not external file storage." } } } } }, "RedemptionFulfillmentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "fulfillment" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "fulfillment": { "type": "object", "additionalProperties": false, "required": [ "id", "redemptionId", "state", "fulfillmentReference", "fulfillmentCancellationReference", "updatedAt" ], "properties": { "id": { "type": "string" }, "redemptionId": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "fulfilled", "failed", "cancelled" ] }, "fulfillmentReference": { "type": [ "string", "null" ] }, "fulfillmentCancellationReference": { "type": [ "string", "null" ], "description": "Recorded merchant or connector cancellation evidence, or null when no fulfilled-to-cancelled transition has been recorded." }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "AdjustmentRequestOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "adjustment" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "adjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "externalCustomerId", "direction", "points", "reasonCode", "state", "createdAt" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "externalCustomerId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "points": { "type": "integer", "minimum": 1 }, "reasonCode": { "type": "string" }, "state": { "const": "pending_approval" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "AdjustmentDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "adjustment" ], "properties": { "requestId": { "type": "string" }, "adjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "memberId", "direction", "points", "reasonCode", "description", "evidence", "approvalReference", "state", "transactionId", "reversalTransactionId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "memberId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "points": { "type": "integer", "minimum": 1 }, "reasonCode": { "type": "string" }, "description": { "type": "string" }, "evidence": { "type": "object", "additionalProperties": true }, "approvalReference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "transactionId": { "type": [ "string", "null" ] }, "reversalTransactionId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "AdjustmentPostOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "adjustment" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "adjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "transactionId", "approvalReference" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "posted", "reversed" ] }, "transactionId": { "type": "string" }, "approvalReference": { "type": "string" } } } } }, "AdjustmentRejectOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "adjustment" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "adjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "decisionNote" ], "properties": { "id": { "type": "string" }, "state": { "const": "rejected" }, "decisionNote": { "type": "string" } } } } }, "ProgramValidationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "valid", "checksum", "summary", "normalized", "warnings" ], "properties": { "requestId": { "type": "string" }, "valid": { "const": true }, "checksum": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" }, "normalized": { "$ref": "#/components/schemas/ProgramManifest" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "ProgramListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "programs" ], "properties": { "requestId": { "type": "string" }, "programs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "status", "currentVersion", "unitName", "currency", "timezone", "locale", "marketCode", "latestRevision", "updatedAt" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "currentVersion": { "type": "integer", "minimum": 1 }, "unitName": { "type": "string" }, "currency": { "type": "string" }, "timezone": { "type": "string" }, "locale": { "type": "string" }, "marketCode": { "type": "string" }, "latestRevision": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "programId", "version", "status", "checksum" ], "properties": { "programId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "checksum": { "type": "string" } } } ] }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "ProgramCreateOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "program", "revision" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "program": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "status", "currentVersion", "etag" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "const": "draft" }, "currentVersion": { "const": 1 }, "etag": { "type": "string" } } }, "revision": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "checksum", "summary" ], "properties": { "id": { "type": "string" }, "version": { "const": 1 }, "status": { "const": "draft" }, "checksum": { "type": "string" }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" } } } } }, "ProgramConfigurationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "program", "revision" ], "properties": { "requestId": { "type": "string" }, "program": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "currentVersion" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "currentVersion": { "type": "integer", "minimum": 1 } } }, "revision": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "checksum", "approvalReference", "publishedAt", "summary", "manifest" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "checksum": { "type": "string" }, "approvalReference": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" }, "manifest": { "$ref": "#/components/schemas/ProgramManifest" } } } } }, "ProgramRevisionListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "revisions" ], "properties": { "requestId": { "type": "string" }, "revisions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "checksum", "approvalReference", "summary", "createdAt", "publishedAt" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "checksum": { "type": "string" }, "approvalReference": { "type": [ "string", "null" ] }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" }, "createdAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "ProgramRevisionCreateOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "revision" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "revision": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "version", "status", "checksum", "etag", "impact" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "const": "draft" }, "checksum": { "type": "string" }, "etag": { "type": "string" }, "impact": { "type": "object", "additionalProperties": false, "required": [ "before", "after" ], "properties": { "before": { "$ref": "#/components/schemas/ProgramConfigurationSummary" }, "after": { "$ref": "#/components/schemas/ProgramConfigurationSummary" } } } } } } }, "ProgramPublishOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "program", "revision" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "program": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "currentVersion", "publishedAt" ], "properties": { "id": { "type": "string" }, "status": { "const": "published" }, "currentVersion": { "type": "integer", "minimum": 1 }, "publishedAt": { "type": "string", "format": "date-time" } } }, "revision": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "checksum", "approvalReference", "summary" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "const": "published" }, "checksum": { "type": "string" }, "approvalReference": { "type": "string" }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" } } } } }, "ProgramRestoreOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "revision" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "revision": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "version", "status", "restoredFromVersion", "checksum", "etag", "summary" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "const": "draft" }, "restoredFromVersion": { "type": "integer", "minimum": 1 }, "checksum": { "type": "string" }, "etag": { "type": "string" }, "summary": { "$ref": "#/components/schemas/ProgramConfigurationSummary" } } } } }, "PartnerAgreementProposalOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "agreement" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "agreement": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "termsHash", "counterparty", "endsAt" ], "properties": { "id": { "type": "string" }, "version": { "const": 1 }, "status": { "const": "proposed" }, "termsHash": { "type": "string" }, "counterparty": { "type": "string" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "PartnerAgreementAcceptanceOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "agreement" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "agreement": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "status", "termsHash", "effectiveAt" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "status": { "const": "active" }, "termsHash": { "type": "string" }, "effectiveAt": { "type": "string", "format": "date-time" } } } } }, "PartnerMemberTokenOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "memberToken", "agreementId", "expiresAt", "expiresIn", "notice" ], "properties": { "requestId": { "type": "string" }, "memberToken": { "type": "string", "minLength": 1 }, "agreementId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "const": 300 }, "notice": { "type": "string" } } }, "PartnerExchangeQuoteOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "quote" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "quote": { "type": "object", "additionalProperties": false, "required": [ "id", "agreementId", "state", "sourcePoints", "destinationPoints", "settlementMinor", "settlementCurrency", "sourceReference", "expiresAt", "terms", "confirmationFingerprint" ], "properties": { "id": { "type": "string" }, "agreementId": { "type": "string" }, "state": { "const": "quoted" }, "sourcePoints": { "type": "integer", "minimum": 1 }, "destinationPoints": { "type": "integer", "minimum": 1 }, "settlementMinor": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceReference": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "terms": { "type": "object", "additionalProperties": false, "required": [ "agreementId", "agreementVersion", "termsHash", "sourceRate", "destinationRate", "settlementMinorPerBlock", "settlementCurrency", "rounding", "destinationPointExpiration", "memberLink", "destinationPointExpirationPolicy", "confirmation", "customerDisclosure", "customerVerification" ], "properties": { "agreementId": { "type": "string" }, "agreementVersion": { "type": "integer", "minimum": 1 }, "termsHash": { "type": "string" }, "sourceRate": { "type": "integer", "minimum": 1 }, "destinationRate": { "type": "integer", "minimum": 1 }, "settlementMinorPerBlock": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "rounding": { "type": "object", "additionalProperties": false, "required": [ "destinationPoints", "settlementMinor" ], "properties": { "destinationPoints": { "const": "floor" }, "settlementMinor": { "const": "ceiling" } } }, "destinationPointExpiration": { "$ref": "#/components/schemas/PartnerDestinationPointExpiration" }, "memberLink": { "type": "object", "additionalProperties": false, "required": [ "verification", "sourceLinkChallengeId" ], "properties": { "verification": { "type": "string", "const": "source_challenge_destination_consent" }, "sourceLinkChallengeId": { "type": "string" } } }, "destinationPointExpirationPolicy": { "$ref": "#/components/schemas/PartnerDestinationPointExpirationPolicy" }, "confirmation": { "type": "object", "additionalProperties": false, "required": [ "required", "fingerprint", "algorithm", "nonce", "method" ], "properties": { "required": { "type": "boolean", "const": true }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "algorithm": { "type": "string", "const": "sha256-canonical-json" }, "nonce": { "type": "string", "pattern": "^pcn_[a-f0-9]{32}$" }, "method": { "type": "string", "const": "prelinked_verified_provider_approval_v1" } } }, "customerDisclosure": { "$ref": "#/components/schemas/PartnerExchangeCustomerDisclosure" }, "customerVerification": { "type": "object", "additionalProperties": false, "required": [ "version", "required", "method", "providers", "linkVersion", "bindingCommitment" ], "properties": { "version": { "type": "integer", "const": 1 }, "required": { "type": "boolean", "const": true }, "method": { "type": "string", "const": "verified_social_provider" }, "providers": { "type": "array", "prefixItems": [ { "type": "string", "const": "google" }, { "type": "string", "const": "apple" } ], "minItems": 2, "maxItems": 2 }, "linkVersion": { "type": "integer", "const": 1 }, "bindingCommitment": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "description": "Quote-specific opaque commitment to the active customer-verification link. It is stripped from participant portability exports and is not a reusable identity proof." } } }, "confirmationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact customer-facing quote fingerprint required by the reserve confirmation." } } } } }, "PartnerExchangeReservationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "agreementId", "state", "sourcePoints", "destinationPoints", "settlementMinor", "settlementCurrency", "sourceReference", "expiresAt" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "agreementId": { "type": "string" }, "state": { "const": "reserved" }, "sourcePoints": { "type": "integer", "minimum": 1 }, "destinationPoints": { "type": "integer", "minimum": 1 }, "settlementMinor": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceReference": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "PartnerExchangeDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "agreementId", "state", "sourcePoints", "destinationPoints", "settlementMinor", "settlementCurrency", "sourceReference", "agreementVersion", "expiresAt", "sourceTransactionId", "destinationTransactionId", "sourceReversalTransactionId", "destinationReversalTransactionId", "settlementReference", "settlementReversalReference", "committedAt", "releasedAt", "settledAt", "reversedAt", "createdAt", "updatedAt", "consistency", "participantRole", "returnedSourcePoints", "expiredSourcePoints" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "agreementId": { "type": "string" }, "state": { "type": "string" }, "sourcePoints": { "type": "integer", "minimum": 1 }, "destinationPoints": { "type": "integer", "minimum": 1 }, "settlementMinor": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceReference": { "type": [ "string", "null" ], "description": "Source merchant business reference for source-participant reads; always null for destination-participant reads to prevent customer-reference disclosure." }, "agreementVersion": { "type": "integer", "minimum": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "sourceTransactionId": { "type": [ "string", "null" ], "description": "Source-ledger identifier returned only to the source participant; null for the destination participant." }, "destinationTransactionId": { "type": [ "string", "null" ], "description": "Destination-ledger identifier returned only to the destination participant; null for the source participant." }, "sourceReversalTransactionId": { "type": [ "string", "null" ], "description": "Source-ledger identifier returned only to the source participant; null for the destination participant." }, "destinationReversalTransactionId": { "type": [ "string", "null" ], "description": "Destination-ledger identifier returned only to the destination participant; null for the source participant." }, "settlementReference": { "type": [ "string", "null" ] }, "settlementReversalReference": { "type": [ "string", "null" ] }, "committedAt": { "type": [ "string", "null" ], "format": "date-time" }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time" }, "settledAt": { "type": [ "string", "null" ], "format": "date-time" }, "reversedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "consistency": { "type": "string", "enum": [ "reconciled", "attention_required" ] }, "confirmationFingerprint": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$", "description": "Exact quote fingerprint recorded with customer confirmation; null only for legacy exchanges." }, "confirmationReference": { "type": [ "string", "null" ], "description": "Source merchant confirmation evidence reference; null for destination-participant and legacy reads." }, "customerConfirmedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Customer confirmation instant; null only for legacy exchanges." }, "participantRole": { "type": "string", "enum": [ "source", "destination" ] }, "returnedSourcePoints": { "type": [ "integer", "null" ], "minimum": 0, "description": "Authoritative source points returned after release/expiry; null when no return evidence applies or evidence needs attention." }, "expiredSourcePoints": { "type": [ "integer", "null" ], "minimum": 0, "description": "Source points that expired under source-program rules while reserved; null when no return evidence applies or evidence needs attention." } } } } }, "PartnerExchangeCommitOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "sourcePoints", "destinationPoints", "settlementMinor", "settlementCurrency", "sourceTransactionId", "destinationTransactionId", "committedAt" ], "properties": { "id": { "type": "string" }, "state": { "const": "committed" }, "sourcePoints": { "type": "integer", "minimum": 1 }, "destinationPoints": { "type": "integer", "minimum": 1 }, "settlementMinor": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceTransactionId": { "type": "string" }, "destinationTransactionId": { "type": "string" }, "committedAt": { "type": "string", "format": "date-time" } } } } }, "PartnerExchangeReleaseOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "returnedSourcePoints", "expiredSourcePoints", "transactionId", "releaseReason" ], "properties": { "id": { "type": "string" }, "state": { "const": "released" }, "returnedSourcePoints": { "type": "integer", "minimum": 0 }, "expiredSourcePoints": { "type": "integer", "minimum": 0 }, "transactionId": { "type": "string" }, "releaseReason": { "type": "string" } } } } }, "PartnerExchangeSettlementOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "settlementMinor", "settlementCurrency", "settlementReference", "settledAt" ], "properties": { "id": { "type": "string" }, "state": { "const": "settled" }, "settlementMinor": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "settlementReference": { "type": "string" }, "settledAt": { "type": "string", "format": "date-time" } } } } }, "PartnerExchangeReverseOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchange" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean", "description": "Present and true when this is a replay of the original response for the same idempotency identity and payload." }, "exchange": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "restoredSourcePoints", "removedDestinationPoints", "replacementLotPoints", "sourceReversalTransactionId", "destinationReversalTransactionId", "settlementReversalReference", "reversedAt" ], "properties": { "id": { "type": "string" }, "state": { "const": "reversed" }, "restoredSourcePoints": { "type": "integer", "minimum": 1 }, "removedDestinationPoints": { "type": "integer", "minimum": 1 }, "replacementLotPoints": { "type": "integer", "minimum": 0 }, "sourceReversalTransactionId": { "type": "string" }, "destinationReversalTransactionId": { "type": "string" }, "settlementReversalReference": { "type": [ "string", "null" ] }, "reversedAt": { "type": "string", "format": "date-time" } } } } }, "CursorPage": { "type": "object", "additionalProperties": false, "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } }, "MemberListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "externalCustomerId", "displayName", "email", "status", "consentStatus", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "externalCustomerId": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "status": { "type": "string" }, "consentStatus": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "MemberListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "members", "page" ], "properties": { "requestId": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MemberListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "TransactionListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "eventType", "sourceReference", "ruleVersion", "state", "reversesTransactionId", "postedAt" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "eventType": { "type": "string" }, "sourceReference": { "type": [ "string", "null" ] }, "ruleVersion": { "type": [ "integer", "null" ] }, "state": { "type": "string" }, "reversesTransactionId": { "type": [ "string", "null" ] }, "postedAt": { "type": "string", "format": "date-time" } } }, "TransactionListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "transactions", "page" ], "properties": { "requestId": { "type": "string" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "LedgerEntryDetail": { "type": "object", "additionalProperties": false, "required": [ "id", "accountId", "accountType", "memberId", "externalCustomerId", "direction", "amount", "lotId", "availableAt", "expiresAt", "createdAt" ], "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "accountType": { "type": "string" }, "memberId": { "type": [ "string", "null" ] }, "externalCustomerId": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "integer", "minimum": 1 }, "lotId": { "type": [ "string", "null" ] }, "availableAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "TransactionDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "transaction" ], "properties": { "requestId": { "type": "string" }, "transaction": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "eventType", "sourceReference", "ruleVersion", "state", "reversesTransactionId", "metadata", "postedAt", "createdAt", "entries" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "eventType": { "type": "string" }, "sourceReference": { "type": [ "string", "null" ] }, "ruleVersion": { "type": [ "integer", "null" ] }, "state": { "type": "string" }, "reversesTransactionId": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "postedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntryDetail" } } } } } }, "RedemptionListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "programId", "memberId", "rewardId", "points", "state", "sourceReference", "expiresAt", "fulfillmentId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": [ "string", "null" ] }, "programId": { "type": "string" }, "memberId": { "type": "string" }, "rewardId": { "type": [ "string", "null" ] }, "points": { "type": "integer", "minimum": 1 }, "state": { "type": "string" }, "sourceReference": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "fulfillmentId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RedemptionListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "redemptions", "page" ], "properties": { "requestId": { "type": "string" }, "redemptions": { "type": "array", "items": { "$ref": "#/components/schemas/RedemptionListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "AdjustmentListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "programId", "memberId", "direction", "points", "reasonCode", "description", "state", "approvalReference", "transactionId", "reversalTransactionId", "decidedAt", "postedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "programId": { "type": "string" }, "memberId": { "type": "string" }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "points": { "type": "integer", "minimum": 1 }, "reasonCode": { "type": "string" }, "description": { "type": "string" }, "state": { "type": "string" }, "approvalReference": { "type": [ "string", "null" ] }, "transactionId": { "type": [ "string", "null" ] }, "reversalTransactionId": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "postedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AdjustmentListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "adjustments", "page" ], "properties": { "requestId": { "type": "string" }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/AdjustmentListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "ImportListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "operationId", "programId", "schemaVersion", "checksum", "status", "totalRows", "validRows", "exceptionRows", "totalPoints", "appliedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "operationId": { "type": "string" }, "programId": { "type": "string" }, "schemaVersion": { "type": "string" }, "checksum": { "type": "string" }, "status": { "type": "string" }, "totalRows": { "type": "integer", "minimum": 0 }, "validRows": { "type": "integer", "minimum": 0 }, "exceptionRows": { "type": "integer", "minimum": 0 }, "totalPoints": { "type": "integer", "minimum": 0 }, "appliedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ImportListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "imports", "page" ], "properties": { "requestId": { "type": "string" }, "imports": { "type": "array", "items": { "$ref": "#/components/schemas/ImportListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "OperationItem": { "type": "object", "additionalProperties": false, "required": [ "id", "organizationId", "environmentId", "type", "status", "name", "summary", "recordCount", "exceptionCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "environmentId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "recordCount": { "type": "integer", "minimum": 0 }, "exceptionCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OperationListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "operations", "page" ], "properties": { "requestId": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "OperationDetailOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "operation" ], "properties": { "requestId": { "type": "string" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/OperationItem" }, { "type": "object", "required": [ "import" ], "properties": { "import": { "anyOf": [ { "$ref": "#/components/schemas/ImportListItem" }, { "type": "null" } ] } } } ] } } }, "AuditEventItem": { "type": "object", "additionalProperties": false, "required": [ "id", "organizationId", "actorId", "action", "targetType", "targetId", "metadata", "createdAt" ], "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "actorId": { "type": "string" }, "action": { "type": "string" }, "targetType": { "type": "string" }, "targetId": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "AuditEventListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "auditEvents", "page" ], "properties": { "requestId": { "type": "string" }, "auditEvents": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEventItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "LedgerAnalyticsOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "asOf", "window", "programId", "consistency", "membersCreatedByStatus", "transactions", "memberAvailableMovements", "currentMemberBalances", "redemptionsByState", "webhookDeliveriesByStatus" ], "properties": { "requestId": { "type": "string" }, "asOf": { "type": "string", "format": "date-time" }, "window": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "maximumDays" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "maximumDays": { "type": "integer", "const": 90 } } }, "programId": { "type": [ "string", "null" ] }, "consistency": { "type": "object", "additionalProperties": false, "required": [ "model", "financialCloseReport", "description" ], "properties": { "model": { "type": "string", "const": "best_effort_request_view" }, "financialCloseReport": { "type": "boolean", "const": false }, "description": { "type": "string" } } }, "membersCreatedByStatus": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "transactions": { "type": "object", "additionalProperties": false, "required": [ "posted", "reversed" ], "properties": { "posted": { "type": "integer", "minimum": 0 }, "reversed": { "type": "integer", "minimum": 0, "description": "Transactions with reversal lineage (a compensating transaction, including release or expiry compensation) plus legacy transactions whose state is reversed. Each transaction is counted once." } } }, "memberAvailableMovements": { "type": "object", "additionalProperties": false, "required": [ "credits", "debits", "net" ], "properties": { "credits": { "type": "integer", "minimum": 0 }, "debits": { "type": "integer", "minimum": 0 }, "net": { "type": "integer" } } }, "currentMemberBalances": { "type": "object", "additionalProperties": false, "required": [ "available", "pending", "reserved" ], "properties": { "available": { "type": "integer", "minimum": 0 }, "pending": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 } } }, "redemptionsByState": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "webhookDeliveriesByStatus": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Environment-wide operational delivery counts. These remain environment-wide when programId filters the ledger, member, balance, and redemption metrics." } } }, "WebhookEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "url", "eventTypes", "status", "signingSecretVersion", "lastDeliveryAt", "failureCount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "points.earned", "member.enrolled", "member.unenrolled", "program.published", "redemption.reserved", "redemption.committed", "redemption.released", "redemption.expired", "redemption.reversed", "redemption.fulfillment.updated", "redemption.dispute.opened", "redemption.dispute.resolved", "redemption.dispute.rejected", "reward_gift.reserved", "reward_gift.accepted", "reward_gift.declined", "reward_gift.cancelled", "reward_gift.expired", "reward_gift.reversed", "reward_gift.fulfillment.updated", "reward_gift.dispute.opened", "reward_gift.dispute.resolved", "reward_gift.dispute.rejected", "adjustment.requested", "adjustment.rejected", "adjustment.posted", "adjustment.reversed", "import.completed", "partner_exchange.committed", "partner_exchange.released", "partner_exchange.expired", "partner_exchange.settled", "partner_exchange.reversed", "reward_gift.invitation.created", "reward_gift.invitation.readiness.updated", "reward_gift.invitation.delivery.scheduled", "reward_gift.invitation.delivery.updated", "reward_gift.entitlement.available", "reward_gift.entitlement.used", "reward_gift.entitlement.expired" ] } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "signingSecretVersion": { "type": "integer", "minimum": 1 }, "lastDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookEndpointListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "webhookEndpoints", "page" ], "properties": { "requestId": { "type": "string" }, "webhookEndpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "WebhookEndpointOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "endpoint" ], "properties": { "requestId": { "type": "string" }, "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "signingSecret": { "type": "string", "writeOnly": true }, "signingSecretAvailable": { "type": "boolean" }, "notice": { "type": "string" }, "idempotent": { "type": "boolean" } } }, "WebhookEndpointCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "url", "eventTypes" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "points.earned", "member.enrolled", "member.unenrolled", "program.published", "redemption.reserved", "redemption.committed", "redemption.released", "redemption.expired", "redemption.reversed", "redemption.fulfillment.updated", "redemption.dispute.opened", "redemption.dispute.resolved", "redemption.dispute.rejected", "reward_gift.reserved", "reward_gift.accepted", "reward_gift.declined", "reward_gift.cancelled", "reward_gift.expired", "reward_gift.reversed", "reward_gift.fulfillment.updated", "reward_gift.dispute.opened", "reward_gift.dispute.resolved", "reward_gift.dispute.rejected", "adjustment.requested", "adjustment.rejected", "adjustment.posted", "adjustment.reversed", "import.completed", "partner_exchange.committed", "partner_exchange.released", "partner_exchange.expired", "partner_exchange.settled", "partner_exchange.reversed", "reward_gift.invitation.created", "reward_gift.invitation.readiness.updated", "reward_gift.invitation.delivery.scheduled", "reward_gift.invitation.delivery.updated", "reward_gift.entitlement.available", "reward_gift.entitlement.used", "reward_gift.entitlement.expired" ] }, "minItems": 1, "maxItems": 33, "uniqueItems": true } } }, "WebhookEndpointUpdateRequest": { "type": "object", "additionalProperties": false, "required": [], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "points.earned", "member.enrolled", "member.unenrolled", "program.published", "redemption.reserved", "redemption.committed", "redemption.released", "redemption.expired", "redemption.reversed", "redemption.fulfillment.updated", "redemption.dispute.opened", "redemption.dispute.resolved", "redemption.dispute.rejected", "reward_gift.reserved", "reward_gift.accepted", "reward_gift.declined", "reward_gift.cancelled", "reward_gift.expired", "reward_gift.reversed", "reward_gift.fulfillment.updated", "reward_gift.dispute.opened", "reward_gift.dispute.resolved", "reward_gift.dispute.rejected", "adjustment.requested", "adjustment.rejected", "adjustment.posted", "adjustment.reversed", "import.completed", "partner_exchange.committed", "partner_exchange.released", "partner_exchange.expired", "partner_exchange.settled", "partner_exchange.reversed", "reward_gift.invitation.created", "reward_gift.invitation.readiness.updated", "reward_gift.invitation.delivery.scheduled", "reward_gift.invitation.delivery.updated", "reward_gift.entitlement.available", "reward_gift.entitlement.used", "reward_gift.entitlement.expired" ] }, "minItems": 1, "maxItems": 33, "uniqueItems": true }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "minProperties": 1 }, "EmptyCommand": { "type": "object", "additionalProperties": false, "required": [], "properties": {}, "maxProperties": 0 }, "WebhookDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "endpointId", "eventType", "eventId", "status", "attemptCount", "responseCode", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventType": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "failed", "delivered", "dead_letter" ] }, "attemptCount": { "type": "integer", "minimum": 0 }, "responseCode": { "type": [ "integer", "null" ], "minimum": 100, "maximum": 599 }, "lastError": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "webhookDeliveries", "page" ], "properties": { "requestId": { "type": "string" }, "webhookDeliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "WebhookDeliveryOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "delivery" ], "properties": { "requestId": { "type": "string" }, "delivery": { "$ref": "#/components/schemas/WebhookDelivery" }, "notice": { "type": "string" }, "idempotent": { "type": "boolean" } } }, "ProgramManifestInput": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "program", "rules" ], "properties": { "schemaVersion": { "const": "loyumi.program/v1" }, "program": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 200, "default": "points" }, "currency": { "type": "string", "minLength": 1, "maxLength": 200, "default": "USD" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 200, "default": "UTC" }, "locale": { "type": "string", "minLength": 1, "maxLength": 200, "default": "en-US" }, "marketCode": { "type": "string", "minLength": 1, "maxLength": 200, "default": "GLOBAL" }, "negativeBalancePolicy": { "type": "string", "enum": [ "block", "allow" ], "default": "block" } } }, "rules": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "pointsPerCurrencyUnit" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100 }, "eventType": { "type": "string", "minLength": 1, "maxLength": 200, "default": "purchase.completed" }, "pointsPerCurrencyUnit": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "pendingDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 0 }, "expirationDays": { "type": "integer", "minimum": 0, "maximum": 36500, "default": 365 }, "perMemberDailyCap": { "type": "integer", "minimum": 0, "default": 0 }, "definition": { "$ref": "#/components/schemas/EarnRuleDefinition", "default": {} } } } }, "tiers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "rank", "qualificationPoints" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "rank": { "type": "integer", "minimum": 1, "maximum": 1000 }, "qualificationPoints": { "type": "integer", "minimum": 0 }, "multiplierBps": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 10000 }, "downgradePolicy": { "type": "string", "minLength": 1, "maxLength": 200, "default": "scheduled" }, "graceDays": { "type": "integer", "minimum": 0, "maximum": 3650, "default": 30 }, "qualificationWindowDays": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 365 }, "benefits": { "type": "object", "additionalProperties": true, "default": {} } } }, "maxItems": 16, "description": "At most 16 active tier definitions are supported in one program version.", "default": [] }, "rewards": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "description", "pointsCost" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "pointsCost": { "type": "integer", "minimum": 1 }, "inventory": { "type": "integer", "minimum": -1, "default": -1 }, "fulfillmentType": { "type": "string", "enum": [ "entitlement", "coupon", "external" ], "default": "external" }, "giftable": { "type": "boolean" }, "giftClaimWindowDays": { "type": "integer", "minimum": 1, "maximum": 30 }, "giftValidityDays": { "type": "integer", "minimum": 1, "maximum": 3650 } }, "allOf": [ { "if": { "properties": { "giftable": { "const": true } }, "required": [ "giftable" ] }, "then": { "properties": { "fulfillmentType": { "const": "entitlement" } } } } ] }, "default": [] }, "campaigns": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key", "name", "objective", "budgetPoints", "startsAt", "endsAt" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "objective": { "type": "string", "minLength": 1, "maxLength": 200 }, "priority": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 100 }, "stackingPolicy": { "type": "string", "enum": [ "stack", "exclusive", "best_value" ], "default": "stack" }, "budgetPoints": { "type": "integer", "minimum": 1 }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "audience": { "$ref": "#/components/schemas/CampaignAudience", "default": {} }, "rules": { "type": "array", "items": { "type": "object", "additionalProperties": true, "required": [ "key" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9._-]{1,63}$" }, "conditionType": { "type": "string", "default": "minimum_spend" }, "minimumSpendMinor": { "type": "integer", "minimum": 0, "default": 0 }, "channel": { "type": [ "string", "null" ] }, "memberTier": { "type": [ "string", "null" ] }, "effectType": { "type": "string", "default": "bonus_points" }, "bonusPoints": { "type": "integer", "minimum": 0, "default": 0 }, "multiplierBps": { "type": "integer", "minimum": 1, "default": 10000 }, "maxAwardsPerMember": { "type": "integer", "minimum": 0, "default": 0 } } }, "default": [] } } }, "default": [] } } }, "MemberProgramEnrollmentRequest": { "type": "object", "additionalProperties": false, "required": [ "consentStatus", "noticeVersion", "evidence" ], "properties": { "consentStatus": { "type": "string", "const": "opted_in" }, "noticeVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Merchant-controlled consent or withdrawal evidence. Do not place secrets in this object." } } }, "MemberProgramUnenrollmentRequest": { "type": "object", "additionalProperties": false, "required": [ "reason", "evidence" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Merchant-controlled consent or withdrawal evidence. Do not place secrets in this object." }, "noticeVersion": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "MemberProgramEnrollmentReceipt": { "type": "object", "additionalProperties": false, "required": [ "consentEventId", "auditEventId", "recordedAt" ], "properties": { "consentEventId": { "type": "string" }, "auditEventId": { "type": "string" }, "recordedAt": { "type": "string", "format": "date-time" } } }, "MemberProgramEnrollmentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "enrollment", "receipt" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "enrollment": { "type": "object", "additionalProperties": false, "required": [ "externalCustomerId", "programId", "profileId", "accountId", "state", "consentStatus", "createdProfile", "createdAccount", "createdAt" ], "properties": { "externalCustomerId": { "type": "string" }, "programId": { "type": "string" }, "profileId": { "type": "string" }, "accountId": { "type": "string" }, "state": { "type": "string", "const": "active" }, "consentStatus": { "type": "string", "const": "opted_in" }, "createdProfile": { "type": "boolean" }, "createdAccount": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "receipt": { "$ref": "#/components/schemas/MemberProgramEnrollmentReceipt" } } }, "MemberProgramUnenrollmentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "enrollment", "receipt" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "enrollment": { "type": "object", "additionalProperties": false, "required": [ "externalCustomerId", "programId", "profileId", "state", "removedAt", "cleanup" ], "properties": { "externalCustomerId": { "type": "string" }, "programId": { "type": "string" }, "profileId": { "type": [ "string", "null" ] }, "state": { "type": "string", "const": "unenrolled" }, "removedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cleanup": { "type": "object", "additionalProperties": false, "required": [ "availableChoiceAwards", "quotedRedemptionQuotes" ], "properties": { "availableChoiceAwards": { "type": "string", "const": "expired" }, "quotedRedemptionQuotes": { "type": "string", "const": "cancelled" } } } } }, "receipt": { "anyOf": [ { "$ref": "#/components/schemas/MemberProgramEnrollmentReceipt" }, { "type": "null" } ] } } }, "LedgerCloseMovement": { "type": "object", "additionalProperties": false, "required": [ "eventType", "transactions", "creditPoints", "debitPoints", "netPoints" ], "properties": { "eventType": { "type": "string" }, "transactions": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "creditPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "debitPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "netPoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." } } }, "LedgerCloseRollforward": { "type": "object", "additionalProperties": false, "required": [ "openingOutstandingPoints", "creditsPoints", "debitsPoints", "netMovementPoints", "closingOutstandingPoints" ], "properties": { "openingOutstandingPoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "creditsPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "debitsPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "netMovementPoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "closingOutstandingPoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." } } }, "LedgerCloseControls": { "type": "object", "additionalProperties": false, "required": [ "status", "memberRollForwardDifferencePoints", "doubleEntryDebitPoints", "doubleEntryCreditPoints", "doubleEntryDifferencePoints" ], "properties": { "status": { "type": "string", "enum": [ "pass", "fail" ] }, "memberRollForwardDifferencePoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "doubleEntryDebitPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "doubleEntryCreditPoints": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "doubleEntryDifferencePoints": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." } } }, "LedgerCloseValuationAmounts": { "type": "object", "additionalProperties": false, "required": [ "openingLiabilityMicros", "movementLiabilityMicros", "closingLiabilityMicros" ], "properties": { "openingLiabilityMicros": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "movementLiabilityMicros": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "closingLiabilityMicros": { "type": "string", "pattern": "^-?[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." } } }, "LedgerCloseFinancePolicy": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "pointValueMicros", "expectedRedemptionBps", "breakageBps", "assumptionsComplementary", "journalMapping", "approvedBy", "approvedAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "pointValueMicros": { "type": "string", "pattern": "^[0-9]+$", "description": "An exact base-10 integer string. It is a string to preserve D1 64-bit integer precision across JSON runtimes." }, "expectedRedemptionBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "breakageBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "assumptionsComplementary": { "type": "boolean" }, "journalMapping": { "type": "object", "additionalProperties": true, "description": "Merchant-approved general-ledger account mapping snapshot." }, "approvedBy": { "type": [ "string", "null" ] }, "approvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "LedgerCloseEvidence": { "type": "object", "additionalProperties": false, "required": [ "version", "organizationId", "environmentId", "program", "window", "basis", "closeStatus", "rollforward", "movementsByEventType", "controls", "valuation", "readiness" ], "properties": { "version": { "type": "string", "const": "ledger-close.v1" }, "organizationId": { "type": "string" }, "environmentId": { "type": "string" }, "program": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "currency", "unitName", "configurationVersion" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "unitName": { "type": "string" }, "configurationVersion": { "type": "integer", "minimum": 1 } } }, "window": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "semantics" ], "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "semantics": { "type": "string", "const": "[from,to)" } } }, "basis": { "type": "object", "additionalProperties": false, "required": [ "cutoffField", "accountScope", "arithmetic", "valuationUnit", "valuationRounding" ], "properties": { "cutoffField": { "type": "string", "const": "ledger_transactions.posted_at" }, "accountScope": { "type": "string", "const": "member_*" }, "arithmetic": { "type": "string", "const": "exact_decimal_strings" }, "valuationUnit": { "type": "string", "const": "merchant_currency_micros" }, "valuationRounding": { "type": "string", "const": "floor_to_microunit" } } }, "closeStatus": { "type": "string", "enum": [ "points_only", "provisional", "ready_for_external_review", "control_exception" ] }, "rollforward": { "$ref": "#/components/schemas/LedgerCloseRollforward" }, "movementsByEventType": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerCloseMovement" } }, "controls": { "$ref": "#/components/schemas/LedgerCloseControls" }, "valuation": { "type": "object", "additionalProperties": false, "required": [ "status", "policy", "amounts" ], "properties": { "status": { "type": "string", "enum": [ "not_configured", "provisional_policy", "approved_policy" ] }, "policy": { "anyOf": [ { "$ref": "#/components/schemas/LedgerCloseFinancePolicy" }, { "type": "null" } ] }, "amounts": { "anyOf": [ { "$ref": "#/components/schemas/LedgerCloseValuationAmounts" }, { "type": "null" } ] } } }, "readiness": { "type": "object", "additionalProperties": false, "required": [ "ledgerControlsPass", "financePolicyConfigured", "financePolicyApproved", "journalMappingComplete", "assumptionsComplementary" ], "properties": { "ledgerControlsPass": { "type": "boolean" }, "financePolicyConfigured": { "type": "boolean" }, "financePolicyApproved": { "type": "boolean" }, "journalMappingComplete": { "type": "boolean" }, "assumptionsComplementary": { "type": [ "boolean", "null" ] } } } } }, "LedgerCloseReportOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "reportId", "generatedAt", "integrity", "evidence", "assurance" ], "properties": { "requestId": { "type": "string" }, "reportId": { "type": "string", "pattern": "^lcr_[a-f0-9]{24}$" }, "generatedAt": { "type": "string", "format": "date-time" }, "integrity": { "type": "object", "additionalProperties": false, "required": [ "algorithm", "canonicalPayload", "hash" ], "properties": { "algorithm": { "type": "string", "const": "SHA-256" }, "canonicalPayload": { "type": "string", "const": "evidence" }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "evidence": { "$ref": "#/components/schemas/LedgerCloseEvidence" }, "assurance": { "type": "object", "additionalProperties": false, "required": [ "systemGenerated", "independentlyAudited", "contractualFinancialStatement", "notice" ], "properties": { "systemGenerated": { "type": "boolean", "const": true }, "independentlyAudited": { "type": "boolean", "const": false }, "contractualFinancialStatement": { "type": "boolean", "const": false }, "notice": { "type": "string" } } } } }, "PurchaseEvaluationPolicy": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "const": "receipt_time_current_configuration", "default": "receipt_time_current_configuration" }, "configurationVersion": { "type": "integer", "minimum": 1, "description": "Optional integrity assertion. When supplied it must equal the current published configuration version." } } }, { "type": "object", "additionalProperties": false, "required": [ "mode", "configurationVersion", "memberTier" ], "properties": { "mode": { "type": "string", "const": "event_time_pinned_configuration" }, "configurationVersion": { "type": "integer", "minimum": 1 }, "memberTier": { "type": "string", "minLength": 1, "maxLength": 200 } } } ], "description": "Selects receipt-time current-configuration evaluation, or explicitly pins a late event to the immutable configuration and member tier that were valid at occurredAt. event_time_pinned_configuration also requires PurchaseRequest.occurredAt (top-level or in context)." }, "PurchaseAttributes": { "type": "object", "additionalProperties": true, "properties": { "loyumiEvaluation": { "$ref": "#/components/schemas/PurchaseEvaluationPolicy" } }, "description": "Merchant-defined, non-secret decision context. loyumiEvaluation is reserved for Loyumi's explicit evaluation-clock policy." }, "PurchaseNestedContext": { "type": "object", "additionalProperties": true, "properties": { "attributes": { "$ref": "#/components/schemas/PurchaseAttributes" } }, "description": "Nested commerce and decision context. Top-level commerce fields take precedence, except context.attributes is authoritative when it is present." }, "EarnRuleCondition": { "type": "object", "additionalProperties": false, "required": [ "field", "value" ], "properties": { "field": { "anyOf": [ { "type": "string", "enum": [ "eventType", "amountMinor", "eligibleAmountMinor", "channel", "currency", "memberTier", "market", "locale", "storeId", "orderType", "deviceType", "customerTag", "sku", "category" ] }, { "type": "string", "pattern": "^attribute\\.[A-Za-z0-9_.-]{1,200}$" } ] }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "in", "not_in", "gte", "lte", "contains" ], "default": "equals" }, "value": { "oneOf": [ { "type": [ "string", "integer", "boolean", "null" ] }, { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": [ "string", "integer", "boolean" ] } } ], "description": "Use an array for in/not_in, an integer for gte/lte, and a string for contains." } }, "allOf": [ { "if": { "properties": { "operator": { "enum": [ "in", "not_in" ] } }, "required": [ "operator" ] }, "then": { "properties": { "value": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": [ "string", "integer", "boolean" ] } } } } }, { "if": { "properties": { "operator": { "enum": [ "gte", "lte" ] } }, "required": [ "operator" ] }, "then": { "properties": { "value": { "type": "integer" } } } }, { "if": { "properties": { "operator": { "const": "contains" } }, "required": [ "operator" ] }, "then": { "properties": { "value": { "type": "string" } } } } ] }, "EarnCalculationOptions": { "type": "object", "additionalProperties": false, "required": [], "properties": { "currencyExponent": { "type": "integer", "minimum": 0, "maximum": 9 }, "loyaltyUnitPrecision": { "type": "integer", "minimum": 0, "maximum": 9, "default": 0 }, "rateNumerator": { "type": "integer", "minimum": 1 }, "rateDenominator": { "type": "integer", "minimum": 1, "default": 1 }, "rounding": { "type": "string", "enum": [ "floor", "ceil", "nearest_half_up", "nearest_half_even" ], "default": "floor" }, "tierRounding": { "type": "string", "enum": [ "floor", "ceil", "nearest_half_up", "nearest_half_even" ], "default": "floor" } } }, "EarnRuleDefinition": { "type": "object", "additionalProperties": true, "properties": { "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/EarnRuleCondition" }, "maxItems": 100 }, "earn": { "$ref": "#/components/schemas/EarnCalculationOptions" } } }, "CampaignAudience": { "type": "object", "additionalProperties": false, "required": [], "properties": { "tier": { "type": "string", "minLength": 1, "maxLength": 200 }, "memberTier": { "type": "string", "minLength": 1, "maxLength": 200 }, "memberTiers": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "channels": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "enum": [ "web", "store", "app", "partner", "marketplace", "call_center" ] }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200, "enum": [ "web", "store", "app", "partner", "marketplace", "call_center" ] }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "markets": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "locales": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "storeIds": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "customerTagsAny": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "customerTagsAll": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "memberIds": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "externalCustomerIds": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 100 } ], "description": "Accepts one value or an array of values." }, "attributes": { "type": "object", "additionalProperties": true } } }, "EarnRuleDecision": { "type": "object", "additionalProperties": false, "required": [ "ruleId", "name", "priority", "matched", "selected", "reason" ], "properties": { "ruleId": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "integer" }, "matched": { "type": "boolean" }, "selected": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "selected", "lower_priority_match", "event_type_not_matched", "conditions_not_met" ] }, { "type": "string", "pattern": "^invalid_definition(?:: .+)?$" } ] } } }, "CampaignRuleDecision": { "type": "object", "additionalProperties": false, "required": [ "ruleId", "applied", "award", "reason" ], "properties": { "ruleId": { "type": "string" }, "applied": { "type": "boolean" }, "award": { "type": "integer", "minimum": 0 }, "reason": { "type": "string", "enum": [ "matched", "conditions_not_met", "award_limit_reached", "audience_not_matched", "zero_award" ] } } }, "PartnerAgreementTerms": { "type": "object", "additionalProperties": false, "required": [ "version", "source", "destination", "sourceRate", "destinationRate", "settlementMinorPerBlock", "settlementCurrency", "monthlySettlementCapMinor", "minimumSourcePoints", "maximumSourcePoints", "rounding", "destinationPointExpirationPolicy", "endsAt" ], "properties": { "version": { "type": "integer", "minimum": 1 }, "source": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "environmentId", "programId" ], "properties": { "organizationId": { "type": "string" }, "environmentId": { "type": "string" }, "programId": { "type": "string" } } }, "destination": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "environmentId", "programId" ], "properties": { "organizationId": { "type": "string" }, "environmentId": { "type": "string" }, "programId": { "type": "string" } } }, "sourceRate": { "type": "integer", "minimum": 1 }, "destinationRate": { "type": "integer", "minimum": 1 }, "settlementMinorPerBlock": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "monthlySettlementCapMinor": { "type": "integer", "minimum": 1 }, "minimumSourcePoints": { "type": "integer", "minimum": 1 }, "maximumSourcePoints": { "type": "integer", "minimum": 0 }, "rounding": { "type": "object", "additionalProperties": false, "required": [ "destinationPoints", "settlementMinor" ], "properties": { "destinationPoints": { "type": "string", "const": "floor" }, "settlementMinor": { "type": "string", "const": "ceiling" } } }, "destinationPointExpirationPolicy": { "$ref": "#/components/schemas/PartnerDestinationPointExpirationPolicy" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PartnerAgreementListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "partnerName", "participantRole", "status", "activePauseRoles", "source", "destination", "version", "termsHash", "canonicalTerms", "effectiveAt", "endsAt", "usage", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "partnerName": { "type": "string" }, "participantRole": { "type": "string", "enum": [ "source", "destination", "both" ] }, "status": { "type": "string", "enum": [ "draft", "proposed", "accepted", "active", "paused", "terminated" ] }, "activePauseRoles": { "type": "array", "items": { "type": "string", "enum": [ "source", "destination" ] } }, "source": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "environmentId", "programId" ], "properties": { "organizationId": { "type": "string" }, "environmentId": { "type": [ "string", "null" ] }, "programId": { "type": [ "string", "null" ] } } }, "destination": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "environmentId", "programId" ], "properties": { "organizationId": { "type": [ "string", "null" ] }, "environmentId": { "type": [ "string", "null" ] }, "programId": { "type": [ "string", "null" ] } } }, "version": { "type": "integer", "minimum": 1 }, "termsHash": { "type": [ "string", "null" ] }, "canonicalTerms": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "version", "termsHash", "state", "document", "sourceApprovalReference", "destinationApprovalReference", "proposedAt", "acceptedAt" ], "properties": { "version": { "type": "integer", "minimum": 1 }, "termsHash": { "type": "string" }, "state": { "type": "string" }, "document": { "$ref": "#/components/schemas/PartnerAgreementTerms" }, "sourceApprovalReference": { "type": [ "string", "null" ], "description": "Source approval reference for source-participant reads; null for destination-only reads." }, "destinationApprovalReference": { "type": [ "string", "null" ], "description": "Destination approval reference for destination-participant reads; null for source-only reads." }, "proposedAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, { "type": "null" } ] }, "effectiveAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "usage": { "type": "object", "additionalProperties": false, "required": [ "windowStart", "settlementCurrency", "monthlyCapMinor", "reservedSettlementMinor", "committedSettlementMinor", "settledSettlementMinor", "reversedSettlementMinor", "exposureSettlementMinor", "availableSettlementMinor" ], "properties": { "windowStart": { "type": "string", "format": "date-time" }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "monthlyCapMinor": { "type": "integer", "minimum": 1 }, "reservedSettlementMinor": { "type": "integer", "minimum": 0 }, "committedSettlementMinor": { "type": "integer", "minimum": 0 }, "settledSettlementMinor": { "type": "integer", "minimum": 0 }, "reversedSettlementMinor": { "type": "integer", "minimum": 0 }, "exposureSettlementMinor": { "type": "integer", "minimum": 0 }, "availableSettlementMinor": { "type": "integer", "minimum": 0 } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PartnerAgreementListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "agreements", "page" ], "properties": { "requestId": { "type": "string" }, "agreements": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerAgreementListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "PartnerDestinationPointExpiration": { "type": "object", "additionalProperties": false, "required": [ "policy", "days", "quotedAt", "rule" ], "properties": { "policy": { "type": "string", "enum": [ "fixed_days_after_commit", "does_not_expire" ] }, "days": { "type": "integer", "minimum": 0, "maximum": 36500 }, "quotedAt": { "type": "string", "format": "date-time" }, "rule": { "$ref": "#/components/schemas/PartnerDestinationExpirationRule" } } }, "PartnerDestinationExpirationRule": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "name", "priority", "configurationKey" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "priority": { "type": "integer", "minimum": 0 }, "configurationKey": { "type": [ "string", "null" ], "description": "Stable destination-program configuration key when the rule was published." } } }, "PartnerDestinationPointExpirationPolicy": { "type": "object", "additionalProperties": false, "required": [ "policy", "days", "selection", "rule" ], "properties": { "policy": { "type": "string", "enum": [ "fixed_days_after_commit", "does_not_expire" ] }, "days": { "type": "integer", "minimum": 0, "maximum": 36500 }, "selection": { "type": "string", "enum": [ "program_uniform", "explicit_rule" ] }, "rule": { "anyOf": [ { "$ref": "#/components/schemas/PartnerDestinationExpirationRule" }, { "type": "null" } ] } } }, "PartnerMemberLinkChallengeOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "sourceLinkChallenge", "agreementId", "expiresAt", "expiresIn", "notice" ], "properties": { "requestId": { "type": "string" }, "sourceLinkChallenge": { "type": "string", "minLength": 1 }, "agreementId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "const": 300 }, "notice": { "type": "string" } } }, "PartnerAgreementRejectRequest": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "reasonCode", "description", "rejectionReference" ], "properties": { "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact SHA-256 hash of the canonical agreement version being acted on." }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "rejectionReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerAgreementWithdrawRequest": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "reasonCode", "description", "withdrawalReference" ], "properties": { "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact SHA-256 hash of the canonical agreement version being acted on." }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "withdrawalReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerAgreementPauseRequest": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "reasonCode", "description", "incidentReference" ], "properties": { "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact SHA-256 hash of the canonical agreement version being acted on." }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "incidentReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerAgreementResumeRequest": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "reasonCode", "description", "approvalReference" ], "properties": { "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact SHA-256 hash of the canonical agreement version being acted on." }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "approvalReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerAgreementTerminateRequest": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "reasonCode", "description", "approvalReference" ], "properties": { "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Exact SHA-256 hash of the canonical agreement version being acted on." }, "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "approvalReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerAgreementLifecycleOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "agreement" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "agreement": { "type": "object", "additionalProperties": false, "required": [ "id", "version", "previousStatus", "status", "versionState", "outcome", "termsHash", "participantRole", "activePauseRoles", "evidence", "updatedAt" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "previousStatus": { "type": "string", "enum": [ "proposed", "active", "paused" ] }, "status": { "type": "string", "enum": [ "active", "paused", "terminated" ] }, "versionState": { "type": "string", "enum": [ "active", "rejected", "terminated" ] }, "outcome": { "type": "string", "enum": [ "reject", "withdraw", "pause", "resume", "terminate" ] }, "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "participantRole": { "type": "string", "enum": [ "source", "destination" ] }, "activePauseRoles": { "type": "array", "items": { "type": "string", "enum": [ "source", "destination" ] } }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "kind", "reference", "reasonCode" ], "properties": { "kind": { "type": "string", "enum": [ "rejection_reference", "withdrawal_reference", "incident_reference", "approval_reference" ] }, "reference": { "type": "string" }, "reasonCode": { "type": "string" } } }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "PartnerExchangeConfirmationRequest": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "approvalIntentId", "confirmationFingerprint", "confirmationNonce" ], "properties": { "quoteId": { "type": "string", "minLength": 1 }, "approvalIntentId": { "type": "string", "minLength": 1, "description": "Opaque, quote-bound intent already approved in the top-level Loyumi customer-verification ceremony." }, "confirmationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationNonce": { "type": "string", "pattern": "^pcn_[a-f0-9]{32}$" } } }, "PartnerExchangeConfirmationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "confirmationAssertion", "expiresAt", "expiresIn" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "confirmationAssertion": { "type": "string", "pattern": "^pca_[a-f0-9]{64}$", "description": "Short-lived, opaque customer assertion. Do not log, persist, or reuse it; the server retains only a SHA-256 digest." }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "minimum": 1, "maximum": 120 } } }, "PartnerExchangeProgramDisclosure": { "type": "object", "additionalProperties": false, "required": [ "organizationName", "programName", "unitName" ], "properties": { "organizationName": { "type": "string", "minLength": 1, "maxLength": 200 }, "programName": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "PartnerExchangeFinalityDisclosure": { "type": "object", "additionalProperties": false, "required": [ "version", "beforeCommit", "afterCommit", "reversalConstraint", "disputePath" ], "properties": { "version": { "type": "integer", "const": 1 }, "beforeCommit": { "type": "string", "minLength": 1, "maxLength": 500 }, "afterCommit": { "type": "string", "minLength": 1, "maxLength": 500 }, "reversalConstraint": { "type": "string", "minLength": 1, "maxLength": 500 }, "disputePath": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "PartnerExchangeCustomerDisclosure": { "type": "object", "additionalProperties": false, "required": [ "version", "source", "destination", "conversion", "finality" ], "properties": { "version": { "type": "integer", "const": 1 }, "source": { "$ref": "#/components/schemas/PartnerExchangeProgramDisclosure" }, "destination": { "$ref": "#/components/schemas/PartnerExchangeProgramDisclosure" }, "conversion": { "type": "object", "additionalProperties": false, "required": [ "sourceRate", "destinationRate", "requiredSourceIncrement", "destinationRounding", "settlementRounding" ], "properties": { "sourceRate": { "type": "integer", "minimum": 1 }, "destinationRate": { "type": "integer", "minimum": 1 }, "requiredSourceIncrement": { "type": "integer", "minimum": 1 }, "destinationRounding": { "type": "string", "const": "floor" }, "settlementRounding": { "type": "string", "const": "ceiling" } } }, "finality": { "$ref": "#/components/schemas/PartnerExchangeFinalityDisclosure" } } }, "PartnerExchangeListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "agreementId", "participantRole", "state", "sourcePoints", "destinationPoints", "returnedSourcePoints", "expiredSourcePoints", "settlementMinor", "settlementCurrency", "sourceReference", "agreementVersion", "quoteExpiresAt", "destinationExpiresAt", "customerConfirmedAt", "committedAt", "releasedAt", "settledAt", "reversedAt", "createdAt", "updatedAt", "consistency" ], "properties": { "id": { "type": "string" }, "quoteId": { "type": "string" }, "agreementId": { "type": "string" }, "participantRole": { "type": "string", "enum": [ "source", "destination", "both" ] }, "state": { "type": "string", "enum": [ "reserved", "committed", "released", "expired", "settled", "reversed" ] }, "sourcePoints": { "type": "integer", "minimum": 0 }, "destinationPoints": { "type": "integer", "minimum": 0 }, "returnedSourcePoints": { "type": [ "integer", "null" ], "minimum": 0 }, "expiredSourcePoints": { "type": [ "integer", "null" ], "minimum": 0 }, "settlementMinor": { "type": "integer", "minimum": 0 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sourceReference": { "type": [ "string", "null" ], "description": "Source-only reconciliation reference; null for destination reads." }, "agreementVersion": { "type": "integer", "minimum": 1 }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "destinationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "customerConfirmedAt": { "type": [ "string", "null" ], "format": "date-time" }, "committedAt": { "type": [ "string", "null" ], "format": "date-time" }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time" }, "settledAt": { "type": [ "string", "null" ], "format": "date-time" }, "reversedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "consistency": { "type": "string", "enum": [ "reconciled", "attention_required" ] } } }, "PartnerExchangeListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "exchanges", "page" ], "properties": { "requestId": { "type": "string" }, "exchanges": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerExchangeListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "PartnerExchangeReceiptTheme": { "type": "object", "additionalProperties": false, "required": [ "accent", "background", "surface", "text" ], "properties": { "accent": { "type": [ "string", "null" ], "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": [ "string", "null" ], "pattern": "^#[0-9a-f]{6}$" }, "surface": { "type": [ "string", "null" ], "pattern": "^#[0-9a-f]{6}$" }, "text": { "type": [ "string", "null" ], "pattern": "^#[0-9a-f]{6}$" } } }, "PartnerExchangeCustomerReceipt": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "exchangeId", "state", "status", "sourcePoints", "destinationPoints", "returnedSourcePoints", "expiredSourcePoints", "source", "destination", "conversion", "finality", "branding", "agreementVersion", "termsHash", "confirmationFingerprint", "confirmationNonce", "destinationPointExpiration", "destinationExpiresAt", "quoteExpiresAt", "confirmedAt", "confirmationExpiresAt", "committedAt", "releasedAt", "settledAt", "reversedAt", "updatedAt", "consistency", "customerFinal" ], "properties": { "quoteId": { "type": "string" }, "exchangeId": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "awaiting_confirmation", "confirmed", "quote_expired", "reserved", "committed", "released", "expired", "settled", "reversed", "attention_required" ] }, "status": { "type": "string", "enum": [ "awaiting_confirmation", "processing", "completed", "restored", "partially_restored", "not_completed", "reversed", "attention_required" ] }, "sourcePoints": { "type": "integer", "minimum": 0 }, "destinationPoints": { "type": "integer", "minimum": 0 }, "returnedSourcePoints": { "type": [ "integer", "null" ], "minimum": 0 }, "expiredSourcePoints": { "type": [ "integer", "null" ], "minimum": 0 }, "source": { "$ref": "#/components/schemas/PartnerExchangeProgramDisclosure" }, "destination": { "$ref": "#/components/schemas/PartnerExchangeProgramDisclosure" }, "conversion": { "type": "object", "additionalProperties": false, "required": [ "sourceRate", "destinationRate", "requiredSourceIncrement", "destinationRounding", "settlementRounding" ], "properties": { "sourceRate": { "type": "integer", "minimum": 1 }, "destinationRate": { "type": "integer", "minimum": 1 }, "requiredSourceIncrement": { "type": "integer", "minimum": 1 }, "destinationRounding": { "type": "string", "const": "floor" }, "settlementRounding": { "type": "string", "const": "ceiling" } } }, "finality": { "$ref": "#/components/schemas/PartnerExchangeFinalityDisclosure" }, "branding": { "type": "object", "additionalProperties": false, "required": [ "name", "theme" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "theme": { "$ref": "#/components/schemas/PartnerExchangeReceiptTheme" } } }, "agreementVersion": { "type": "integer", "minimum": 1 }, "termsHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationNonce": { "type": "string", "pattern": "^pcn_[a-f0-9]{32}$" }, "destinationPointExpiration": { "$ref": "#/components/schemas/PartnerDestinationPointExpiration" }, "destinationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "confirmedAt": { "type": [ "string", "null" ], "format": "date-time" }, "confirmationExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "committedAt": { "type": [ "string", "null" ], "format": "date-time" }, "releasedAt": { "type": [ "string", "null" ], "format": "date-time" }, "settledAt": { "type": [ "string", "null" ], "format": "date-time" }, "reversedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "consistency": { "type": [ "string", "null" ], "enum": [ "reconciled", "attention_required", null ] }, "customerFinal": { "type": "boolean" } } }, "PartnerExchangeCustomerReceiptOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "receipt" ], "properties": { "requestId": { "type": "string" }, "receipt": { "$ref": "#/components/schemas/PartnerExchangeCustomerReceipt" } } }, "PartnerExchangeApprovalIntentRequest": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "confirmationFingerprint", "confirmationNonce" ], "properties": { "quoteId": { "type": "string", "minLength": 1, "maxLength": 200 }, "confirmationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationNonce": { "type": "string", "pattern": "^pcn_[a-f0-9]{32}$" } } }, "PartnerExchangeApprovalIntent": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "expiresAt" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "verification_required", "approved", "consumed", "expired", "revoked" ] }, "quoteId": { "type": "string" }, "authorizeUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PartnerExchangeApprovalIntentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "approvalIntent" ], "properties": { "requestId": { "type": "string" }, "approvalIntent": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntent" } } }, "PartnerExchangeProviderStepUpRequest": { "type": "object", "additionalProperties": false, "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple" ] } } }, "PartnerExchangeProviderStepUpOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "stepUp" ], "properties": { "requestId": { "type": "string" }, "stepUp": { "type": "object", "additionalProperties": false, "required": [ "provider", "callbackUrl" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple" ] }, "callbackUrl": { "type": "string", "format": "uri" } } } } }, "PartnerExchangeCustomerActionRequest": { "type": "object", "additionalProperties": false, "required": [ "csrf" ], "properties": { "csrf": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "PartnerExchangeCustomerLink": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "verification_required", "pending_activation", "active", "expired", "revoked" ] }, "intentId": { "type": [ "string", "null" ] }, "authorizeUrl": { "type": [ "string", "null" ], "format": "uri" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "activatesAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PartnerExchangeCustomerLinkOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "customerLink" ], "properties": { "requestId": { "type": "string" }, "customerLink": { "$ref": "#/components/schemas/PartnerExchangeCustomerLink" } } }, "PartnerExchangeCustomerLinkRevocation": { "type": "object", "additionalProperties": false, "required": [ "state", "intentId", "authorizeUrl", "expiresAt" ], "properties": { "state": { "type": "string", "const": "verification_required" }, "intentId": { "type": "string" }, "authorizeUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "PartnerExchangeCustomerLinkRevocationStartOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "customerLinkRevocation" ], "properties": { "requestId": { "type": "string" }, "customerLinkRevocation": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkRevocation" } } }, "PartnerExchangeCustomerLinkRevokedOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "customerLink" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "customerLink": { "type": "object", "additionalProperties": false, "required": [ "state", "revokedAt" ], "properties": { "state": { "type": "string", "const": "revoked" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "PartnerExchangeGovernedLinkRevocationRequest": { "type": "object", "additionalProperties": false, "required": [ "externalCustomerId", "programId", "reason", "customerNotificationReference", "evidence" ], "properties": { "externalCustomerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reason": { "type": "string", "enum": [ "lost_provider_access", "provider_account_deleted", "provider_access_unrecoverable" ] }, "customerNotificationReference": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{2,199}$", "description": "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." }, "evidence": { "type": "object", "additionalProperties": false, "required": [ "kind", "reference", "reviewerReference", "verifiedAt" ], "properties": { "kind": { "type": "string", "enum": [ "merchant_identity_reverification", "legal_identity_request" ] }, "reference": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{2,199}$", "description": "Stable opaque merchant-attested identity-review reference. Must differ from the reviewer and customer-notification references. Loyumi records but does not certify the underlying review." }, "reviewerReference": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{2,199}$", "description": "Stable opaque merchant-attested reviewer reference. Loyumi enforces that it differs from the primary and notification references, but records rather than certifies the merchant's reviewer identity or review." }, "verifiedAt": { "type": "string", "format": "date-time" } } } } }, "PartnerExchangeGovernedLinkRevocationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "idempotent", "customerLink" ], "properties": { "requestId": { "type": "string" }, "idempotent": { "type": "boolean" }, "customerLink": { "type": "object", "additionalProperties": false, "required": [ "programId", "state", "revokedAt", "futureRelinkRequiresCooling" ], "properties": { "programId": { "type": "string" }, "state": { "type": "string", "const": "revoked" }, "revokedAt": { "type": "string", "format": "date-time" }, "futureRelinkRequiresCooling": { "type": "boolean", "const": true } } } } }, "RewardGiftRewardSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "version" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "version": { "type": "integer", "minimum": 1 } } }, "RewardGiftParticipant": { "type": "object", "additionalProperties": false, "required": [ "displayName", "identityHint" ], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "identityHint": { "type": "string", "minLength": 1, "maxLength": 180 } } }, "RewardGiftDisclosure": { "oneOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlementDisclosure" }, { "$ref": "#/components/schemas/RewardGiftChoiceDisclosure" } ] }, "RewardGiftQuoteRequest": { "oneOf": [ { "$ref": "#/components/schemas/RewardGiftDirectQuoteRequest" }, { "$ref": "#/components/schemas/RewardGiftInvitationQuoteRequest" } ], "description": "Exactly one direct reward or one durable invitation. Invitation quotes cover all immutable recipient choices." }, "RewardGiftQuote": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "programId", "reward", "senderCostPoints", "recipientOutcome", "claimDeadline", "rewardExpiresAt", "quoteExpiresAt", "disclosure", "disclosureFingerprint", "confirmationNonce" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "const": "quoted" }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reward": { "$ref": "#/components/schemas/RewardGiftRewardSummary" }, "senderCostPoints": { "type": "integer", "minimum": 1 }, "recipientOutcome": { "$ref": "#/components/schemas/RewardGiftRecipientOutcome" }, "claimDeadline": { "type": "string", "format": "date-time" }, "rewardExpiresAt": { "type": "string", "format": "date-time" }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "disclosure": { "$ref": "#/components/schemas/RewardGiftDisclosure" }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationNonce": { "type": "string", "pattern": "^rgn_[a-f0-9]{32}$" } } }, "RewardGiftQuoteOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGiftQuote" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "rewardGiftQuote": { "$ref": "#/components/schemas/RewardGiftQuote" }, "idempotent": { "const": true } } }, "RewardGiftApprovalIntentRequest": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "disclosureFingerprint", "confirmationNonce" ], "properties": { "quoteId": { "type": "string", "minLength": 1, "maxLength": 200 }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmationNonce": { "type": "string", "pattern": "^rgn_[a-f0-9]{32}$" } } }, "RewardGiftApprovalIntent": { "type": "object", "additionalProperties": false, "required": [ "id", "quoteId", "state", "disclosureFingerprint", "approvedAt", "expiresAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "quoteId": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "verification_required", "approved", "consumed", "expired", "revoked" ] }, "authorizeUrl": { "type": "string", "format": "uri" }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "RewardGiftApprovalIntentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "approvalIntent" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "approvalIntent": { "$ref": "#/components/schemas/RewardGiftApprovalIntent" }, "idempotent": { "const": true } } }, "RewardGiftCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "approvalId" ], "properties": { "quoteId": { "type": "string", "minLength": 1, "maxLength": 200 }, "approvalId": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "RewardGiftRestoration": { "type": "object", "additionalProperties": false, "required": [ "returnedPoints", "expiredPoints", "replacementPoints" ], "properties": { "returnedPoints": { "type": "integer", "minimum": 0 }, "expiredPoints": { "type": "integer", "minimum": 0 }, "replacementPoints": { "type": "integer", "minimum": 0 } } }, "RewardGiftRecoveryEvidence": { "type": "object", "additionalProperties": false, "required": [ "disputeId", "restoredOriginalPoints", "replacementPoints", "fulfillmentCancellationReference" ], "properties": { "disputeId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "restoredOriginalPoints": { "type": "integer", "minimum": 0 }, "replacementPoints": { "type": "integer", "minimum": 0 }, "fulfillmentCancellationReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] } } }, "RewardGiftParticipantReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "programId", "reward", "choice", "senderCostPoints", "recipientOutcome", "claimDeadline", "rewardExpiresAt", "disclosure", "disclosureFingerprint", "disclosureRedactedAt", "fulfillmentId", "restoration", "recovery", "acceptedAt", "declinedAt", "cancelledAt", "expiredAt", "reversedAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "pending_claim", "fulfilled", "declined", "cancelled", "expired", "reversed" ] }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reward": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRewardSummary" }, { "type": "null" } ] }, "senderCostPoints": { "type": "integer", "minimum": 1 }, "recipientOutcome": { "$ref": "#/components/schemas/RewardGiftRecipientOutcome" }, "claimDeadline": { "type": "string", "format": "date-time" }, "rewardExpiresAt": { "type": "string", "format": "date-time" }, "disclosure": { "$ref": "#/components/schemas/RewardGiftDisclosure" }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "fulfillmentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "fulfillment": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftListFulfillment" }, { "type": "null" } ], "description": "Merchant read/list reconciliation projection only; omitted from participant claim receipts." }, "restoration": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRestoration" }, { "type": "null" } ] }, "recovery": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRecoveryEvidence" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reversedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "recipient": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "pending_claim", "fulfilled", "declined", "cancelled", "expired", "reversed" ] } } }, "sender": { "type": "object", "additionalProperties": false, "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "disclosureRedactedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Tombstone time for governed participant-disclosure deletion. The original disclosure fingerprint remains durable." }, "choice": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftChoice" }, { "type": "null" } ] }, "entitlement": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlementProjection" }, { "type": "null" } ] } }, "description": "Authoritative participant-safe receipt. Sender and recipient are mutually exclusive role-specific projections; raw member IDs and every claim/provider capability are omitted." }, "RewardGiftCreateOutcome": { "oneOf": [ { "$ref": "#/components/schemas/RewardGiftCreateClaimAvailableOutcome" }, { "$ref": "#/components/schemas/RewardGiftCreateClaimUnavailableOutcome" } ], "description": "A direct v1 create or pending direct exact replay can return the private claim token. An invitation-backed v2 create returns claimUnavailable:true and mints recipient authority only at authenticated arrival. A terminal replay also returns claimUnavailable:true without resurrecting scrubbed claim material." }, "RewardGiftOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "rewardGift": { "allOf": [ { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, { "type": "object", "additionalProperties": false, "required": [ "entitlement" ], "properties": { "entitlement": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlementProjection" }, { "type": "null" } ] } } } ] }, "idempotent": { "const": true } } }, "RewardGiftClaimHandoffRequest": { "type": "object", "additionalProperties": false, "required": [ "giftId", "claimToken" ], "properties": { "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "claimToken": { "type": "string", "pattern": "^rgc_[A-Za-z0-9_-]{43}$", "x-sensitive": true } } }, "RewardGiftClaimHandoffOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "claimHandoff" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "claimHandoff": { "type": "object", "additionalProperties": false, "required": [ "giftId", "handoffCode", "expiresAt" ], "properties": { "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "handoffCode": { "type": "string", "pattern": "^rgh_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "idempotent": { "const": true } } }, "RewardGiftClaimHandoffExchangeRequest": { "type": "object", "additionalProperties": false, "required": [ "giftId", "handoffCode" ], "properties": { "giftId": { "type": "string", "pattern": "^rgt_[a-f0-9]{32}$" }, "handoffCode": { "type": "string", "pattern": "^rgh_[A-Za-z0-9_-]{43}$", "x-sensitive": true } } }, "RewardGiftClaimSessionOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "claimSession" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "claimSession": { "type": "object", "additionalProperties": false, "required": [ "giftId", "claimSessionToken", "expiresAt" ], "properties": { "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "expiresAt": { "type": "string", "format": "date-time" }, "claimSessionToken": { "type": "string", "pattern": "^rgs_[A-Za-z0-9_-]{43}$", "x-sensitive": true, "description": "Trusted-frame closure only. Send as X-Loyumi-Gift-Session; never forward or persist it." } } } } }, "RewardGiftClaimOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift", "capabilities" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "accept", "decline" ], "properties": { "accept": { "type": "boolean" }, "decline": { "type": "boolean" } } } } }, "RewardGiftDecisionRequest": { "type": "object", "additionalProperties": false, "required": [ "disclosureFingerprint" ], "properties": { "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "RewardGiftActionIntent": { "type": "object", "additionalProperties": false, "required": [ "id", "giftId", "action", "state", "disclosureFingerprint", "approvedAt", "expiresAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "action": { "type": "string", "enum": [ "accept", "decline", "cancel" ] }, "state": { "type": "string", "enum": [ "verification_required", "approved", "consumed", "expired", "revoked" ] }, "authorizeUrl": { "type": "string", "format": "uri" }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "consumedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } }, "RewardGiftActionIntentOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "giftActionIntent" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "giftActionIntent": { "$ref": "#/components/schemas/RewardGiftActionIntent" }, "idempotent": { "const": true } } }, "RewardGiftProviderStepUpOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "stepUp" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "stepUp": { "type": "object", "additionalProperties": false, "required": [ "provider", "callbackUrl" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple" ] }, "callbackUrl": { "type": "string", "format": "uri" } } } } }, "RewardGiftExplicitActionRequest": { "type": "object", "additionalProperties": false, "required": [ "csrf" ], "properties": { "csrf": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "RewardGiftActionOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "restoration": { "type": "object", "additionalProperties": false, "required": [ "returnedPoints", "expiredPoints" ], "properties": { "returnedPoints": { "type": "integer", "minimum": 0 }, "expiredPoints": { "type": "integer", "minimum": 0 } } }, "idempotent": { "const": true } } }, "RewardGiftRecoveryRequest": { "type": "object", "additionalProperties": false, "required": [ "disputeId", "reasonCode", "description", "fulfillmentCancellationReference" ], "properties": { "disputeId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reasonCode": { "type": "string", "enum": [ "fraud", "fulfillment_failure", "recipient_ineligible", "merchant_cancellation", "legal_requirement" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "RewardGiftRecoveryOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "idempotent": { "const": true } } }, "RewardGiftRecipientOutcome": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "description", "expiresAt" ], "properties": { "kind": { "const": "single_recipient_reward_entitlement" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "expiresAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "description", "expiresAt" ], "properties": { "kind": { "const": "recipient_choice_reward_entitlement" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "expiresAt": { "type": "string", "format": "date-time" } } } ] }, "RewardGiftDisputeEvidence": { "type": "object", "additionalProperties": false, "required": [ "fulfillmentCancellationReference" ], "properties": { "caseReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "providerReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "incidentReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1, "maxLength": 500 } }, "minProperties": 1, "maxProperties": 4, "description": "Pseudonymous references plus the exact cancellation evidence already bound to the fulfilled entitlement. Never include contact data or provider secrets." }, "RewardGiftDisputeRequest": { "type": "object", "additionalProperties": false, "required": [ "reasonCode", "description", "evidence" ], "properties": { "reasonCode": { "type": "string", "enum": [ "fraud", "fulfillment_failure", "recipient_ineligible", "merchant_cancellation", "legal_requirement" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidence": { "$ref": "#/components/schemas/RewardGiftDisputeEvidence" } } }, "RewardGiftDisputeResolutionRequest": { "type": "object", "additionalProperties": false, "required": [ "decision", "resolution" ], "properties": { "decision": { "type": "string", "enum": [ "resolved", "rejected" ] }, "resolution": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "RewardGiftDispute": { "type": "object", "additionalProperties": false, "required": [ "id", "subjectType", "subjectId", "state", "reasonCode" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "subjectType": { "const": "reward_gift" }, "subjectId": { "type": "string", "minLength": 1, "maxLength": 1000 }, "state": { "type": "string", "enum": [ "open", "resolved", "rejected" ] }, "reasonCode": { "type": "string", "enum": [ "fraud", "fulfillment_failure", "recipient_ineligible", "merchant_cancellation", "legal_requirement" ] }, "evidence": { "$ref": "#/components/schemas/RewardGiftDisputeEvidence" }, "resolution": { "type": "string", "minLength": 1, "maxLength": 2000 }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftDisputeOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "dispute" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "dispute": { "$ref": "#/components/schemas/RewardGiftDispute" }, "idempotent": { "const": true } } }, "RewardGiftCreateClaimAvailableOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift", "claim", "claimUnavailable" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "claim": { "type": "object", "additionalProperties": false, "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string", "pattern": "^rgc_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "claimUnavailable": { "const": false }, "idempotent": { "const": true } } }, "RewardGiftCreateClaimUnavailableOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGift", "claim", "claimUnavailable" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "claim": { "type": "object", "additionalProperties": false, "required": [ "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" } } }, "claimUnavailable": { "const": true }, "idempotent": { "const": true } }, "description": "Initial invitation-backed v2 reservation, or terminal exact replay after claim material was scrubbed. idempotent is present only on an exact replay." }, "RewardGiftListFulfillment": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "entitlementExpiresAt", "cancellationReference", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "anyOf": [ { "type": "string", "enum": [ "fulfilled", "reversed" ] }, { "type": "null" } ] }, "entitlementExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancellationReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "RewardGiftListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "programId", "reward", "choice", "senderCostPoints", "recipientOutcome", "claimDeadline", "rewardExpiresAt", "disclosure", "disclosureFingerprint", "disclosureRedactedAt", "fulfillmentId", "restoration", "recovery", "acceptedAt", "declinedAt", "cancelledAt", "expiredAt", "reversedAt", "createdAt", "updatedAt", "fulfillment", "entitlement" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "pending_claim", "fulfilled", "declined", "cancelled", "expired", "reversed" ] }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reward": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRewardSummary" }, { "type": "null" } ] }, "senderCostPoints": { "type": "integer", "minimum": 1 }, "recipientOutcome": { "$ref": "#/components/schemas/RewardGiftRecipientOutcome" }, "claimDeadline": { "type": "string", "format": "date-time" }, "rewardExpiresAt": { "type": "string", "format": "date-time" }, "disclosure": { "$ref": "#/components/schemas/RewardGiftDisclosure" }, "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "fulfillmentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "fulfillment": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftListFulfillment" }, { "type": "null" } ], "description": "Merchant read/list reconciliation projection only; omitted from participant claim receipts." }, "restoration": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRestoration" }, { "type": "null" } ] }, "recovery": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftRecoveryEvidence" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reversedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "recipient": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "pending_claim", "fulfilled", "declined", "cancelled", "expired", "reversed" ] } } }, "sender": { "type": "object", "additionalProperties": false, "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "disclosureRedactedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Tombstone time for governed participant-disclosure deletion. The original disclosure fingerprint remains durable." }, "choice": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftChoice" }, { "type": "null" } ] }, "entitlement": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlementProjection" }, { "type": "null" } ] } }, "description": "Merchant reconciliation projection with non-secret fulfillment state and no claim capability." }, "RewardGiftListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGifts", "page" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGifts": { "type": "array", "items": { "$ref": "#/components/schemas/RewardGiftListItem" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "RewardGiftFulfillmentCancellationRequest": { "type": "object", "additionalProperties": false, "required": [ "state", "fulfillmentCancellationReference" ], "properties": { "state": { "type": "string", "const": "cancelled" }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "RewardGiftFulfillmentCancellation": { "type": "object", "additionalProperties": false, "required": [ "id", "giftId", "state", "cancellationEvidenceRecorded", "fulfillmentCancellationReference", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "const": "fulfilled" }, "cancellationEvidenceRecorded": { "const": true }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftFulfillmentCancellationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "fulfillment" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "fulfillment": { "$ref": "#/components/schemas/RewardGiftFulfillmentCancellation" }, "idempotent": { "const": true } }, "description": "Evidence-only result. The recipient entitlement and gift remain fulfilled; this operation does not restore points." }, "RewardGiftClaimHandoffReplayOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "claimHandoff", "idempotent" ], "properties": { "requestId": { "type": "string", "minLength": 1 }, "claimHandoff": { "type": "object", "additionalProperties": false, "required": [ "giftId", "handoffCode", "expiresAt" ], "properties": { "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "handoffCode": { "type": "string", "pattern": "^rgh_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "idempotent": { "const": true } } }, "IdempotencyReceiptPrivacyScrubbedError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "const": "idempotency_receipt_privacy_scrubbed" }, "message": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 } } } } }, "RewardGiftInvitationPersonalization": { "type": "object", "additionalProperties": false, "required": [ "version", "message", "occasion", "theme", "locale" ], "properties": { "version": { "const": 1 }, "message": { "type": "string", "maxLength": 500 }, "occasion": { "type": "string", "maxLength": 80 }, "theme": { "type": "string", "enum": [ "celebration", "birthday", "thank_you", "holiday", "custom" ] }, "locale": { "type": "string", "minLength": 1, "maxLength": 35 } } }, "RewardGiftInvitationPersonalizationInput": { "type": "object", "additionalProperties": false, "required": [ "message", "occasion", "theme", "locale" ], "properties": { "message": { "type": "string", "maxLength": 500 }, "occasion": { "type": "string", "maxLength": 80 }, "theme": { "type": "string", "enum": [ "celebration", "birthday", "thank_you", "holiday", "custom" ] }, "locale": { "type": "string", "minLength": 1, "maxLength": 35 } } }, "RewardGiftInvitationOptionSnapshot": { "type": "object", "additionalProperties": false, "required": [ "version", "reward", "senderCostPoints", "claimWindowDays", "validityDays", "fulfillment" ], "properties": { "version": { "const": 1 }, "reward": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "catalogVersion" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "catalogVersion": { "type": "integer", "minimum": 1 } } }, "senderCostPoints": { "type": "integer", "minimum": 1 }, "claimWindowDays": { "type": "integer", "minimum": 1 }, "validityDays": { "type": "integer", "minimum": 1 }, "fulfillment": { "type": "object", "additionalProperties": false, "required": [ "kind", "policy", "totalUses" ], "properties": { "kind": { "const": "loyumi_recipient_entitlement" }, "policy": { "const": "recipient_bound_single_use" }, "totalUses": { "const": 1 } } } } }, "RewardGiftInvitationReadiness": { "type": "object", "additionalProperties": false, "required": [ "state", "reason", "coolingUntil", "nextAction" ], "properties": { "state": { "type": "string", "enum": [ "ready", "enrollment_required", "verification_required", "cooling_until", "ineligible" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "coolingUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "nextAction": { "type": "string", "enum": [ "quote_and_approve", "replace_invitation", "enroll_recipient", "verify_recipient", "wait_for_identity_cooling", "contact_support" ] } } }, "RewardGiftInvitationOption": { "type": "object", "additionalProperties": false, "required": [ "id", "rewardId", "position", "snapshot", "snapshotFingerprint", "reservationState" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0, "maximum": 3 }, "snapshot": { "$ref": "#/components/schemas/RewardGiftInvitationOptionSnapshot" }, "snapshotFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "reservationState": { "type": "string", "enum": [ "unreserved", "reserved", "selected", "released" ] } } }, "RewardGiftInvitationDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "phase", "kind", "channel", "state", "attemptNumber", "reminderNumber", "scheduledFor", "sentAt", "deliveredAt", "failedAt", "failureCode", "providerReference" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "phase": { "type": "string", "enum": [ "onboarding_notice", "gift_ready" ] }, "kind": { "type": "string", "enum": [ "initial", "reminder", "resend" ] }, "channel": { "type": "string", "enum": [ "merchant", "email", "sms", "push" ] }, "state": { "type": "string", "enum": [ "scheduled", "sent", "delivered", "failed", "cancelled" ] }, "attemptNumber": { "type": "integer", "minimum": 1, "maximum": 12 }, "reminderNumber": { "type": "integer", "minimum": 0, "maximum": 3 }, "scheduledFor": { "type": "string", "format": "date-time" }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" }, { "type": "null" } ] }, "providerReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] } } }, "RewardGiftInvitation": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "programId", "readiness", "personalization", "personalizationFingerprint", "personalizationRedactedAt", "delivery", "options", "deliveries", "sourceReference", "currentQuoteId", "giftId", "selectedRewardId", "expiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "onboarding", "ready", "quoted", "reserved", "accepted", "declined", "cancelled", "expired", "reversed", "revoked" ] }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "readiness": { "$ref": "#/components/schemas/RewardGiftInvitationReadiness" }, "personalization": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftInvitationPersonalization" }, { "type": "null" } ] }, "personalizationFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "personalizationRedactedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode", "channel", "destinationReference", "scheduledFor" ], "properties": { "mode": { "type": "string", "enum": [ "immediate", "scheduled" ] }, "channel": { "type": "string", "enum": [ "merchant", "email", "sms", "push" ] }, "destinationReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "scheduledFor": { "type": "string", "format": "date-time" } } }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/RewardGiftInvitationOption" }, "minItems": 1, "maxItems": 4 }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/RewardGiftInvitationDelivery" } }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "currentQuoteId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "giftId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "selectedRewardId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftInvitationCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "programId", "senderExternalCustomerId", "recipientExternalCustomerId", "rewardIds", "personalization", "delivery" ], "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "senderExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 }, "recipientExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 }, "rewardIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 4, "uniqueItems": true }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "personalization": { "$ref": "#/components/schemas/RewardGiftInvitationPersonalizationInput" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode", "channel", "destinationReference" ], "properties": { "mode": { "type": "string", "enum": [ "immediate", "scheduled" ] }, "channel": { "type": "string", "enum": [ "merchant", "email", "sms", "push" ] }, "destinationReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "scheduledFor": { "type": "string", "format": "date-time" } } } } }, "RewardGiftInvitationEligibilityNotice": { "type": "object", "additionalProperties": false, "required": [ "kind", "rewardAvailabilityPromised", "senderCostPromised" ], "properties": { "kind": { "const": "onboarding_notice" }, "rewardAvailabilityPromised": { "const": false }, "senderCostPromised": { "const": false } } }, "RewardGiftInvitationOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGiftInvitation", "eligibilityNotice" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGiftInvitation": { "$ref": "#/components/schemas/RewardGiftInvitation" }, "eligibilityNotice": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftInvitationEligibilityNotice" }, { "type": "null" } ] }, "idempotent": { "const": true } } }, "RewardGiftInvitationListOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGiftInvitations", "page" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGiftInvitations": { "type": "array", "items": { "$ref": "#/components/schemas/RewardGiftInvitation" } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "RewardGiftInvitationReadinessRequest": { "type": "object", "additionalProperties": false, "required": [ "recipientExternalCustomerId" ], "properties": { "recipientExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 } } }, "RewardGiftInvitationReadinessOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "invitationId", "state", "readiness" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "onboarding", "ready", "quoted", "reserved", "accepted", "declined", "cancelled", "expired", "reversed", "revoked" ] }, "readiness": { "$ref": "#/components/schemas/RewardGiftInvitationReadiness" }, "idempotent": { "const": true } } }, "RewardGiftInvitationDeliveryRequest": { "type": "object", "additionalProperties": false, "required": [ "phase", "kind" ], "properties": { "phase": { "type": "string", "enum": [ "onboarding_notice", "gift_ready" ] }, "kind": { "type": "string", "enum": [ "initial", "reminder", "resend" ] }, "scheduledFor": { "type": "string", "format": "date-time" } } }, "RewardGiftInvitationDeliveryContentBoundary": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "rewardAvailabilityPromised", "senderCostPromised" ], "properties": { "kind": { "const": "eligibility_invitation" }, "rewardAvailabilityPromised": { "const": false }, "senderCostPromised": { "const": false } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "rewardAvailabilityPromised", "senderCostPromised" ], "properties": { "kind": { "const": "reserved_gift_ready" }, "rewardAvailabilityPromised": { "const": true }, "senderCostPromised": { "const": true } } } ] }, "RewardGiftInvitationScheduledDelivery": { "type": "object", "additionalProperties": false, "required": [ "id", "phase", "kind", "channel", "state", "attemptNumber", "reminderNumber", "scheduledFor", "sentAt", "deliveredAt", "failedAt", "failureCode", "providerReference", "invitationId", "destinationReference", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "phase": { "type": "string", "enum": [ "onboarding_notice", "gift_ready" ] }, "kind": { "type": "string", "enum": [ "initial", "reminder", "resend" ] }, "channel": { "type": "string", "enum": [ "merchant", "email", "sms", "push" ] }, "state": { "type": "string", "enum": [ "scheduled", "sent", "delivered", "failed", "cancelled" ] }, "attemptNumber": { "type": "integer", "minimum": 1, "maximum": 12 }, "reminderNumber": { "type": "integer", "minimum": 0, "maximum": 3 }, "scheduledFor": { "type": "string", "format": "date-time" }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" }, { "type": "null" } ] }, "providerReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "destinationReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftInvitationDeliveryOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "delivery", "contentBoundary" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "delivery": { "$ref": "#/components/schemas/RewardGiftInvitationScheduledDelivery" }, "contentBoundary": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryContentBoundary" }, "idempotent": { "const": true } } }, "RewardGiftInvitationDeliveryEventRequest": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "sent", "delivered", "failed" ] }, "providerReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "failureCode": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" } }, "description": "failureCode is allowed only for failed; providerReference is an opaque provider receipt, never an address or secret." }, "RewardGiftInvitationDeliveryEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "invitationId", "phase", "state", "providerReference", "failureCode", "sentAt", "deliveredAt", "failedAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "phase": { "type": "string", "enum": [ "onboarding_notice", "gift_ready" ] }, "state": { "type": "string", "enum": [ "sent", "delivered", "failed" ] }, "providerReference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftInvitationDeliveryEventOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "delivery" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "delivery": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryEvent" }, "idempotent": { "const": true } } }, "RewardGiftInvitationArrivalRequest": { "type": "object", "additionalProperties": false, "required": [ "recipientExternalCustomerId", "deliveryId" ], "properties": { "recipientExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 }, "deliveryId": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "RewardGiftInvitationArrivalOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "invitationId", "giftId", "claimHandoff" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "claimHandoff": { "type": "object", "additionalProperties": false, "required": [ "handoffCode", "expiresAt" ], "properties": { "handoffCode": { "type": "string", "pattern": "^rgh_[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "expiresAt": { "type": "string", "format": "date-time" } } }, "idempotent": { "const": true } } }, "RewardGiftEntitlement": { "type": "object", "additionalProperties": false, "required": [ "id", "giftId", "fulfillmentId", "programId", "rewardId", "state", "totalUses", "remainingUses", "availableAt", "expiresAt", "usedAt", "expiredAt", "reversedAt", "updatedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "fulfillmentId": { "type": "string", "minLength": 1, "maxLength": 200 }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "legacy_untracked", "available", "used", "expired", "reversed" ] }, "totalUses": { "const": 1 }, "remainingUses": { "type": "integer", "enum": [ 0, 1 ] }, "availableAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "usedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reversedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftEntitlementUseProjection": { "type": "object", "additionalProperties": false, "required": [ "id", "sourceReference", "occurredAt", "recordedAt" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftEntitlementProjection": { "type": "object", "additionalProperties": false, "required": [ "id", "giftId", "fulfillmentId", "programId", "rewardId", "state", "totalUses", "remainingUses", "availableAt", "expiresAt", "usedAt", "expiredAt", "reversedAt", "updatedAt", "use" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "giftId": { "type": "string", "minLength": 1, "maxLength": 200 }, "fulfillmentId": { "type": "string", "minLength": 1, "maxLength": 200 }, "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "enum": [ "legacy_untracked", "available", "used", "expired", "reversed" ] }, "totalUses": { "const": 1 }, "remainingUses": { "type": "integer", "enum": [ 0, 1 ] }, "availableAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "usedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reversedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "use": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlementUseProjection" }, { "type": "null" } ] } } }, "RewardGiftEntitlementUseRequest": { "type": "object", "additionalProperties": false, "required": [ "sourceReference", "occurredAt" ], "properties": { "sourceReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" } } }, "RewardGiftEntitlementUseEvent": { "type": "object", "additionalProperties": false, "required": [ "kind", "quantity", "remainingAfter", "sourceReference", "occurredAt", "recordedAt" ], "properties": { "kind": { "const": "consume" }, "quantity": { "const": 1 }, "remainingAfter": { "const": 0 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftEntitlementUseOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "rewardGiftEntitlement", "useEvent" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardGiftEntitlement": { "$ref": "#/components/schemas/RewardGiftEntitlement" }, "useEvent": { "$ref": "#/components/schemas/RewardGiftEntitlementUseEvent" }, "idempotent": { "const": true } } }, "RewardGiftWalletGiftItem": { "type": "object", "additionalProperties": false, "required": [ "kind", "id", "createdAt", "rewardGift", "entitlement" ], "properties": { "kind": { "const": "gift" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "createdAt": { "type": "string", "format": "date-time" }, "rewardGift": { "$ref": "#/components/schemas/RewardGiftParticipantReceipt" }, "entitlement": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftEntitlement" }, { "type": "null" } ] } } }, "RewardGiftWalletInvitationItem": { "type": "object", "additionalProperties": false, "required": [ "kind", "id", "createdAt", "state", "readiness", "personalization", "scheduledFor", "giftId", "selectedRewardId", "updatedAt" ], "properties": { "kind": { "const": "invitation" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "createdAt": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "onboarding", "ready", "quoted", "reserved", "accepted", "declined", "cancelled", "expired", "reversed", "revoked" ] }, "readiness": { "type": "object", "additionalProperties": false, "required": [ "state", "reason", "coolingUntil" ], "properties": { "state": { "type": "string", "enum": [ "ready", "enrollment_required", "verification_required", "cooling_until", "ineligible" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "coolingUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "personalization": { "anyOf": [ { "$ref": "#/components/schemas/RewardGiftInvitationPersonalization" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "giftId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "selectedRewardId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RewardGiftWalletOutcome": { "type": "object", "additionalProperties": false, "required": [ "requestId", "view", "items", "page" ], "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "view": { "type": "string", "enum": [ "sent", "received" ] }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/RewardGiftWalletGiftItem" }, { "$ref": "#/components/schemas/RewardGiftWalletInvitationItem" } ] } }, "page": { "$ref": "#/components/schemas/CursorPage" } } }, "RewardGiftDirectQuoteRequest": { "type": "object", "additionalProperties": false, "required": [ "programId", "senderExternalCustomerId", "recipientExternalCustomerId", "rewardId" ], "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "senderExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 }, "recipientExternalCustomerId": { "type": "string", "minLength": 1, "maxLength": 320 }, "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "RewardGiftInvitationQuoteRequest": { "type": "object", "additionalProperties": false, "required": [ "programId", "invitationId" ], "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 200 }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "RewardGiftEntitlementDisclosure": { "type": "object", "additionalProperties": false, "required": [ "version", "reward", "issuer", "participants", "senderCost", "deadlines", "finality", "product", "fulfillment", "recipientOutcome", "restrictions" ], "properties": { "version": { "const": 1 }, "reward": { "$ref": "#/components/schemas/RewardGiftRewardSummary" }, "issuer": { "type": "object", "additionalProperties": false, "required": [ "organizationName", "programName", "unitName" ], "properties": { "organizationName": { "type": "string", "minLength": 1, "maxLength": 200 }, "programName": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "participants": { "type": "object", "additionalProperties": false, "required": [ "sender", "recipient" ], "properties": { "sender": { "$ref": "#/components/schemas/RewardGiftParticipant" }, "recipient": { "$ref": "#/components/schemas/RewardGiftParticipant" } } }, "senderCost": { "type": "object", "additionalProperties": false, "required": [ "points", "unitName" ], "properties": { "points": { "type": "integer", "minimum": 1 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "deadlines": { "type": "object", "additionalProperties": false, "required": [ "quoteExpiresAt", "claimDeadline" ], "properties": { "quoteExpiresAt": { "type": "string", "format": "date-time" }, "claimDeadline": { "type": "string", "format": "date-time" } } }, "finality": { "type": "object", "additionalProperties": false, "required": [ "beforeAcceptance", "afterAcceptance", "deliveryFailure" ], "properties": { "beforeAcceptance": { "type": "string", "minLength": 1 }, "afterAcceptance": { "type": "string", "minLength": 1 }, "deliveryFailure": { "type": "string", "minLength": 1 } } }, "product": { "const": "catalog_reward_entitlement_gift" }, "fulfillment": { "type": "object", "additionalProperties": false, "required": [ "kind", "policy" ], "properties": { "kind": { "const": "loyumi_recipient_entitlement" }, "policy": { "const": "recipient_bound_single_use" } } }, "recipientOutcome": { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "description", "expiresAt" ], "properties": { "kind": { "const": "single_recipient_reward_entitlement" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "expiresAt": { "type": "string", "format": "date-time" } } }, "restrictions": { "type": "object", "additionalProperties": false, "required": [ "cashValue", "transferable", "regiftable", "resellable" ], "properties": { "cashValue": { "const": false }, "transferable": { "const": false }, "regiftable": { "const": false }, "resellable": { "const": false } } } }, "description": "Immutable exact terms for one recipient-bound, single-use catalog reward entitlement. It has no cash value and cannot be transferred, regifted, or resold." }, "RewardGiftChoiceDisclosure": { "type": "object", "additionalProperties": false, "required": [ "version", "product", "invitationId", "reward", "issuer", "participants", "senderCost", "deadlines", "finality", "restrictions", "rewardOptions", "personalization", "delivery", "fulfillment", "recipientOutcome" ], "properties": { "version": { "const": 2 }, "product": { "const": "catalog_reward_entitlement_choice_gift" }, "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "reward": { "$ref": "#/components/schemas/RewardGiftRewardSummary" }, "issuer": { "type": "object", "additionalProperties": false, "required": [ "organizationName", "programName", "unitName" ], "properties": { "organizationName": { "type": "string", "minLength": 1, "maxLength": 200 }, "programName": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "participants": { "type": "object", "additionalProperties": false, "required": [ "sender", "recipient" ], "properties": { "sender": { "$ref": "#/components/schemas/RewardGiftParticipant" }, "recipient": { "$ref": "#/components/schemas/RewardGiftParticipant" } } }, "senderCost": { "type": "object", "additionalProperties": false, "required": [ "points", "unitName" ], "properties": { "points": { "type": "integer", "minimum": 1 }, "unitName": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "deadlines": { "type": "object", "additionalProperties": false, "required": [ "quoteExpiresAt", "claimDeadline" ], "properties": { "quoteExpiresAt": { "type": "string", "format": "date-time" }, "claimDeadline": { "type": "string", "format": "date-time" } } }, "finality": { "type": "object", "additionalProperties": false, "required": [ "beforeAcceptance", "afterAcceptance", "deliveryFailure" ], "properties": { "beforeAcceptance": { "type": "string", "minLength": 1 }, "afterAcceptance": { "type": "string", "minLength": 1 }, "deliveryFailure": { "type": "string", "minLength": 1 } } }, "restrictions": { "type": "object", "additionalProperties": false, "required": [ "cashValue", "transferable", "regiftable", "resellable" ], "properties": { "cashValue": { "const": false }, "transferable": { "const": false }, "regiftable": { "const": false }, "resellable": { "const": false } } }, "rewardOptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rewardId", "position", "snapshot", "snapshotFingerprint" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0, "maximum": 3 }, "snapshot": { "$ref": "#/components/schemas/RewardGiftInvitationOptionSnapshot" }, "snapshotFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "minItems": 1, "maxItems": 4 }, "personalization": { "$ref": "#/components/schemas/RewardGiftInvitationPersonalization" }, "delivery": { "type": "object", "additionalProperties": false, "required": [ "mode", "channel", "scheduledFor" ], "properties": { "mode": { "type": "string", "enum": [ "immediate", "scheduled" ] }, "channel": { "type": "string", "enum": [ "merchant", "email", "sms", "push" ] }, "scheduledFor": { "type": "string", "format": "date-time" } } }, "fulfillment": { "type": "object", "additionalProperties": false, "required": [ "kind", "policy" ], "properties": { "kind": { "const": "loyumi_recipient_entitlement" }, "policy": { "const": "recipient_bound_single_use" } } }, "recipientOutcome": { "type": "object", "additionalProperties": false, "required": [ "kind", "name", "description", "expiresAt" ], "properties": { "kind": { "const": "recipient_choice_reward_entitlement" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "expiresAt": { "type": "string", "format": "date-time" } } } }, "description": "Immutable terms for one recipient-bound choice among one to four catalog entitlement outcomes. It is noncash, nontransferable, nonreloadable, and single-use." }, "RewardGiftChoice": { "type": "object", "additionalProperties": false, "required": [ "invitationId", "options", "selectedRewardId" ], "properties": { "invitationId": { "type": "string", "minLength": 1, "maxLength": 200 }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "rewardId", "position", "reward" ], "properties": { "rewardId": { "type": "string", "minLength": 1, "maxLength": 200 }, "position": { "type": "integer", "minimum": 0, "maximum": 3 }, "reward": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "description", "catalogVersion" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "catalogVersion": { "type": "integer", "minimum": 1 } } } } }, "minItems": 1, "maxItems": 4 }, "selectedRewardId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } } }, "RewardGiftAcceptanceRequest": { "type": "object", "additionalProperties": false, "required": [ "disclosureFingerprint" ], "properties": { "disclosureFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "selectedRewardId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "description": "selectedRewardId is required for a v2 choice disclosure and forbidden for a direct v1 gift." } } }, "security": [ { "bearerAuth": [] } ], "x-rate-limit": { "requests": 600, "window": "60 seconds", "retryHeader": "Retry-After" }, "x-release": { "releasedAt": "2026-08-17", "previousVersion": "1.12.0", "compatibility": "additive", "summary": "Publishes a 121-operation contract for invitation-first catalog-entitlement Reward Gifts: durable personalization and readiness, recipient choice, isolated delivery scheduling and evidence, just-in-time trusted-frame arrival, first-party sent/received wallet, single-use entitlement evidence, 40 privacy-minimized webhook events, and portability schema 1.6.0 with 53 collections.", "migration": { "upgradeRequired": false, "newScopes": [ "gifts:delivery" ], "newCredentialAuthorityZones": [ "delivery", "fulfillment" ], "newOperations": [ "createRewardGiftInvitation", "listRewardGiftInvitations", "getRewardGiftInvitation", "refreshRewardGiftInvitationReadiness", "scheduleRewardGiftInvitationDelivery", "createRewardGiftInvitationArrival", "recordRewardGiftInvitationDeliveryEvent", "getRewardGiftWallet", "recordRewardGiftEntitlementUse" ], "webhookCatalogVersion": "2026-08-17", "webhookEventTypes": [ "points.earned", "member.enrolled", "member.unenrolled", "program.published", "redemption.reserved", "redemption.committed", "redemption.released", "redemption.expired", "redemption.reversed", "redemption.fulfillment.updated", "redemption.dispute.opened", "redemption.dispute.resolved", "redemption.dispute.rejected", "reward_gift.reserved", "reward_gift.accepted", "reward_gift.declined", "reward_gift.cancelled", "reward_gift.expired", "reward_gift.reversed", "reward_gift.fulfillment.updated", "reward_gift.dispute.opened", "reward_gift.dispute.resolved", "reward_gift.dispute.rejected", "adjustment.requested", "adjustment.rejected", "adjustment.posted", "adjustment.reversed", "import.completed", "partner_exchange.committed", "partner_exchange.released", "partner_exchange.expired", "partner_exchange.settled", "partner_exchange.reversed", "reward_gift.invitation.created", "reward_gift.invitation.readiness.updated", "reward_gift.invitation.delivery.scheduled", "reward_gift.invitation.delivery.updated", "reward_gift.entitlement.available", "reward_gift.entitlement.used", "reward_gift.entitlement.expired" ], "existingWebhookSubscriptionsUnchanged": true, "portabilitySchema": "1.6.0", "portabilityCollections": 53, "rawPointTransferAdded": false, "cashLikeBalanceAdded": false, "giftProduct": "catalog_reward_entitlement_choice_gift", "directGiftProductPreserved": "catalog_reward_entitlement_gift", "recipientBound": true, "transferable": false, "durableInvitationIsNotClaimAuthority": true, "notificationContainsClaimCapability": false, "governedPrivacyDeletionSupersedesHistoricReplay": { "status": 410, "code": "idempotency_receipt_privacy_scrubbed", "idempotentOperations": 59 } } }, "paths": { "/events": { "post": { "tags": [ "Commerce" ], "operationId": "postPurchase", "x-required-scope": "events:write", "summary": "Post a completed purchase and award points", "description": "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.", "x-evaluation-context": { "clock": "receipt-time-default-or-explicit-event-time-pinned-configuration", "currency": "request-validated-against-program", "clientOccurredAtSupported": true, "occurredAtAffectsRuleSelection": "only-when-event_time_pinned_configuration-is-explicit", "pinnedEventTimeSupported": true, "pinnedConfigurationMustBeEffectiveAtOccurredAt": true, "historicalMemberTierEvidenceRequired": true, "memberContext": true, "channelContext": true, "marketAndStoreContext": true, "customContext": "interpreted-only-when-referenced-by-a-published-rule", "lineItemsProvideReturnAttribution": true }, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseRequest" } } } }, "responses": { "200": { "description": "Existing transaction returned for a repeated idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotentOutcome" } } } }, "201": { "description": "New award committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/returns": { "post": { "tags": [ "Commerce" ], "operationId": "postReturn", "x-required-scope": "events:write", "summary": "Return all or part of an order and claw back points", "description": "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.", "x-clawback-model": { "mode": "line-attributed-with-legacy-amount-fallback", "lineSelectionSupported": true, "lineAttributedPointReversal": true, "legacyAmountOnlyProportional": true }, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRequest" } } } }, "responses": { "200": { "description": "Existing clawback transaction returned for a repeated idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnIdempotentOutcome" } } } }, "201": { "description": "Return and proportional clawback committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/custom-events": { "post": { "tags": [ "Engagement" ], "operationId": "postCustomEvent", "x-required-scope": "events:write", "summary": "Post a registered engagement event", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventRequest" } } } }, "responses": { "200": { "description": "Durable event and challenge-award outcome replayed for the same Idempotency-Key and exact request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventOutcome" } } } }, "201": { "description": "Event accepted and challenge awards returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEventOutcome" } } } }, "400": { "description": "Invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Invalid credential or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks events:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Active event definition or member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Idempotency-Key payload mismatch, production lock, or sourceReference already belongs to another event in this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "description": "JSON body exceeds 128 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Idempotency-Key or a required event field is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/offers/evaluate": { "post": { "tags": [ "Commerce" ], "operationId": "evaluateOffers", "x-required-scope": "offers:evaluate", "x-legacy-accepted-scope": "events:write", "x-legacy-scope-sunset": "2027-02-01T00:00:00Z", "summary": "Evaluate active cart offers", "description": "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.", "x-evaluation-context": { "clock": "server-receipt-time-current-configuration", "occurredAtAffectsRuleSelection": false, "memberContext": true, "channelContext": true, "currencyContext": true, "marketContext": true, "storeContext": true, "customContext": "accepted-not-interpreted-by-built-in-selectors" }, "x-least-privilege-status": "offers:evaluate is the dedicated non-mutating scope. events:write is accepted only as a compatibility bridge for existing API 1.7 credentials.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferEvaluationRequest" } } } }, "responses": { "200": { "description": "Contextual effects, eligibility reasons, matched line references, member context, coupon validity, and reconciled totals returned without mutation.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Deprecation": { "description": "Present with value true only when the events:write compatibility scope was used.", "schema": { "type": "string", "const": "true" } }, "Sunset": { "description": "Retirement date for the events:write scope fallback.", "schema": { "type": "string", "format": "http-date" } }, "Warning": { "description": "Migration warning emitted when the legacy scope fallback was used.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferEvaluationOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/choice-benefits": { "post": { "tags": [ "Engagement" ], "operationId": "claimChoiceBenefit", "x-required-scope": "events:write", "summary": "Claim a milestone choice benefit", "description": "Fulfills one eligible reward choice without spending points and decrements the member's remaining selections. Requires events:write.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoiceBenefitRequest" } } } }, "responses": { "200": { "description": "Existing fulfillment returned for a repeated idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoiceBenefitOutcome" } } } }, "201": { "description": "Choice fulfilled and remaining selections returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoiceBenefitOutcome" } } } }, "400": { "description": "Invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Invalid credential or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks events:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Member or active choice set was unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "No eligible choice or selected reward inventory remains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "description": "JSON body exceeds 128 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Idempotency-Key or a required choice field is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/members": { "post": { "tags": [ "Members" ], "operationId": "createMember", "summary": "Create a member identity", "description": "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.", "x-required-scope": "members:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "externalCustomerId", "displayName" ], "properties": { "externalCustomerId": { "type": "string", "minLength": 1, "maxLength": 200 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "minLength": 1, "maxLength": 64 }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ], "default": "unknown" }, "noticeVersion": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Merchant notice or consent-policy version shown to the member." } } } } } }, "responses": { "200": { "description": "Existing member returned idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberCreateOutcome" } } } }, "201": { "description": "Member identity, consent evidence, and audit event created; no program enrollment is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberCreateOutcome" } } } }, "401": { "description": "Invalid credential or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks members:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Member identity or consent fields are invalid, or legacy non-empty programIds requires the explicit program-enrollment operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "get": { "tags": [ "Members" ], "operationId": "listMembers", "summary": "List and exactly filter members", "x-required-scope": "members:read", "description": "List and exactly filter members. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires members:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "externalId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email", "maxLength": 320 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "suspended", "closed", "deleted" ] } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/{externalId}": { "get": { "tags": [ "Members" ], "operationId": "getMember", "x-required-scope": "members:read", "summary": "Get a member, balances, tier, and qualification state", "description": "Returns the member identity state and consent status plus every program profile and its available, pending, and reserved account balances. Requires members:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "externalId", "in": "path", "required": true, "description": "URL-encoded external customer ID.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Member, consent state, program profiles, tiers, qualification totals, and account balances returned with Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberDetailOutcome" } } } }, "401": { "description": "Invalid credential or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks members:read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Member was not found in the selected environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "tags": [ "Members" ], "operationId": "updateMember", "summary": "Update a member while preserving consent history", "description": "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.", "x-required-scope": "members:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "dependentRequired": { "noticeVersion": [ "consentStatus" ] }, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 320 }, "phone": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "active", "suspended", "closed" ] }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "noticeVersion": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Member updated and audit evidence appended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdateOutcome" } } } }, "401": { "description": "Invalid credential or environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks members:write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Member was not found in the selected environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "The member update is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "tags": [ "Members" ], "operationId": "anonymizeMember", "summary": "Anonymize a member under governed retention", "description": "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.", "x-required-scope": "members:delete", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "deletionReference", "reason" ], "properties": { "deletionReference": { "type": "string", "minLength": 1, "description": "Merchant privacy case or erasure request reference." }, "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Identity anonymized or original response replayed. Retained record classes are explicit in the response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAnonymizationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/imports": { "post": { "tags": [ "Imports" ], "operationId": "stageMemberImport", "summary": "Validate and stage a member snapshot import", "description": "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.", "x-required-scope": "imports:write", "x-import-semantics": { "mode": "snapshot", "stageMutatesCustomerValue": false, "resumableApply": true, "createOnly": true, "productionWindow": "locked_prelaunch_only", "productionWindowReopens": false }, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberImportRequest" } } } }, "responses": { "201": { "description": "Member snapshot validated and staged without applying customer value, or the original 201 receipt replayed for an identical idempotent command.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberImportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/ImportPayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "tags": [ "Imports" ], "operationId": "listMemberImports", "summary": "List member import batches", "x-required-scope": "imports:read", "description": "List member import batches. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires imports:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "validated", "exceptions_review", "applying", "completed" ] } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/imports/{batchId}": { "get": { "tags": [ "Imports" ], "operationId": "getMemberImport", "summary": "Inspect a staged or partially applied member import", "description": "Returns batch progress plus a stable row-number page of all, valid, exception, or applied records. Requires imports:read.", "x-required-scope": "imports:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "afterRow", "in": "query", "required": false, "description": "Return rows whose stable one-based rowNumber is greater than this cursor.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "valid", "exception", "applied" ] } } ], "responses": { "200": { "description": "Batch progress and row page returned.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberImportStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/imports/{batchId}/apply": { "post": { "tags": [ "Imports" ], "operationId": "applyMemberImport", "summary": "Apply the next member import chunk", "description": "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.", "x-required-scope": "imports:apply", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyMemberImportRequest" } } } }, "responses": { "200": { "description": "Chunk applied or original idempotent chunk outcome replayed; remaining progress returned.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyMemberImportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/exports": { "get": { "tags": [ "Portability" ], "operationId": "exportPortabilityBundle", "summary": "Export a versioned, secret-safe environment bundle", "description": "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.", "externalDocs": { "description": "Portability export schema 1.6.0", "url": "https://app.loyumi.com/schemas/portability-export.v1.6.0.json" }, "x-consistency-model": { "consistencyModel": "best-effort-request-view", "crossQueryMvccSnapshot": false, "crossPageSnapshot": false, "snapshotToken": false, "highWaterMark": false, "incrementalExport": false, "exactCutoverRequiresPausedWrites": true, "postExportReconciliationRequired": true }, "x-public-import-api": { "published": true, "stage": "/imports", "inspect": "/imports/{batchId}", "apply": "/imports/{batchId}/apply", "mode": "resumable-member-snapshot" }, "x-required-scope": "exports:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "collection", "in": "query", "required": false, "description": "Export one collection for cursor pagination.", "schema": { "type": "string", "enum": [ "configuration", "members", "memberProfiles", "programs", "programRules", "tiers", "rewards", "campaigns", "campaignRules", "campaignMemberUsage", "loyaltyEvents", "referrals", "challengeProgress", "memberChoiceAwards", "sharedWalletMembers", "commerceOrders", "commerceOrderLines", "commerceReturns", "ledgerAccounts", "ledgerBalances", "pointLots", "pointLotAllocations", "ledgerTransactions", "ledgerEntries", "consentEvents", "riskCases", "approvalRequests", "operations", "importBatches", "importRows", "auditEvents", "programConfigurations", "redemptionQuotes", "redemptions", "reservationLotAllocations", "rewardFulfillments", "rewardGiftQuotes", "rewardGifts", "rewardGiftInvitations", "rewardGiftInvitationOptions", "rewardGiftInvitationDeliveries", "rewardGiftSelections", "rewardGiftEntitlements", "rewardGiftEntitlementUseEvents", "valueDisputes", "ledgerAdjustments", "partnerAgreements", "partnerAgreementVersions", "partnerAgreementPauseHolds", "partnerUsageWindows", "partnerExchangeQuotes", "partnerExchanges", "partnerSettlements" ] } }, { "name": "after", "in": "query", "required": false, "description": "Stable cursor returned in manifest.pagination.next. Requires collection.", "schema": { "type": "string", "maxLength": 256 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum records per included collection.", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 } } ], "responses": { "200": { "description": "Versioned portability manifest and requested records. Response is no-store and attachment-ready.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortabilityExport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/redemption-quotes": { "post": { "tags": [ "Redemptions" ], "operationId": "createRedemptionQuote", "summary": "Quote a governed point redemption", "description": "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.", "x-required-scope": "redemptions:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "programId", "externalCustomerId", "sourceReference" ], "properties": { "programId": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "rewardId": { "type": "string", "minLength": 1 }, "points": { "type": "integer", "minimum": 1 }, "ttlSeconds": { "type": "integer", "minimum": 30, "maximum": 900, "default": 300 } }, "oneOf": [ { "required": [ "rewardId" ], "not": { "required": [ "points" ] } }, { "required": [ "points" ], "not": { "required": [ "rewardId" ] } } ] } } } }, "responses": { "200": { "description": "Original quote replayed for the same idempotency key and identical payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionQuoteOutcome" } } } }, "201": { "description": "Bounded quote created without moving points or inventory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionQuoteOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions": { "post": { "tags": [ "Redemptions" ], "operationId": "reserveRedemption", "summary": "Reserve points and reward inventory from a quote", "description": "Atomically consumes an unexpired quote, moves available points into a reserved account, preserves point-lot provenance, and reserves finite reward inventory.", "x-required-scope": "redemptions:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quoteId" ], "properties": { "quoteId": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original reservation replayed for the same idempotency key and identical payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReservationOutcome" } } } }, "201": { "description": "Points and any finite inventory reserved atomically.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReservationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Redemptions" ], "operationId": "listRedemptions", "summary": "List and filter redemptions", "x-required-scope": "redemptions:read", "description": "List and filter redemptions. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires redemptions:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "externalCustomerId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sourceReference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "reserved", "committed", "released", "expired", "reversed" ] } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/redemptions/{redemptionId}": { "get": { "tags": [ "Redemptions" ], "operationId": "getRedemption", "summary": "Get redemption financial, fulfillment, and dispute state", "x-required-scope": "redemptions:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Current financial state, transaction links, fulfillment state, and disputes returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionDetailOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/commit": { "post": { "tags": [ "Redemptions" ], "operationId": "commitRedemption", "summary": "Commit a reserved redemption", "x-required-scope": "redemptions:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fulfillmentReference": { "type": "string", "description": "Optional connector reference when it already exists." }, "provider": { "type": "string", "description": "Required for coupon and external fulfillment types." } } } } } }, "responses": { "200": { "description": "Original commit replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionCommitOutcome" } } } }, "201": { "description": "Redemption committed and fulfillment evidence recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionCommitOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/release": { "post": { "tags": [ "Redemptions" ], "operationId": "releaseRedemption", "summary": "Release a reservation", "x-required-scope": "redemptions:write", "description": "Returns still-valid reserved point lots to available balance, records expired portions, and releases finite inventory.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "additionalProperties": false } } } }, "responses": { "200": { "description": "Original release replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReleaseOutcome" } } } }, "201": { "description": "Reservation released with point-lot provenance preserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReleaseOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/expire": { "post": { "tags": [ "Redemptions" ], "operationId": "expireRedemption", "summary": "Expire a reservation after its deadline", "x-required-scope": "redemptions:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "additionalProperties": false } } } }, "responses": { "200": { "description": "Original expiration replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReleaseOutcome" } } } }, "201": { "description": "Past-due reservation expired; valid points returned and expired points recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReleaseOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/reverse": { "post": { "tags": [ "Redemptions" ], "operationId": "reverseRedemption", "summary": "Reverse a committed redemption", "x-required-scope": "redemptions:reverse", "description": "Creates a linked compensating transaction. A fulfilled reward also requires a fulfillmentCancellationReference.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reasonCode", "description" ], "properties": { "reasonCode": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original reversal replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReverseOutcome" } } } }, "201": { "description": "Compensating reversal committed with evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionReverseOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/cancel": { "post": { "tags": [ "Redemptions" ], "operationId": "cancelRedemption", "summary": "Cancel using the safe operation for current state", "x-required-scope": "redemptions:write", "x-conditional-scope": "redemptions:reverse", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reasonCode": { "type": "string" }, "description": { "type": "string" }, "fulfillmentCancellationReference": { "type": "string" } } } } } }, "responses": { "200": { "description": "Original derived command replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionCancelOutcome" } } } }, "201": { "description": "Safe state-dependent cancellation completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionCancelOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/redemptions/{redemptionId}/disputes": { "post": { "tags": [ "Redemptions" ], "operationId": "openRedemptionDispute", "summary": "Open a redemption dispute with evidence", "x-required-scope": "disputes:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reasonCode", "description", "evidence" ], "properties": { "reasonCode": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "Inline JSON evidence metadata retained with the dispute. External files must be stored by the merchant and referenced from this object." } } } } } }, "responses": { "200": { "description": "Original dispute replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionDisputeOutcome" } } } }, "201": { "description": "Open dispute recorded and linked to the redemption.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionDisputeOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "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." } }, "/redemption-disputes/{disputeId}/resolve": { "post": { "tags": [ "Redemptions" ], "operationId": "resolveRedemptionDispute", "summary": "Resolve an open redemption dispute", "x-required-scope": "disputes:resolve", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "decision", "resolution" ], "properties": { "decision": { "type": "string", "enum": [ "resolved", "rejected" ] }, "resolution": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Original resolution replayed or dispute resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionDisputeResolutionOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "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." } }, "/redemptions/{redemptionId}/fulfillment-events": { "post": { "tags": [ "Redemptions" ], "operationId": "recordRedemptionFulfillment", "summary": "Record an idempotent fulfillment connector event", "x-required-scope": "fulfillments:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "redemptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "pending", "fulfilled", "failed", "cancelled" ] }, "fulfillmentReference": { "type": "string", "minLength": 1, "maxLength": 500 }, "fulfillmentCancellationReference": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Durable merchant or connector cancellation evidence. Required when the stored fulfillment is fulfilled and the requested state is cancelled.", "x-required-when": "existing fulfillment state is fulfilled and requested state is cancelled" }, "lastError": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "Original connector event replayed or fulfillment updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionFulfillmentOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-state-dependent-requirements": { "fulfilled -> cancelled": [ "fulfillmentCancellationReference" ] } } }, "/adjustments": { "post": { "tags": [ "Adjustments" ], "operationId": "requestAdjustment", "summary": "Request a governed ledger adjustment", "x-required-scope": "adjustments:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "programId", "externalCustomerId", "direction", "points", "reasonCode", "description", "evidence" ], "properties": { "programId": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "points": { "type": "integer", "minimum": 1 }, "reasonCode": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "evidence": { "type": "object", "minProperties": 1, "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Original request replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentRequestOutcome" } } } }, "202": { "description": "Adjustment recorded pending independent approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentRequestOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Adjustments" ], "operationId": "listAdjustments", "summary": "List and filter governed adjustments", "x-required-scope": "adjustments:read", "description": "List and filter governed adjustments. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires adjustments:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "externalCustomerId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/adjustments/{adjustmentId}": { "get": { "tags": [ "Adjustments" ], "operationId": "getAdjustment", "summary": "Get adjustment evidence and posting state", "x-required-scope": "adjustments:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "adjustmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Adjustment, evidence, approval, and transaction links returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentDetailOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/adjustments/{adjustmentId}/approve": { "post": { "tags": [ "Adjustments" ], "operationId": "approveAdjustment", "summary": "Independently approve and post an adjustment", "x-required-scope": "adjustments:approve", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "adjustmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "approvalReference", "decisionNote" ], "properties": { "approvalReference": { "type": "string", "minLength": 1 }, "decisionNote": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original decision replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentPostOutcome" } } } }, "201": { "description": "Adjustment posted to the balanced ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentPostOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/adjustments/{adjustmentId}/reject": { "post": { "tags": [ "Adjustments" ], "operationId": "rejectAdjustment", "summary": "Independently reject an adjustment", "x-required-scope": "adjustments:approve", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "adjustmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "approvalReference", "decisionNote" ], "properties": { "approvalReference": { "type": "string", "minLength": 1 }, "decisionNote": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Adjustment rejected or original rejection replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentRejectOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/adjustments/{adjustmentId}/reverse": { "post": { "tags": [ "Adjustments" ], "operationId": "reverseAdjustment", "summary": "Post a compensating reversal for an adjustment", "x-required-scope": "adjustments:approve", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "adjustmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "approvalReference", "decisionNote" ], "properties": { "approvalReference": { "type": "string", "minLength": 1 }, "decisionNote": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original reversal replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentPostOutcome" } } } }, "201": { "description": "Linked compensating transaction posted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentPostOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/program-configurations/validate": { "post": { "tags": [ "Programs" ], "operationId": "validateProgramConfiguration", "summary": "Validate and normalize a program manifest", "x-required-scope": "programs:write", "description": "Returns a checksum, normalized manifest, impact counts, and policy warnings without creating or changing a program.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramManifestInput" } } } }, "responses": { "200": { "description": "Manifest is valid and normalized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramValidationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/programs": { "get": { "tags": [ "Programs" ], "operationId": "listPrograms", "summary": "List programs and latest managed revisions", "x-required-scope": "programs:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Environment programs and their newest immutable configuration revision returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramListOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Programs" ], "operationId": "createProgram", "summary": "Create a draft program from a validated manifest", "x-required-scope": "programs:write", "description": "Creates version 1 as an immutable draft. It does not publish or activate the program.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramManifestInput" } } } }, "responses": { "200": { "description": "Original create response replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramCreateOutcome" } } } }, "201": { "description": "Draft program and immutable version 1 created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramCreateOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/programs/{programId}/configuration": { "get": { "tags": [ "Programs" ], "operationId": "getProgramConfiguration", "summary": "Get the current or a specific immutable program manifest", "x-required-scope": "programs:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Immutable manifest and checksum returned. The ETag header is required for the next revision mutation.", "headers": { "ETag": { "description": "Quoted version-checksum token for If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramConfigurationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/programs/{programId}/revisions": { "get": { "tags": [ "Programs" ], "operationId": "listProgramRevisions", "summary": "List immutable program revision history", "x-required-scope": "programs:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revision versions, status, checksum, provenance, and timestamps returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramRevisionListOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Programs" ], "operationId": "createProgramRevision", "summary": "Create the next immutable draft revision", "x-required-scope": "programs:write", "description": "Requires the latest ETag in If-Match. Returns 428 when absent and 412 when stale.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "$ref": "#/components/parameters/ifMatch" }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramManifestInput" } } } }, "responses": { "200": { "description": "Original revision response replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramRevisionCreateOutcome" } } } }, "201": { "description": "Next immutable draft created with a new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramRevisionCreateOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/programs/{programId}/revisions/{version}/publish": { "post": { "tags": [ "Programs" ], "operationId": "publishProgramRevision", "summary": "Publish one exact draft revision", "x-required-scope": "programs:publish", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "$ref": "#/components/parameters/ifMatch" }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "approvalReference": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original publish response replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramPublishOutcome" } } } }, "201": { "description": "Exact revision published atomically.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramPublishOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/programs/{programId}/revisions/{version}/restore": { "post": { "tags": [ "Programs" ], "operationId": "restoreProgramRevision", "summary": "Copy an old manifest into a new draft revision", "x-required-scope": "programs:write", "description": "Restore never mutates history or silently publishes. It copies the selected source version into the next immutable draft and requires the latest ETag.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "$ref": "#/components/parameters/ifMatch" }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "Historical source version to copy.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Original restore response replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramRestoreOutcome" } } } }, "201": { "description": "Historical manifest copied into a new draft with a new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramRestoreOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-agreements": { "post": { "tags": [ "Partners" ], "operationId": "proposePartnerAgreement", "summary": "Propose versioned bilateral exchange terms", "x-required-scope": "partners:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "sourceProgramId", "destinationOrganizationId", "destinationEnvironmentId", "destinationProgramId", "partnerName", "sourceApprovalReference", "sourceRate", "destinationRate", "settlementMinorPerBlock", "monthlySettlementCapMinor" ], "properties": { "sourceProgramId": { "type": "string", "minLength": 1 }, "destinationOrganizationId": { "type": "string", "minLength": 1 }, "destinationEnvironmentId": { "type": "string", "minLength": 1 }, "destinationProgramId": { "type": "string", "minLength": 1 }, "partnerName": { "type": "string", "minLength": 1, "description": "Must match the destination organization's registered name, ignoring case. The canonical registered name is persisted." }, "sourceApprovalReference": { "type": "string", "minLength": 1 }, "sourceRate": { "type": "integer", "minimum": 1 }, "destinationRate": { "type": "integer", "minimum": 1 }, "settlementMinorPerBlock": { "type": "integer", "minimum": 1 }, "settlementCurrency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" }, "monthlySettlementCapMinor": { "type": "integer", "minimum": 1 }, "minimumSourcePoints": { "type": "integer", "minimum": 1, "description": "Defaults to sourceRate. Must be at least sourceRate and an exact multiple of sourceRate." }, "maximumSourcePoints": { "type": "integer", "minimum": 0, "default": 0, "description": "Zero means unlimited; otherwise it must be an exact sourceRate multiple at least minimumSourcePoints." }, "endsAt": { "type": "string", "format": "date-time", "maxLength": 64 }, "destinationExpirationRuleId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "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." } } } } } }, "responses": { "200": { "description": "Original proposal replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementProposalOutcome" } } } }, "201": { "description": "Version 1 proposed with immutable termsHash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementProposalOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Partners" ], "operationId": "listPartnerAgreements", "summary": "List bilateral agreement corridors and current cap usage", "description": "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.", "x-required-scope": "partners:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page; pages are ordered by creation time then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "proposed", "accepted", "active", "paused", "terminated" ] } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "source", "destination" ] } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Participant-scoped agreement corridors and current usage returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-agreements/{agreementId}/accept": { "post": { "tags": [ "Partners" ], "operationId": "acceptPartnerAgreement", "summary": "Accept the exact bilateral agreement terms", "x-required-scope": "partners:approve", "description": "Callable only by the destination tenant named in the proposal. Activates only when termsHash matches exactly.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "termsHash", "acceptanceReference" ], "properties": { "termsHash": { "type": "string", "minLength": 1 }, "acceptanceReference": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Exact terms accepted or original acceptance replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementAcceptanceOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-member-tokens": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerMemberToken", "summary": "Create an opaque one-time destination member link", "x-required-scope": "exchanges:member-link", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "agreementId", "externalCustomerId", "sourceLinkChallenge", "consentReference" ], "properties": { "agreementId": { "type": "string", "minLength": 1 }, "externalCustomerId": { "type": "string", "minLength": 1 }, "sourceLinkChallenge": { "type": "string", "minLength": 1, "maxLength": 256 }, "consentReference": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Single-use 5-minute member token returned once with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerMemberTokenOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-quotes": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerExchangeQuote", "summary": "Quote conversion and clearing economics", "x-required-scope": "exchanges:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "agreementId", "sourceExternalCustomerId", "destinationMemberToken", "sourceReference", "sourcePoints" ], "properties": { "agreementId": { "type": "string", "minLength": 1 }, "sourceExternalCustomerId": { "type": "string", "minLength": 1 }, "destinationMemberToken": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 }, "sourcePoints": { "type": "integer", "minimum": 1, "description": "Must be a positive exact multiple of the selected agreement's sourceRate; this prevents silent fractional destination-point loss." } } } } } }, "responses": { "200": { "description": "Original quote replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeQuoteOutcome" } } } }, "201": { "description": "Pinned conversion and settlement quote created without moving value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeQuoteOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchanges": { "post": { "tags": [ "Partners" ], "operationId": "reservePartnerExchange", "summary": "Reserve source points and agreement capacity", "x-required-scope": "exchanges:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quoteId", "confirmationAssertion" ], "properties": { "quoteId": { "type": "string", "minLength": 1 }, "confirmationAssertion": { "type": "string", "pattern": "^pca_[a-f0-9]{64}$" } } } } } }, "responses": { "200": { "description": "Original reservation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeReservationOutcome" } } } }, "201": { "description": "Source points and monthly settlement capacity reserved atomically.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeReservationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Partners" ], "operationId": "listPartnerExchanges", "summary": "List participant-scoped exchanges for recovery and reconciliation", "description": "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.", "x-required-scope": "exchanges:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "reserved", "committed", "released", "expired", "settled", "reversed" ] } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "source", "destination" ] } }, { "name": "agreementId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sourceReference", "in": "query", "required": false, "description": "Source-participant-only exact filter; implicitly restricts participation to source.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Participant-scoped exchange page returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-exchanges/{exchangeId}": { "get": { "tags": [ "Partners" ], "operationId": "getPartnerExchange", "summary": "Get bilateral exchange and reconciliation state", "x-required-scope": "exchanges:read", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "exchangeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exchange state and participant-safe reconciliation evidence returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeDetailOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchanges/{exchangeId}/commit": { "post": { "tags": [ "Partners" ], "operationId": "commitPartnerExchange", "summary": "Commit both sides of a reserved exchange", "x-required-scope": "exchanges:write", "description": "Posts separate balanced source debit and destination credit transactions, creates the destination point lot, and converts reserved monthly cap usage into committed usage.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "exchangeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "additionalProperties": false } } } }, "responses": { "200": { "description": "Exchange committed or original commit replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCommitOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-corrective-while-production-locked": false } }, "/partner-exchanges/{exchangeId}/release": { "post": { "tags": [ "Partners" ], "operationId": "releasePartnerExchange", "summary": "Release a reserved exchange", "x-required-scope": "exchanges:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "exchangeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reasonCode": { "type": "string", "default": "merchant_release" } } } } } }, "responses": { "200": { "description": "Exchange released or original release replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeReleaseOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-corrective-while-production-locked": true } }, "/partner-exchanges/{exchangeId}/settle": { "post": { "tags": [ "Partners" ], "operationId": "settlePartnerExchange", "summary": "Record external clearing settlement evidence", "x-required-scope": "settlements:write", "description": "Records the external settlement reference and reconciles settled usage to the committed agreement amount; it does not initiate a bank payment.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "exchangeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "settlementReference" ], "properties": { "settlementReference": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Settlement evidence recorded or original settlement replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeSettlementOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-corrective-while-production-locked": false } }, "/partner-exchanges/{exchangeId}/reverse": { "post": { "tags": [ "Partners" ], "operationId": "reversePartnerExchange", "summary": "Reverse both program transactions and cap usage", "x-required-scope": "exchanges:reverse", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "exchangeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reasonCode", "description" ], "properties": { "reasonCode": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "settlementReversalReference": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Exchange reversed or original reversal replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeReverseOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-corrective-while-production-locked": true } }, "/widget-sessions": { "post": { "tags": [ "Widgets" ], "operationId": "createWidgetSession", "summary": "Create a short-lived personalized widget session", "description": "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.", "x-required-scope": "widgets:sessions", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionRequest" } } } }, "responses": { "201": { "description": "An opaque single-use 60-second iframe handoff code was created. The response includes Cache-Control: no-store.", "headers": { "Cache-Control": { "description": "Always no-store.", "schema": { "type": "string", "const": "no-store" } }, "X-Request-Id": { "description": "Trace identifier for support and audit correlation.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionCodeResponse" } } } }, "400": { "description": "The deployment ID, external customer ID, origin, or request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Credential or X-Environment is absent, invalid, expired, revoked, or crossed between environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks widgets:sessions; rewards:redeem additionally lacks widgets:redemptions; or a requested permission is not enabled on the deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The published deployment is unavailable for the exact origin, or the active member is not enrolled in its program.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Production is locked or the deployment's loyalty program is no longer published. No code is issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "JSON body exceeds the accepted request limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal processing error. Do not reuse or persist failed session material.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/widget-sessions/exchange": { "post": { "tags": [ "Widgets" ], "operationId": "exchangeWidgetSessionCode", "summary": "Exchange a one-time code inside the hosted iframe", "description": "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.", "servers": [ { "url": "https://widgets.loyumi.com/api/v1", "description": "Dedicated isolated Web Widget runtime origin" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionExchangeRequest" } } } }, "responses": { "201": { "description": "The code was consumed and a signed 10-minute iframe session was created with Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionExchangeResponse" } } } }, "400": { "description": "The request body or exact merchant origin is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "The code is invalid, expired, already consumed, mismatched, or no longer authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The exchange did not originate from the same-origin hosted iframe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "JSON body exceeds 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Iframe exchange velocity exceeded its limit. Honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions": { "get": { "tags": [ "Transactions" ], "operationId": "listTransactions", "summary": "List and filter posted ledger transactions", "x-required-scope": "transactions:read", "description": "List and filter posted ledger transactions. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires transactions:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "externalCustomerId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sourceReference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "committed", "reversed" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "operationId": "getTransaction", "summary": "Get a transaction and its balanced entries", "x-required-scope": "transactions:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetailOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/operations": { "get": { "tags": [ "Operations" ], "operationId": "listOperations", "summary": "List operational runs", "x-required-scope": "operations:read", "description": "List operational runs. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires operations:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/operations/{operationId}": { "get": { "tags": [ "Operations" ], "operationId": "getOperation", "summary": "Get operation progress and related import evidence", "x-required-scope": "operations:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDetailOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/audit-events": { "get": { "tags": [ "Operations" ], "operationId": "listAuditEvents", "summary": "List environment-attributed audit evidence", "x-required-scope": "audit:read", "description": "List environment-attributed audit evidence. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires audit:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "targetType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "actorId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/analytics/ledger-summary": { "get": { "tags": [ "Analytics" ], "operationId": "getLedgerAnalytics", "summary": "Get bounded descriptive ledger analytics", "x-required-scope": "analytics:read", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerAnalyticsOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhook-endpoints": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List secret-safe webhook endpoints", "x-required-scope": "webhooks:read", "description": "List secret-safe webhook endpoints. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires webhooks:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Create a disabled webhook endpoint", "x-required-scope": "webhooks:write", "description": "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.", "x-security-boundary": { "redirects": "rejected", "syntaxLayerHostnameValidation": true, "productionEgressPolicyRequired": true, "secretReplay": false }, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" } } } }, "responses": { "200": { "description": "Idempotent replay without signing secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointOutcome" } } } }, "201": { "description": "Endpoint created; signing secret returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Webhook secret encryption is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/webhook-endpoints/{endpointId}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Get a secret-safe webhook endpoint", "x-required-scope": "webhooks:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update or activate a webhook endpoint", "x-required-scope": "webhooks:write", "description": "Updates URL, supported event types, or state. A URL change forces disabled state. Requires Idempotency-Key.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdateRequest" } } } }, "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhook-endpoints/{endpointId}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Rotate once-visible signing secret and disable endpoint", "x-required-scope": "webhooks:write", "description": "Replaces the encrypted signing secret, increments its version, disables the endpoint, and returns the new secret only in the original response.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyCommand" } } } }, "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Webhook secret encryption is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/webhook-endpoints/{endpointId}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhookEndpoint", "summary": "Send an idempotent non-PII test delivery", "x-required-scope": "webhooks:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyCommand" } } } }, "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "description": "Webhook secret encryption is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/webhook-deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List PII-safe webhook delivery evidence", "x-required-scope": "webhooks:read", "description": "List PII-safe webhook delivery evidence. Results are tenant-scoped, ordered deterministically, cursor-paged, and returned with Cache-Control: no-store. Requires webhooks:read.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from the previous page; pages are ordered by timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "endpointId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "sending", "failed", "delivered", "dead_letter" ] } } ], "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhook-deliveries/{deliveryId}/retry": { "post": { "tags": [ "Webhooks" ], "operationId": "retryWebhookDelivery", "summary": "Idempotently re-queue a failed delivery", "x-required-scope": "webhooks:retry", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyCommand" } } } }, "responses": { "200": { "description": "Request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/{externalId}/programs/{programId}": { "put": { "tags": [ "Members" ], "operationId": "enrollMemberProgram", "summary": "Explicitly enroll a member in one program", "x-required-scope": "members:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberProgramEnrollmentRequest" } } } }, "responses": { "200": { "description": "Existing enrollment completed or original result replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberProgramEnrollmentOutcome" } } } }, "201": { "description": "Program profile or available account created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberProgramEnrollmentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": [ "Members" ], "operationId": "unenrollMemberProgram", "summary": "Governedly unenroll a member from one program", "x-required-scope": "members:write", "description": "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.", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "programId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberProgramUnenrollmentRequest" } } } }, "responses": { "200": { "description": "Program enrollment removed or confirmed absent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberProgramUnenrollmentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/reports/ledger-close": { "get": { "tags": [ "Analytics" ], "operationId": "getLedgerCloseReport", "summary": "Generate exact program-period ledger close evidence", "description": "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.", "x-required-scope": "analytics:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "programId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive ISO-8601 start. Defaults to the first instant of the UTC month containing to.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Exclusive ISO-8601 end. Defaults to the current instant.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Exact ledger close control evidence generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCloseReportOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-member-link-challenges": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerMemberLinkChallenge", "summary": "Create a consent-bound opaque source member challenge", "description": "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.", "x-required-scope": "exchanges:member-link", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "agreementId", "sourceExternalCustomerId", "consentReference" ], "properties": { "agreementId": { "type": "string", "minLength": 1 }, "sourceExternalCustomerId": { "type": "string", "minLength": 1 }, "consentReference": { "type": "string", "minLength": 1, "maxLength": 500 } } } } } }, "responses": { "201": { "description": "One-time source member-link challenge returned once with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerMemberLinkChallengeOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-agreements/{agreementId}/reject": { "post": { "tags": [ "Partners" ], "operationId": "rejectPartnerAgreement", "summary": "Reject an exact proposed agreement as the destination", "description": "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.", "x-required-scope": "partners:approve", "x-corrective-while-production-locked": true, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementRejectRequest" } } } }, "responses": { "200": { "description": "Exact lifecycle transition committed or replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementLifecycleOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-agreements/{agreementId}/withdraw": { "post": { "tags": [ "Partners" ], "operationId": "withdrawPartnerAgreement", "summary": "Withdraw an exact proposed agreement as the source", "description": "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.", "x-required-scope": "partners:write", "x-corrective-while-production-locked": true, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementWithdrawRequest" } } } }, "responses": { "200": { "description": "Exact lifecycle transition committed or replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementLifecycleOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-agreements/{agreementId}/pause": { "post": { "tags": [ "Partners" ], "operationId": "pausePartnerAgreement", "summary": "Emergency-pause an active agreement", "description": "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.", "x-required-scope": "partners:manage", "x-corrective-while-production-locked": true, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementPauseRequest" } } } }, "responses": { "200": { "description": "Exact lifecycle transition committed or replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementLifecycleOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-agreements/{agreementId}/resume": { "post": { "tags": [ "Partners" ], "operationId": "resumePartnerAgreement", "summary": "Resume a paused agreement with explicit approval evidence", "description": "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.", "x-required-scope": "partners:manage", "x-corrective-while-production-locked": false, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementResumeRequest" } } } }, "responses": { "200": { "description": "Exact lifecycle transition committed or replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementLifecycleOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-agreements/{agreementId}/terminate": { "post": { "tags": [ "Partners" ], "operationId": "terminatePartnerAgreement", "summary": "Permanently terminate an agreement", "description": "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.", "x-required-scope": "partners:manage", "x-corrective-while-production-locked": true, "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "agreementId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementTerminateRequest" } } } }, "responses": { "200": { "description": "Exact lifecycle transition committed or replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAgreementLifecycleOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/partner-exchange-confirmations": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerExchangeConfirmation", "summary": "Issue the one-use assertion for an approved exchange intent", "description": "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.", "x-authentication": "prelinked_verified_provider_approval_v1", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeConfirmationRequest" } } } }, "responses": { "201": { "description": "One short-lived customer assertion returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeConfirmationOutcome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-receipts/{quoteId}": { "get": { "tags": [ "Partners" ], "operationId": "getPartnerExchangeReceipt", "summary": "Read a customer-safe authoritative exchange receipt", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Customer-safe authoritative receipt returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerReceiptOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-approval-intents": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerExchangeApprovalIntent", "summary": "Start or recover an exact quote-approval intent", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentRequest" } } } }, "responses": { "200": { "description": "Existing exact intent recovered after an ambiguous response or Widget refresh.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentOutcome" } } } }, "201": { "description": "Quote-bound approval intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-approval-intents/{intentId}": { "get": { "tags": [ "Partners" ], "operationId": "getPartnerExchangeApprovalIntent", "summary": "Poll authoritative quote-approval status", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Authoritative approval-intent status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-approval-intents/{intentId}/step-up": { "post": { "tags": [ "Partners" ], "operationId": "startPartnerExchangeApprovalProviderAuthorization", "summary": "Start a new provider authorization for an exact quote", "description": "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.", "x-authentication": "opaque_intent_same_origin", "x-browser-only": true, "security": [], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Provider authorization callback created with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeProviderStepUpOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-approval-intents/{intentId}/approve": { "post": { "tags": [ "Partners" ], "operationId": "approvePartnerExchangeQuote", "summary": "Explicitly approve the immutable quote after provider authorization", "description": "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.", "x-authentication": "prelinked_verified_provider_approval_v1", "x-browser-only": true, "security": [ { "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerActionRequest" } } } }, "responses": { "200": { "description": "Exact prior approval replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentOutcome" } } } }, "201": { "description": "Exact quote approved without moving value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerExchangeCustomerLinkIntent", "summary": "Start, recover, or read Customer Verification prelink status", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Current link status or exact existing intent returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkOutcome" } } } }, "201": { "description": "Customer-link intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/revocations": { "post": { "tags": [ "Partners" ], "operationId": "createPartnerExchangeCustomerLinkRevocationIntent", "summary": "Start or recover customer-controlled unlink", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Existing exact unlink intent recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkRevocationStartOutcome" } } } }, "201": { "description": "Unlink intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkRevocationStartOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/{intentId}": { "get": { "tags": [ "Partners" ], "operationId": "getPartnerExchangeCustomerLinkIntent", "summary": "Poll customer-link or unlink status", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Authoritative link status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/{intentId}/step-up": { "post": { "tags": [ "Partners" ], "operationId": "startPartnerExchangeCustomerLinkProviderAuthorization", "summary": "Start a new provider authorization for link or unlink", "description": "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.", "x-authentication": "opaque_intent_same_origin", "x-browser-only": true, "security": [], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeProviderStepUpRequest" } } } }, "responses": { "200": { "description": "Provider authorization callback created with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeProviderStepUpOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/{intentId}/complete": { "post": { "tags": [ "Partners" ], "operationId": "completePartnerExchangeCustomerLink", "summary": "Create a durable Customer Verification link", "description": "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.", "x-authentication": "verified_provider_customer_session", "x-browser-only": true, "security": [ { "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerActionRequest" } } } }, "responses": { "200": { "description": "Exact completed link replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkOutcome" } } } }, "201": { "description": "Customer link created; Production activation remains cooling-period gated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/{intentId}/revoke": { "post": { "tags": [ "Partners" ], "operationId": "revokePartnerExchangeCustomerLink", "summary": "Customer-control unlink the exact provider link", "description": "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.", "x-authentication": "verified_provider_customer_session", "x-browser-only": true, "security": [ { "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerActionRequest" } } } }, "responses": { "200": { "description": "Customer link revoked or exact prior result replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeCustomerLinkRevokedOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/partner-exchange-customer-links/governed-revocations": { "post": { "tags": [ "Partners" ], "operationId": "governedRevokePartnerExchangeCustomerLink", "summary": "Governed revoke-only recovery after the linked provider is lost", "description": "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.", "x-required-scope": "members:delete", "x-credential-authority-zone": "identity", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeGovernedLinkRevocationRequest" } } } }, "responses": { "200": { "description": "Customer Verification revoked or the exact receipt replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerExchangeGovernedLinkRevocationOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/reward-gift-quotes": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftQuote", "summary": "Quote one recipient-bound catalog reward gift", "description": "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.", "x-required-scope": "gifts:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftQuoteRequest" } } } }, "responses": { "200": { "description": "Exact quote replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftQuoteOutcome" } } } }, "201": { "description": "Exact gift quote created without reserving value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftQuoteOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGift", "summary": "Reserve an independently approved reward gift", "description": "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.", "x-required-scope": "gifts:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftCreateRequest" } } } }, "responses": { "200": { "description": "Exact reservation replayed with the same private claim capability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftCreateOutcome" } } } }, "201": { "description": "Gift value and inventory reserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftCreateOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } }, "get": { "tags": [ "Gifts" ], "operationId": "listRewardGifts", "summary": "List durable reward gifts for reconciliation", "description": "Returns tenant-scoped, deterministic cursor pages without claim tokens, browser handoffs, provider fulfillment references, member IDs, or other authority material.", "x-required-scope": "gifts:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page; pages are ordered by creation timestamp then ID descending.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_claim", "fulfilled", "declined", "cancelled", "expired", "reversed" ] } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "senderExternalCustomerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 320 } }, { "name": "recipientExternalCustomerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 320 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Reward gifts returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts/{giftId}": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGift", "summary": "Read the authoritative merchant reward-gift receipt", "description": "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.", "x-required-scope": "gifts:read", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Authoritative gift receipt returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-claim-handoffs": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftClaimHandoff", "summary": "Convert a server-held claim token into a one-use browser handoff", "description": "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.", "x-required-scope": "gifts:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimHandoffRequest" } } } }, "responses": { "200": { "description": "Exact replay returned the same still-live one-use handoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimHandoffReplayOutcome" } } } }, "201": { "description": "A new one-use recipient handoff generation was issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimHandoffOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-claim-handoffs/exchange": { "post": { "tags": [ "Gifts" ], "operationId": "exchangeRewardGiftClaimHandoff", "summary": "Exchange a one-use recipient handoff for a closure-only gift session", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimHandoffExchangeRequest" } } } }, "responses": { "201": { "description": "Gift-scoped recipient claim session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimSessionOutcome" } } }, "headers": { "Cache-Control": { "required": true, "schema": { "type": "string", "const": "no-store" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" }, "x-trusted-frame-only": true } }, "/reward-gift-approvals": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftApprovalIntent", "summary": "Start or recover exact sender gift approval", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentRequest" } } } }, "responses": { "200": { "description": "Existing exact approval intent recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentOutcome" } } } }, "201": { "description": "Quote-bound sender approval intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-approvals/{intentId}": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGiftApprovalIntent", "summary": "Poll authoritative sender approval status", "description": "Returns only the current quote-bound approval status for the verified linked sender.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Approval status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-approvals/{intentId}/step-up": { "post": { "tags": [ "Gifts" ], "operationId": "startRewardGiftApprovalProviderAuthorization", "summary": "Start fresh provider authorization for sender approval", "description": "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.", "x-authentication": "opaque_intent_same_origin", "x-browser-only": true, "security": [], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Provider authorization callback created with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftProviderStepUpOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-approvals/{intentId}/approve": { "post": { "tags": [ "Gifts" ], "operationId": "approveRewardGiftQuote", "summary": "Explicitly approve the exact gift quote after provider step-up", "description": "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.", "x-authentication": "prelinked_verified_provider_approval_v1", "x-browser-only": true, "security": [ { "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftExplicitActionRequest" } } } }, "responses": { "200": { "description": "Exact prior approval returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentOutcome" } } } }, "201": { "description": "Exact immutable gift quote approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftApprovalIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-claims/{giftId}": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGiftClaim", "summary": "Read the intended recipient gift projection", "description": "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.", "x-authentication": "widget_member_session_and_gift_session_header", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [], "rewardGiftClaimSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Private recipient gift projection returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftClaimOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" }, "x-trusted-frame-only": true } }, "/reward-gift-claims/{giftId}/accept": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftAcceptanceIntent", "summary": "Start acceptance for the exact recipient gift", "description": "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.", "x-authentication": "widget_member_session_and_gift_session_header", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [], "rewardGiftClaimSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftAcceptanceRequest" } } } }, "responses": { "200": { "description": "Existing exact decision intent recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "201": { "description": "Recipient decision intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" }, "x-trusted-frame-only": true } }, "/reward-gift-claims/{giftId}/decline": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftDeclineIntent", "summary": "Start decline for the exact recipient gift", "description": "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.", "x-authentication": "widget_member_session_and_gift_session_header", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [], "rewardGiftClaimSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDecisionRequest" } } } }, "responses": { "200": { "description": "Existing exact decision intent recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "201": { "description": "Recipient decision intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" }, "x-trusted-frame-only": true } }, "/reward-gifts/{giftId}/cancel": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftCancellationIntent", "summary": "Start sender cancellation for a pending gift", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDecisionRequest" } } } }, "responses": { "200": { "description": "Existing exact cancellation intent recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "201": { "description": "Sender cancellation intent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-actions/{intentId}": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGiftActionIntent", "summary": "Poll authoritative accept, decline, or cancel status", "description": "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.", "x-authentication": "widget_member_session", "x-required-widget-permission": "rewards:redeem", "x-browser-only": true, "security": [ { "widgetSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Gift action status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionIntentOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" }, "x-recipient-additional-authentication": "rewardGiftClaimSessionAuth" } }, "/reward-gift-actions/{intentId}/step-up": { "post": { "tags": [ "Gifts" ], "operationId": "startRewardGiftActionProviderAuthorization", "summary": "Start fresh provider authorization for a gift decision", "description": "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.", "x-authentication": "opaque_intent_same_origin", "x-browser-only": true, "security": [], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Provider authorization callback created with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftProviderStepUpOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-actions/{intentId}/complete": { "post": { "tags": [ "Gifts" ], "operationId": "completeRewardGiftAction", "summary": "Explicitly complete verified acceptance, decline, or cancellation", "description": "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.", "x-authentication": "prelinked_verified_provider_approval_v1", "x-browser-only": true, "security": [ { "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "intentId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftExplicitActionRequest" } } } }, "responses": { "200": { "description": "Exact prior terminal decision returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionOutcome" } } } }, "201": { "description": "Verified terminal gift decision committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftActionOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts/{giftId}/recover": { "post": { "tags": [ "Gifts" ], "operationId": "recoverRewardGift", "summary": "Governed post-acceptance gift reversal", "description": "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.", "x-required-scope": "gifts:reverse", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftRecoveryRequest" } } } }, "responses": { "200": { "description": "Exact governed reversal replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftRecoveryOutcome" } } } }, "201": { "description": "Governed gift reversal committed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftRecoveryOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts/{giftId}/fulfillment-events": { "post": { "tags": [ "Gifts" ], "operationId": "recordRewardGiftFulfillmentCancellation", "summary": "Record reward-entitlement cancellation evidence", "description": "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.", "x-required-scope": "fulfillments:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftFulfillmentCancellationRequest" } } } }, "responses": { "200": { "description": "Cancellation evidence recorded or exactly replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftFulfillmentCancellationOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts/{giftId}/disputes": { "post": { "tags": [ "Gifts" ], "operationId": "openRewardGiftDispute", "summary": "Open an independently governed reward-gift dispute", "description": "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.", "x-required-scope": "disputes:write", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDisputeRequest" } } } }, "responses": { "200": { "description": "Exact dispute replayed idempotently.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDisputeOutcome" } } } }, "201": { "description": "Reward-gift dispute opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDisputeOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-disputes/{disputeId}/resolve": { "post": { "tags": [ "Gifts" ], "operationId": "resolveRewardGiftDispute", "summary": "Resolve or reject an open reward-gift dispute", "description": "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.", "x-required-scope": "disputes:resolve", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "disputeId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDisputeResolutionRequest" } } } }, "responses": { "200": { "description": "Dispute resolved, rejected, or exactly replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftDisputeOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitations": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftInvitation", "summary": "Create a durable personalized reward-gift invitation", "description": "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.", "x-required-scope": "gifts:write", "x-credential-authority-zone": "value", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationCreateRequest" } } } }, "responses": { "200": { "description": "Exact invitation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationOutcome" } } } }, "202": { "description": "Invitation durably accepted for readiness or sender approval.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } }, "get": { "tags": [ "Gifts" ], "operationId": "listRewardGiftInvitations", "summary": "List durable reward-gift invitations", "description": "Returns cursor-paged invitation, readiness, option, and delivery evidence without member IDs, contact addresses, claim capabilities, provider secrets, or customer-session authority.", "x-required-scope": "gifts:read", "x-credential-authority-zone": "value", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "onboarding", "ready", "quoted", "reserved", "accepted", "declined", "cancelled", "expired", "reversed", "revoked" ] } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Invitations returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationListOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitations/{invitationId}": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGiftInvitation", "summary": "Read one authoritative reward-gift invitation", "description": "Returns the current invitation, readiness, choices, and delivery evidence. The response is no-store and contains only opaque destination/provider references.", "x-required-scope": "gifts:read", "x-credential-authority-zone": "value", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/requestId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Invitation returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitations/{invitationId}/readiness": { "post": { "tags": [ "Gifts" ], "operationId": "refreshRewardGiftInvitationReadiness", "summary": "Refresh recipient readiness for an invitation", "description": "Re-evaluates enrollment, provider verification, identity cooling, and option compatibility without reserving value or promising an outcome.", "x-required-scope": "gifts:write", "x-credential-authority-zone": "value", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationReadinessRequest" } } } }, "responses": { "200": { "description": "Readiness returned or exactly replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationReadinessOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitations/{invitationId}/deliveries": { "post": { "tags": [ "Gifts" ], "operationId": "scheduleRewardGiftInvitationDelivery", "summary": "Schedule a purpose-bound invitation delivery", "description": "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.", "x-required-scope": "gifts:delivery", "x-credential-authority-zone": "delivery", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryRequest" } } } }, "responses": { "200": { "description": "Exact delivery schedule replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryOutcome" } } } }, "201": { "description": "Delivery attempt scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitations/{invitationId}/arrivals": { "post": { "tags": [ "Gifts" ], "operationId": "createRewardGiftInvitationArrival", "summary": "Create a just-in-time recipient arrival handoff", "description": "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.", "x-required-scope": "gifts:write", "x-credential-authority-zone": "value", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationArrivalRequest" } } } }, "responses": { "200": { "description": "Exact still-live arrival generation replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationArrivalOutcome" } } } }, "201": { "description": "Just-in-time arrival handoff created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationArrivalOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-invitation-deliveries/{deliveryId}/events": { "post": { "tags": [ "Gifts" ], "operationId": "recordRewardGiftInvitationDeliveryEvent", "summary": "Record provider delivery outcome evidence", "description": "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.", "x-required-scope": "gifts:delivery", "x-credential-authority-zone": "delivery", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryEventRequest" } } } }, "responses": { "200": { "description": "Delivery outcome recorded or exactly replayed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftInvitationDeliveryEventOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gift-wallet": { "get": { "tags": [ "Gifts" ], "operationId": "getRewardGiftWallet", "summary": "Read a participant's first-party sent or received gift wallet", "description": "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.", "x-browser-only": true, "x-hosted-popup-only": true, "x-required-widget-permission": "rewards:redeem", "security": [ { "widgetSessionAuth": [], "customerSessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "name": "view", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "sent", "received" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "200": { "description": "First-party wallet page returned with no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftWalletOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } }, "/reward-gifts/{giftId}/use-events": { "post": { "tags": [ "Gifts" ], "operationId": "recordRewardGiftEntitlementUse", "summary": "Record the single recipient-bound entitlement use", "description": "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.", "x-required-scope": "fulfillments:write", "x-credential-authority-zone": "fulfillment", "parameters": [ { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/idempotency" }, { "$ref": "#/components/parameters/requestId" }, { "name": "giftId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftEntitlementUseRequest" } } } }, "responses": { "200": { "description": "Exact entitlement-use replay returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftEntitlementUseOutcome" } } } }, "201": { "description": "Entitlement use recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardGiftEntitlementUseOutcome" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/IdempotencyReceiptPrivacyScrubbed" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "externalDocs": { "description": "Reward Gifts integration and security guide", "url": "https://app.loyumi.com/docs/reward-gifts" } } } } }