{ "openapi": "3.0.0", "info": { "title": "Reward Loyalty Agent API", "description": "Machine-to-machine API for AI agents, POS systems, and automation platforms. Authenticate with X-Agent-Key header. See https://rewardloyalty.co/docs/agent-api/overview for full documentation.", "version": "1.0.0" }, "servers": [ { "url": "/api/agent/v1", "description": "Agent API v1" } ], "paths": { "/admin/members": { "get": { "tags": [ "Admin / Members" ], "summary": "List all members platform-wide", "description": "Returns paginated members across all partners. Supports search and active filtering. Admin-only.", "operationId": "admin_list_members", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name, email, or unique identifier", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of members", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:members" ] } }, "/admin/members/{id}": { "get": { "tags": [ "Admin / Members" ], "summary": "Get member details with card balances", "description": "Returns member details with their card enrollments and point balances. Admin-only.", "operationId": "admin_get_member", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member details with card balances", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/AdminMemberDetail" } }, "type": "object" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:members" ] } }, "/admin/analytics/overview": { "get": { "tags": [ "Admin / Analytics" ], "summary": "Get platform-wide analytics", "description": "Returns aggregated platform metrics including partner, member, and transaction counts.", "operationId": "admin_analytics_overview", "responses": { "200": { "description": "Platform analytics", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/AnalyticsOverview" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:analytics" ] } }, "/admin/analytics/partners/{id}": { "get": { "tags": [ "Admin / Analytics" ], "summary": "Get per-partner analytics", "description": "Returns usage metrics for a specific partner.", "operationId": "admin_partner_metrics", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Partner analytics", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:analytics" ] } }, "/admin/partners": { "get": { "tags": [ "Admin / Partners" ], "summary": "List all partners", "description": "Returns paginated partners with optional filters. Admin-only endpoint.", "operationId": "admin_list_partners", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search by name or email", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of partners", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:partners" ] } }, "/admin/partners/{id}": { "get": { "tags": [ "Admin / Partners" ], "summary": "Get a specific partner with permissions and usage", "description": "Returns partner details including permissions, limits, and usage counts.", "operationId": "admin_get_partner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Partner details with permissions and usage", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/PartnerDetail" } }, "type": "object" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read:partners" ] } }, "/admin/partners/{id}/permissions": { "patch": { "tags": [ "Admin / Partners" ], "summary": "Update partner permissions and limits", "description": "Updates feature flags and resource limits for a partner.", "operationId": "admin_update_partner_permissions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "loyalty_cards_permission": { "type": "boolean" }, "loyalty_cards_limit": { "description": "-1 = unlimited", "type": "integer", "minimum": -1 }, "stamp_cards_permission": { "type": "boolean" }, "stamp_cards_limit": { "type": "integer", "minimum": -1 }, "vouchers_permission": { "type": "boolean" }, "voucher_batches_permission": { "type": "boolean" }, "vouchers_limit": { "type": "integer", "minimum": -1 }, "rewards_limit": { "type": "integer", "minimum": -1 }, "staff_members_limit": { "type": "integer", "minimum": -1 }, "email_campaigns_permission": { "type": "boolean" }, "activity_permission": { "type": "boolean" }, "agent_api_permission": { "type": "boolean" }, "agent_keys_limit": { "type": "integer", "minimum": -1 }, "cards_on_homepage": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Permissions updated — returns the full permission set after save", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/PartnerPermissions" } }, "type": "object" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Validation error or empty body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:partners" ] } }, "/admin/partners/{id}/activate": { "post": { "tags": [ "Admin / Partners" ], "summary": "Activate a partner", "description": "Reactivates a previously deactivated partner.", "operationId": "admin_activate_partner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Partner activated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:partners" ] } }, "/admin/partners/{id}/deactivate": { "post": { "tags": [ "Admin / Partners" ], "summary": "Deactivate a partner", "description": "Deactivates a partner. All associated agent keys become invalid.", "operationId": "admin_deactivate_partner", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Partner deactivated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:partners" ] } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Check API health and key identity", "description": "Returns the authenticated key's identity, role, scopes, rate limit, and owner information. Use this as a connectivity and configuration check before calling business endpoints.", "operationId": "check_health", "responses": { "200": { "description": "Key is valid and active", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/HealthResponse" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired key" } }, "security": [ { "AgentKey": [] } ] } }, "/tools": { "get": { "tags": [ "Tools" ], "summary": "Discover available API tools for this key", "description": "Returns tool definitions scoped to the authenticated key's role and permissions. Use the format parameter to get definitions compatible with your agent framework. This endpoint is excluded from its own tool list.", "operationId": "discover_tools", "parameters": [ { "name": "format", "in": "query", "description": "Output format for tool definitions", "required": false, "schema": { "type": "string", "default": "generic", "enum": [ "openai", "anthropic", "mcp", "generic" ] } } ], "responses": { "200": { "description": "Tool definitions for the authenticated key", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "tools": { "description": "Framework-specific tool definitions", "type": "array", "items": { "type": "object" } }, "meta": { "properties": { "role": { "type": "string" }, "format": { "type": "string" }, "tool_count": { "type": "integer" }, "cached": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Partner API access revoked (agent_api_permission disabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Invalid format parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "503": { "description": "Tool definitions not yet available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [] } }, "/member/balance": { "get": { "tags": [ "Member / Wallet" ], "summary": "Get all card balances for this member", "description": "Returns the member's point balance across all enrolled loyalty cards in one call.", "operationId": "member_get_balance", "responses": { "200": { "description": "Card balances", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "properties": { "card_id": { "type": "string", "format": "uuid" }, "card_title": { "type": "string" }, "balance": { "type": "integer" }, "currency": { "type": "string", "example": "points" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/cards": { "get": { "tags": [ "Member / Wallet" ], "summary": "List all enrolled loyalty cards", "description": "Returns paginated loyalty cards that the member has transacted with.", "operationId": "member_list_cards", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of enrolled cards", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberCard" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/cards/{id}": { "get": { "tags": [ "Member / Wallet" ], "summary": "Get a single enrolled loyalty card", "description": "Returns a card's details and the member's balance on it.", "operationId": "member_get_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Card details with balance", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/MemberCard" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/transactions": { "get": { "tags": [ "Member / Wallet" ], "summary": "Get transaction history across all cards", "description": "Returns paginated transaction history for the authenticated member.", "operationId": "member_list_transactions", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated transaction history", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberTransaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/transactions/{cardId}": { "get": { "tags": [ "Member / Wallet" ], "summary": "Get transaction history for a specific card", "description": "Returns paginated transaction history for the member on a specific enrolled card.", "operationId": "member_card_transactions", "parameters": [ { "name": "cardId", "in": "path", "description": "Loyalty card UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated transaction history", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberTransaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/discover": { "get": { "tags": [ "Member / Discover" ], "summary": "Browse discoverable loyalty cards, stamp cards, and vouchers", "description": "Returns all cards visible on the homepage. Includes loyalty cards, stamp cards, and vouchers that are active and visible by default.", "operationId": "member_discover", "responses": { "200": { "description": "Discoverable cards grouped by type", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "cards": { "type": "array", "items": { "type": "object" } }, "stamp_cards": { "type": "array", "items": { "type": "object" } }, "vouchers": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/discover/resolve": { "post": { "tags": [ "Member / Discover" ], "summary": "Resolve a card URL or identifier to its details", "description": "Accepts a QR code URL, UUID, or unique identifier and returns the corresponding card details. Primary endpoint for QR code scanning.", "operationId": "member_resolve_card", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "url": { "description": "Full URL from a QR code or shared link", "type": "string" }, "identifier": { "description": "UUID or unique identifier (alternative to url)", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Resolved card details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Missing input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/discover/follow": { "post": { "tags": [ "Member / Discover" ], "summary": "Save a card to My Cards (follow)", "description": "Saves a loyalty card to the member's collection. Idempotent — following an already-followed card is a no-op.", "operationId": "member_follow_card", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "card_id" ], "properties": { "card_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "Card followed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:profile" ] } }, "/member/discover/unfollow": { "post": { "tags": [ "Member / Discover" ], "summary": "Remove a card from My Cards (unfollow)", "description": "Removes a loyalty card from the member's collection.", "operationId": "member_unfollow_card", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "card_id" ], "properties": { "card_id": { "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "Card unfollowed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "object" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:profile" ] } }, "/member/rewards": { "get": { "tags": [ "Member / Rewards" ], "summary": "List available rewards for this member", "description": "Returns rewards available on the member's enrolled cards with affordability info.", "operationId": "member_list_rewards", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of available rewards", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/member/rewards/{id}/claim": { "post": { "tags": [ "Member / Rewards" ], "summary": "Submit a reward claim request", "description": "Submits a claim for a reward. Does NOT deduct points directly — staff must confirm via the dashboard or partner API.", "operationId": "member_claim_reward", "parameters": [ { "name": "id", "in": "path", "description": "Reward UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Claim submitted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "status": { "type": "string", "example": "claim_submitted" }, "reward_id": { "type": "string", "format": "uuid" }, "points_required": { "type": "integer" }, "current_balance": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Reward not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Insufficient balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:redeem" ] } }, "/member/profile": { "get": { "tags": [ "Member / Profile" ], "summary": "Get the authenticated member's profile", "description": "Returns the member's own profile including name, email, locale, avatar, and interaction status.", "operationId": "member_get_profile", "responses": { "200": { "description": "Member profile", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/MemberProfile" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] }, "put": { "tags": [ "Member / Profile" ], "summary": "Update the authenticated member's profile", "description": "Updates limited profile fields (name, locale). Email cannot be changed via agent API.", "operationId": "member_update_profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 200 }, "locale": { "description": "Locale code (e.g. en_US, nl_NL)", "type": "string", "example": "en_US" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/MemberProfile" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:profile" ] } }, "/partner/cards": { "get": { "tags": [ "Partner / Loyalty Cards" ], "summary": "List all loyalty cards for this partner", "description": "Returns paginated loyalty cards owned by the authenticated partner. Supports pagination via page and per_page query parameters.", "operationId": "list_loyalty_cards", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of loyalty cards", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyCard" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope or feature disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:cards" ], "x-agent-permission": "loyalty_cards_permission" }, "post": { "tags": [ "Partner / Loyalty Cards" ], "summary": "Create a new loyalty card", "description": "Creates a loyalty card with the specified points economy configuration. Requires the club_id of an existing club owned by this partner.", "operationId": "create_loyalty_card", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "club_id", "name", "currency", "points_per_currency", "currency_unit_amount", "min_points_per_purchase", "max_points_per_purchase", "points_expiration_months" ], "properties": { "club_id": { "description": "Club this card belongs to", "type": "string", "format": "uuid" }, "name": { "description": "Internal name (not shown to members)", "type": "string", "maxLength": 250 }, "head": { "description": "Translatable header text", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "currency": { "description": "ISO 4217 currency code", "type": "string", "maxLength": 3, "minLength": 3, "example": "EUR" }, "points_per_currency": { "type": "number", "maximum": 100000, "minimum": 0 }, "currency_unit_amount": { "type": "number", "maximum": 1000000, "minimum": 1 }, "min_points_per_purchase": { "type": "number", "maximum": 10000000, "minimum": 0 }, "max_points_per_purchase": { "type": "number", "maximum": 10000000, "minimum": 0 }, "initial_bonus_points": { "type": "number", "maximum": 10000000, "minimum": 0 }, "points_expiration_months": { "type": "number", "maximum": 1200, "minimum": 1 }, "is_active": { "type": "boolean", "default": true }, "bg_color": { "type": "string", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$", "example": "#4F46E5" } }, "type": "object" } } } }, "responses": { "201": { "description": "Card created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/LoyaltyCard" } }, "type": "object" } } } }, "422": { "description": "Validation error or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:cards" ], "x-agent-permission": "loyalty_cards_permission" } }, "/partner/cards/{id}": { "get": { "tags": [ "Partner / Loyalty Cards" ], "summary": "Get a specific loyalty card", "description": "Returns a single loyalty card by ID. The card must belong to the authenticated partner.", "operationId": "get_loyalty_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Loyalty card details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/LoyaltyCard" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:cards" ], "x-agent-permission": "loyalty_cards_permission" }, "put": { "tags": [ "Partner / Loyalty Cards" ], "summary": "Update an existing loyalty card", "description": "Updates a loyalty card owned by the authenticated partner. Only provided fields are updated.", "operationId": "update_loyalty_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 250 }, "head": { "description": "Translatable header text", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "currency": { "type": "string", "maxLength": 3, "minLength": 3 }, "points_per_currency": { "type": "number", "maximum": 100000, "minimum": 0 }, "currency_unit_amount": { "type": "number", "maximum": 1000000, "minimum": 1 }, "min_points_per_purchase": { "type": "number", "maximum": 10000000, "minimum": 0 }, "max_points_per_purchase": { "type": "number", "maximum": 10000000, "minimum": 0 }, "initial_bonus_points": { "type": "number", "maximum": 10000000, "minimum": 0 }, "points_expiration_months": { "type": "number", "maximum": 1200, "minimum": 1 }, "is_active": { "type": "boolean" }, "bg_color": { "type": "string", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } }, "type": "object" } } } }, "responses": { "200": { "description": "Card updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/LoyaltyCard" } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:cards" ], "x-agent-permission": "loyalty_cards_permission" }, "delete": { "tags": [ "Partner / Loyalty Cards" ], "summary": "Delete a loyalty card", "description": "Permanently deletes a loyalty card owned by the authenticated partner.", "operationId": "delete_loyalty_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Card deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Card deleted." } }, "type": "object" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:cards" ], "x-agent-permission": "loyalty_cards_permission" } }, "/partner/clubs": { "get": { "tags": [ "Partner / Clubs" ], "summary": "List all clubs for this partner", "description": "Returns paginated clubs owned by the authenticated partner.", "operationId": "list_clubs", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of clubs", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Club" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:clubs" ] }, "post": { "tags": [ "Partner / Clubs" ], "summary": "Create a new club", "description": "Creates a club owned by the authenticated partner.", "operationId": "create_club", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Club name", "type": "string", "maxLength": 120 }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Club created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Club" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:clubs" ] } }, "/partner/clubs/{id}": { "get": { "tags": [ "Partner / Clubs" ], "summary": "Get a specific club", "description": "Returns a single club by ID. The club must belong to the authenticated partner.", "operationId": "get_club", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Club details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Club" } }, "type": "object" } } } }, "404": { "description": "Club not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:clubs" ] }, "put": { "tags": [ "Partner / Clubs" ], "summary": "Update an existing club", "description": "Updates a club owned by the authenticated partner. Only provided fields are updated.", "operationId": "update_club", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 120 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Club updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Club" } }, "type": "object" } } } }, "404": { "description": "Club not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:clubs" ] }, "delete": { "tags": [ "Partner / Clubs" ], "summary": "Delete a club", "description": "Deletes a club owned by the authenticated partner. Protected clubs cannot be deleted.", "operationId": "delete_club", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Club deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Club deleted." } }, "type": "object" } } } }, "404": { "description": "Club not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "422": { "description": "Club is protected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:clubs" ] } }, "/partner/members": { "get": { "tags": [ "Partner / Members" ], "summary": "List members who interacted with this partner", "description": "Returns paginated members that have transactions with this partner's cards. Searchable by name, email, member number, or unique identifier.", "operationId": "list_members", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Search by name, email, member number, or unique identifier", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of members", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerMemberSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/partner/members/{id}": { "get": { "tags": [ "Partner / Members" ], "summary": "Get a specific member", "description": "Returns member details. Accepts UUID as path parameter. Member must have interacted with this partner's cards.", "operationId": "get_member", "parameters": [ { "name": "id", "in": "path", "description": "Member UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/PartnerMemberSummary" } }, "type": "object" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/partner/members/{id}/balance/{cardId}": { "get": { "tags": [ "Partner / Members" ], "summary": "Get a member's balance on a specific card", "description": "Returns the member's point balance for a specific loyalty card. Both the member and card must belong to this partner.", "operationId": "get_member_balance", "parameters": [ { "name": "id", "in": "path", "description": "Member UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cardId", "in": "path", "description": "Loyalty card UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member balance on card", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "member_id": { "type": "string", "format": "uuid" }, "card_id": { "type": "string", "format": "uuid" }, "balance": { "type": "integer" }, "currency": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Member or card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read" ] } }, "/partner/rewards": { "get": { "tags": [ "Partner / Rewards" ], "summary": "List all rewards for this partner", "description": "Returns paginated rewards owned by the authenticated partner. Requires loyalty cards feature to be enabled.", "operationId": "list_rewards", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of rewards", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reward" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope or feature disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:rewards" ], "x-agent-permission": "loyalty_cards_permission" }, "post": { "tags": [ "Partner / Rewards" ], "summary": "Create a new reward", "description": "Creates a reward that members can claim by spending loyalty points.", "operationId": "create_reward", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "points" ], "properties": { "name": { "description": "Internal reward name", "type": "string", "maxLength": 120 }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "points": { "description": "Points required to claim this reward", "type": "number", "maximum": 10000000, "minimum": 0 }, "active_from": { "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Reward created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Reward" } }, "type": "object" } } } }, "422": { "description": "Validation error or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:rewards" ], "x-agent-permission": "loyalty_cards_permission" } }, "/partner/rewards/{id}": { "get": { "tags": [ "Partner / Rewards" ], "summary": "Get a specific reward", "description": "Returns a single reward by ID. The reward must belong to the authenticated partner.", "operationId": "get_reward", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reward details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Reward" } }, "type": "object" } } } }, "404": { "description": "Reward not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:rewards" ], "x-agent-permission": "loyalty_cards_permission" }, "put": { "tags": [ "Partner / Rewards" ], "summary": "Update an existing reward", "description": "Updates a reward owned by the authenticated partner. Only provided fields are updated.", "operationId": "update_reward", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 120 }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "points": { "type": "number", "maximum": 10000000, "minimum": 0 }, "active_from": { "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Reward" } }, "type": "object" } } } }, "404": { "description": "Reward not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:rewards" ], "x-agent-permission": "loyalty_cards_permission" }, "delete": { "tags": [ "Partner / Rewards" ], "summary": "Delete a reward", "description": "Permanently deletes a reward owned by the authenticated partner.", "operationId": "delete_reward", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reward deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Reward deleted." } }, "type": "object" } } } }, "404": { "description": "Reward not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:rewards" ], "x-agent-permission": "loyalty_cards_permission" } }, "/partner/staff": { "get": { "tags": [ "Partner / Staff" ], "summary": "List all staff members for this partner", "description": "Returns paginated staff members owned by the authenticated partner.", "operationId": "list_staff", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of staff", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMember" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:staff" ] }, "post": { "tags": [ "Partner / Staff" ], "summary": "Create a new staff member", "description": "Creates a staff member who can perform loyalty operations.", "operationId": "create_staff_member", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 120 }, "password": { "type": "string", "maxLength": 48, "minLength": 6 }, "club_id": { "description": "Assign to a specific club", "type": "string", "format": "uuid" }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Staff member created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StaffMember" } }, "type": "object" } } } }, "422": { "description": "Validation error or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:staff" ] } }, "/partner/staff/{id}": { "get": { "tags": [ "Partner / Staff" ], "summary": "Get a specific staff member", "description": "Returns a single staff member by ID.", "operationId": "get_staff_member", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staff member details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StaffMember" } }, "type": "object" } } } }, "404": { "description": "Staff member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:staff" ] }, "put": { "tags": [ "Partner / Staff" ], "summary": "Update an existing staff member", "description": "Updates a staff member owned by the authenticated partner.", "operationId": "update_staff_member", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email", "maxLength": 120 }, "password": { "type": "string", "maxLength": 48, "minLength": 6 }, "club_id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Staff member updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StaffMember" } }, "type": "object" } } } }, "404": { "description": "Staff member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:staff" ] }, "delete": { "tags": [ "Partner / Staff" ], "summary": "Delete a staff member", "description": "Permanently deletes a staff member owned by the authenticated partner.", "operationId": "delete_staff_member", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Staff member deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Staff member deleted." } }, "type": "object" } } } }, "404": { "description": "Staff member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:staff" ] } }, "/partner/stamp-cards": { "get": { "tags": [ "Partner / Stamp Cards" ], "summary": "List all stamp cards for this partner", "description": "Returns paginated stamp cards owned by the authenticated partner.", "operationId": "list_stamp_cards", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of stamp cards", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StampCard" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope or feature disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:stamps" ], "x-agent-permission": "stamp_cards_permission" }, "post": { "tags": [ "Partner / Stamp Cards" ], "summary": "Create a new stamp card", "description": "Creates a stamp card with the specified configuration. Requires stamp cards feature to be enabled.", "operationId": "create_stamp_card", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "club_id", "name", "stamps_required" ], "properties": { "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 250 }, "head": { "description": "Translatable header", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "reward_title": { "description": "Reward title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "stamps_required": { "type": "integer", "maximum": 100, "minimum": 1 }, "stamps_per_purchase": { "type": "integer", "maximum": 100, "minimum": 1 }, "max_stamps_per_transaction": { "type": "integer", "minimum": 1 }, "max_stamps_per_day": { "type": "integer", "minimum": 1 }, "stamps_expire_days": { "type": "integer", "maximum": 365, "minimum": 1 }, "min_purchase_amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "maxLength": 3, "minLength": 3 }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Stamp card created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StampCard" } }, "type": "object" } } } }, "422": { "description": "Validation error or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:stamps" ], "x-agent-permission": "stamp_cards_permission" } }, "/partner/stamp-cards/{id}": { "get": { "tags": [ "Partner / Stamp Cards" ], "summary": "Get a specific stamp card", "description": "Returns a single stamp card by ID.", "operationId": "get_stamp_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stamp card details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StampCard" } }, "type": "object" } } } }, "404": { "description": "Stamp card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:stamps" ], "x-agent-permission": "stamp_cards_permission" }, "put": { "tags": [ "Partner / Stamp Cards" ], "summary": "Update an existing stamp card", "description": "Updates a stamp card owned by the authenticated partner. Only provided fields are updated.", "operationId": "update_stamp_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 250 }, "stamps_required": { "type": "integer", "maximum": 100, "minimum": 1 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Stamp card updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/StampCard" } }, "type": "object" } } } }, "404": { "description": "Stamp card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:stamps" ], "x-agent-permission": "stamp_cards_permission" }, "delete": { "tags": [ "Partner / Stamp Cards" ], "summary": "Delete a stamp card", "description": "Permanently deletes a stamp card owned by the authenticated partner.", "operationId": "delete_stamp_card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stamp card deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Stamp card deleted." } }, "type": "object" } } } }, "404": { "description": "Stamp card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:stamps" ], "x-agent-permission": "stamp_cards_permission" } }, "/partner/stamp-cards/{id}/stamps": { "post": { "tags": [ "Partner / Stamp Cards" ], "summary": "Add stamps to a member's stamp card", "description": "Awards stamp(s) to a member on the specified stamp card. If the card is completed, a pending reward is created.", "operationId": "add_stamps", "parameters": [ { "name": "id", "in": "path", "description": "Stamp card UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_identifier" ], "properties": { "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "stamps": { "description": "Number of stamps to add", "type": "integer", "default": 1, "maximum": 100, "minimum": 1 }, "purchase_amount": { "description": "Purchase amount (for minimum purchase validation)", "type": "number", "minimum": 0 }, "note": { "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "201": { "description": "Stamp(s) added", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "stamps_added": { "type": "integer" }, "current_stamps": { "type": "integer" }, "stamps_required": { "type": "integer" }, "completed": { "type": "boolean" }, "pending_rewards": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Stamp operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:stamps" ], "x-agent-permission": "stamp_cards_permission" } }, "/partner/stamp-cards/{id}/redeem": { "post": { "tags": [ "Partner / Stamp Cards" ], "summary": "Redeem a pending stamp reward", "description": "Redeems one pending reward for a member on the specified stamp card. The member must have a completed card with an unclaimed reward.", "operationId": "redeem_stamp_reward", "parameters": [ { "name": "id", "in": "path", "description": "Stamp card UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_identifier" ], "properties": { "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "note": { "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward redeemed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "reward_title": { "type": "string" }, "reward_value": { "type": "string", "nullable": true }, "remaining_rewards": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "No pending reward or redeem failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:stamps" ], "x-agent-permission": "stamp_cards_permission" } }, "/partner/tiers": { "get": { "tags": [ "Partner / Tiers" ], "summary": "List all tiers for this partner", "description": "Returns paginated tiers owned by the authenticated partner, ordered by level.", "operationId": "list_tiers", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of tiers", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tier" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:tiers" ] }, "post": { "tags": [ "Partner / Tiers" ], "summary": "Create a new tier", "description": "Creates a loyalty tier within a club.", "operationId": "create_tier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "club_id", "name", "level" ], "properties": { "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "level": { "description": "Sort order / tier level", "type": "integer", "minimum": 0 }, "points_threshold": { "type": "integer", "minimum": 0 }, "points_multiplier": { "type": "number", "maximum": 100, "minimum": 1 }, "color": { "type": "string", "maxLength": 7, "example": "#FFD700" }, "icon": { "type": "string", "maxLength": 50 }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Tier created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Tier" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:tiers" ] } }, "/partner/tiers/{id}": { "get": { "tags": [ "Partner / Tiers" ], "summary": "Get a specific tier", "description": "Returns a single tier by ID.", "operationId": "get_tier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tier details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Tier" } }, "type": "object" } } } }, "404": { "description": "Tier not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:tiers" ] }, "put": { "tags": [ "Partner / Tiers" ], "summary": "Update an existing tier", "description": "Updates a tier owned by the authenticated partner.", "operationId": "update_tier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "level": { "type": "integer", "minimum": 0 }, "points_threshold": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tier updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Tier" } }, "type": "object" } } } }, "404": { "description": "Tier not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:tiers" ] }, "delete": { "tags": [ "Partner / Tiers" ], "summary": "Delete a tier", "description": "Permanently deletes a tier owned by the authenticated partner.", "operationId": "delete_tier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tier deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Tier deleted." } }, "type": "object" } } } }, "404": { "description": "Tier not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:tiers" ] } }, "/partner/transactions": { "get": { "tags": [ "Partner / Transactions" ], "summary": "List transactions for this partner", "description": "Returns paginated transactions with optional filters by member, card, event type, and date range.", "operationId": "list_transactions", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "member_identifier", "in": "query", "description": "Filter by member (UUID, email, member number, or unique identifier)", "required": false, "schema": { "type": "string" } }, { "name": "card_id", "in": "query", "description": "Filter by loyalty card", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "event", "in": "query", "description": "Filter by event type", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start date (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (Y-m-d)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated list of transactions", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerTransaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:transactions" ] } }, "/partner/transactions/purchase": { "post": { "tags": [ "Partner / Transactions" ], "summary": "Record a purchase and award loyalty points", "description": "Records a purchase transaction. Points awarded are calculated from the card's points_per_currency ratio, or can be set explicitly via the points parameter. The member_identifier accepts UUID, email, member number, or unique identifier.", "operationId": "record_purchase", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "card_id", "member_identifier" ], "properties": { "card_id": { "type": "string", "format": "uuid" }, "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "purchase_amount": { "description": "Required unless points is set", "type": "number", "minimum": 0.01 }, "points": { "description": "Override calculated points", "type": "integer", "minimum": 0 }, "staff_id": { "description": "Attribute to a staff member", "type": "string", "format": "uuid" }, "note": { "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "201": { "description": "Points awarded", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/PurchaseResult" } }, "type": "object" } } } }, "422": { "description": "Validation error, card inactive, or transaction failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:transactions" ] } }, "/partner/transactions/redeem": { "post": { "tags": [ "Partner / Transactions" ], "summary": "Redeem a reward and deduct loyalty points", "description": "Claims a reward for a member, deducting the required points from their balance. The reward must be linked to the specified card.", "operationId": "redeem_reward", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "card_id", "reward_id", "member_identifier" ], "properties": { "card_id": { "type": "string", "format": "uuid" }, "reward_id": { "type": "string", "format": "uuid" }, "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "staff_id": { "description": "Attribute to a staff member", "type": "string", "format": "uuid" }, "note": { "type": "string", "maxLength": 500 } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward redeemed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/RedemptionResult" } }, "type": "object" } } } }, "422": { "description": "Insufficient points, reward not linked, or redemption failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:rewards" ] } }, "/partner/vouchers": { "get": { "tags": [ "Partner / Vouchers" ], "summary": "List all vouchers for this partner", "description": "Returns paginated vouchers owned by the authenticated partner.", "operationId": "list_vouchers", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of vouchers", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voucher" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "403": { "description": "Insufficient scope or feature disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:vouchers" ], "x-agent-permission": "vouchers_permission" }, "post": { "tags": [ "Partner / Vouchers" ], "summary": "Create a new voucher", "description": "Creates a voucher with the specified type and value. If no code is provided, one is generated automatically.", "operationId": "create_voucher", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "club_id", "name", "type" ], "properties": { "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 128 }, "title": { "description": "Display title (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": { "description": "Description (translatable)", "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "code": { "description": "Voucher code (auto-generated if omitted)", "type": "string", "maxLength": 32 }, "type": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_product", "bonus_points" ] }, "value": { "description": "Discount value (required for percentage/fixed_amount)", "type": "integer", "minimum": 0 }, "currency": { "type": "string", "maxLength": 3, "minLength": 3 }, "points_value": { "description": "Points to award (for bonus_points type)", "type": "integer", "minimum": 1 }, "max_uses_total": { "type": "integer", "minimum": 1 }, "max_uses_per_member": { "type": "integer", "minimum": 1 }, "valid_from": { "type": "string", "format": "date" }, "valid_until": { "type": "string", "format": "date" }, "is_active": { "type": "boolean", "default": true }, "is_public": { "type": "boolean", "default": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Voucher created", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Voucher" } }, "type": "object" } } } }, "422": { "description": "Validation error or limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:vouchers" ], "x-agent-permission": "vouchers_permission" } }, "/partner/vouchers/{id}": { "get": { "tags": [ "Partner / Vouchers" ], "summary": "Get a specific voucher", "description": "Returns a single voucher by ID.", "operationId": "get_voucher", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Voucher details", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Voucher" } }, "type": "object" } } } }, "404": { "description": "Voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "read", "write:vouchers" ], "x-agent-permission": "vouchers_permission" }, "put": { "tags": [ "Partner / Vouchers" ], "summary": "Update an existing voucher", "description": "Updates a voucher owned by the authenticated partner. Only provided fields are updated.", "operationId": "update_voucher", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 128 }, "type": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_product", "bonus_points" ] }, "value": { "type": "integer", "minimum": 0 }, "valid_until": { "type": "string", "format": "date" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher updated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "$ref": "#/components/schemas/Voucher" } }, "type": "object" } } } }, "404": { "description": "Voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:vouchers" ], "x-agent-permission": "vouchers_permission" }, "delete": { "tags": [ "Partner / Vouchers" ], "summary": "Delete a voucher", "description": "Soft-deletes a voucher owned by the authenticated partner.", "operationId": "delete_voucher", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Voucher deleted", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Voucher deleted." } }, "type": "object" } } } }, "404": { "description": "Voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:vouchers" ], "x-agent-permission": "vouchers_permission" } }, "/partner/vouchers/validate": { "post": { "tags": [ "Partner / Vouchers" ], "summary": "Validate a voucher code without redeeming", "description": "Checks if a voucher code is valid for a member and optionally calculates the discount for a given order amount.", "operationId": "validate_voucher", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "member_identifier", "club_id" ], "properties": { "code": { "description": "Voucher code to validate", "type": "string" }, "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "club_id": { "description": "Club the voucher belongs to", "type": "string", "format": "uuid" }, "order_amount": { "description": "Order amount in cents for discount calculation", "type": "integer", "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher is valid", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "valid": { "type": "boolean", "example": true }, "voucher_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "integer" }, "discount_amount": { "type": "integer" }, "final_amount": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Voucher invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:vouchers" ], "x-agent-permission": "vouchers_permission" } }, "/partner/vouchers/{id}/redeem": { "post": { "tags": [ "Partner / Vouchers" ], "summary": "Redeem a voucher for a member", "description": "Redeems a voucher for a member, applying the discount/bonus and recording the usage. Uses transactional locking to prevent race conditions.", "operationId": "redeem_voucher", "parameters": [ { "name": "id", "in": "path", "description": "Voucher UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_identifier" ], "properties": { "member_identifier": { "description": "UUID, email, member number, or unique identifier", "type": "string" }, "order_amount": { "description": "Order amount in cents", "type": "integer", "minimum": 0 }, "order_reference": { "description": "External order reference", "type": "string", "maxLength": 64 } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher redeemed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "boolean", "example": false }, "data": { "properties": { "voucher_id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "type": { "type": "string" }, "member_id": { "type": "string", "format": "uuid" }, "discount_amount": { "type": "integer" }, "points_awarded": { "type": "integer", "nullable": true }, "remaining_uses": { "type": "integer", "nullable": true }, "redemption_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Voucher redeem failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } }, "security": [ { "AgentKey": [] } ], "x-agent-scopes": [ "write:vouchers" ], "x-agent-permission": "vouchers_permission" } } }, "components": { "schemas": { "TranslatableString": { "description": "A translatable value. String when Accept-Language is set, object of locale→value when not.", "oneOf": [ { "type": "string" }, { "type": "object", "example": { "en": "English text", "nl": "Nederlandse tekst" }, "additionalProperties": { "type": "string" } } ] }, "Club": { "description": "A club groups loyalty cards, stamp cards, and vouchers under one brand.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "LoyaltyCard": { "description": "A loyalty card defines a points economy: currency, earning rate, limits, and expiry.", "properties": { "id": { "type": "string", "format": "uuid" }, "club_id": { "type": "string", "format": "uuid" }, "name": { "description": "Internal name", "type": "string" }, "head": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "title": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "currency": { "type": "string", "maxLength": 3, "minLength": 3, "example": "EUR" }, "points_per_currency": { "type": "number" }, "currency_unit_amount": { "type": "number" }, "min_points_per_purchase": { "type": "number" }, "max_points_per_purchase": { "type": "number" }, "initial_bonus_points": { "type": "number", "nullable": true }, "points_expiration_months": { "type": "number" }, "is_active": { "type": "boolean" }, "bg_color": { "type": "string", "example": "#4F46E5", "nullable": true }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Reward": { "description": "A reward that members can claim by spending loyalty points. Linked to cards via pivot table — no card_id on the resource itself.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "description": "Internal name", "type": "string" }, "title": { "$ref": "#/components/schemas/TranslatableString" }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "points": { "description": "Points required to claim", "type": "integer" }, "active_from": { "type": "string", "format": "date", "nullable": true }, "expiration_date": { "type": "string", "format": "date", "nullable": true }, "is_active": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PartnerTransaction": { "description": "A transaction as seen from the partner perspective. Includes staff and reward attribution.", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "description": "Transaction event type (initial_bonus_points, purchase, redemption, etc.)", "type": "string" }, "points": { "type": "integer" }, "purchase_amount": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true }, "member_id": { "type": "string", "format": "uuid" }, "card_id": { "type": "string", "format": "uuid" }, "reward_id": { "type": "string", "format": "uuid", "nullable": true }, "staff_id": { "type": "string", "format": "uuid", "nullable": true }, "staff_name": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "MemberTransaction": { "description": "A transaction as seen from the member perspective. Omits internal IDs, includes display fields.", "properties": { "id": { "type": "string", "format": "uuid" }, "card_id": { "type": "string", "format": "uuid" }, "card_title": { "type": "string", "nullable": true }, "event": { "description": "Transaction event type", "type": "string" }, "points": { "type": "integer" }, "points_used": { "type": "integer", "nullable": true }, "purchase_amount": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true }, "reward_title": { "type": "string", "nullable": true }, "reward_points": { "type": "integer", "nullable": true }, "note": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "MemberSummary": { "description": "A member as seen from the admin perspective. Used by admin list/detail endpoints.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "unique_identifier": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "is_anonymous": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PartnerMemberSummary": { "description": "A member as seen from the partner perspective. Includes more profile fields than the admin view.", "properties": { "id": { "type": "string", "format": "uuid" }, "unique_identifier": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "locale": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "time_zone": { "type": "string", "nullable": true }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "avatar": { "type": "string", "nullable": true }, "is_anonymous": { "type": "boolean" } }, "type": "object" }, "StampCard": { "description": "A stamp card with a fixed number of stamp slots and a reward on completion.", "properties": { "id": { "type": "string", "format": "uuid" }, "club_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "head": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "title": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "reward_title": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "stamps_required": { "description": "Number of stamps needed to complete the card", "type": "integer", "maximum": 100, "minimum": 1 }, "stamps_per_purchase": { "type": "integer", "maximum": 100, "minimum": 1, "nullable": true }, "max_stamps_per_transaction": { "type": "integer", "nullable": true }, "max_stamps_per_day": { "type": "integer", "nullable": true }, "stamps_expire_days": { "type": "integer", "maximum": 365, "minimum": 1, "nullable": true }, "min_purchase_amount": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true }, "requires_physical_claim": { "type": "boolean" }, "is_active": { "type": "boolean" }, "bg_color": { "type": "string", "nullable": true }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Voucher": { "description": "A voucher with a code, type (discount/reward), and optional usage limits.", "properties": { "id": { "type": "string", "format": "uuid" }, "club_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "title": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "code": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number", "nullable": true }, "is_active": { "type": "boolean" }, "valid_from": { "type": "string", "format": "date-time", "nullable": true }, "valid_until": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Tier": { "description": "A loyalty tier for VIP levels based on points thresholds.", "properties": { "id": { "type": "string", "format": "uuid" }, "club_id": { "type": "string", "format": "uuid" }, "name": { "$ref": "#/components/schemas/TranslatableString" }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "level": { "description": "Sort/rank order of the tier", "type": "integer", "minimum": 0 }, "points_threshold": { "type": "integer", "minimum": 0, "nullable": true }, "points_multiplier": { "type": "number", "maximum": 100, "minimum": 1, "nullable": true }, "color": { "type": "string", "example": "#FFD700", "nullable": true }, "icon": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "StaffMember": { "description": "A staff member who can perform loyalty operations at the point of sale.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "description": "1=Owner, 2=Manager, 3=Staff", "type": "integer" }, "is_active": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PurchaseResult": { "description": "Result of a purchase transaction with points awarded.", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "points_awarded": { "type": "integer" }, "member_balance": { "type": "integer" }, "purchase_amount": { "type": "number" }, "card_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "RedemptionResult": { "description": "Result of a reward redemption with points deducted.", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "points_deducted": { "type": "integer" }, "member_balance": { "type": "integer" }, "reward_id": { "type": "string", "format": "uuid" }, "card_id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" } }, "type": "object" }, "MemberProfile": { "description": "The authenticated member's own profile, including interaction status.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "locale": { "type": "string", "nullable": true }, "unique_identifier": { "type": "string", "nullable": true }, "avatar": { "type": "string", "nullable": true }, "is_anonymous": { "type": "boolean" }, "has_interacted": { "type": "boolean" }, "first_interaction_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "MemberCard": { "description": "A loyalty card as seen from the member perspective, including their balance.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "title": { "$ref": "#/components/schemas/TranslatableString" }, "description": { "oneOf": [ { "$ref": "#/components/schemas/TranslatableString" } ], "nullable": true }, "currency": { "type": "string", "example": "points" }, "balance": { "description": "Member's current point balance on this card", "type": "integer" }, "bg_color": { "type": "string", "nullable": true }, "text_color": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" }, "PartnerSummary": { "description": "A partner summary as seen from the admin perspective (list endpoint).", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "locale": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "time_zone": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "avatar": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "PartnerPermissions": { "description": "Feature flags and resource limits for a partner. Returned by detail and permission update endpoints.", "properties": { "loyalty_cards_permission": { "type": "boolean" }, "loyalty_cards_limit": { "description": "-1 = unlimited", "type": "integer" }, "stamp_cards_permission": { "type": "boolean" }, "stamp_cards_limit": { "type": "integer" }, "vouchers_permission": { "type": "boolean" }, "voucher_batches_permission": { "type": "boolean" }, "vouchers_limit": { "type": "integer" }, "rewards_limit": { "type": "integer" }, "staff_members_limit": { "type": "integer" }, "email_campaigns_permission": { "type": "boolean" }, "activity_permission": { "type": "boolean" }, "agent_api_permission": { "type": "boolean" }, "agent_keys_limit": { "type": "integer" }, "cards_on_homepage": { "type": "boolean" } }, "type": "object" }, "PartnerDetail": { "description": "Full partner details including permissions and usage counts (detail endpoint).", "allOf": [ { "$ref": "#/components/schemas/PartnerSummary" }, { "properties": { "permissions": { "$ref": "#/components/schemas/PartnerPermissions" }, "usage": { "properties": { "loyalty_cards": { "type": "integer" }, "stamp_cards": { "type": "integer" }, "vouchers": { "type": "integer" }, "rewards": { "type": "integer" }, "staff_members": { "type": "integer" } }, "type": "object" } }, "type": "object" } ] }, "AdminMemberDetail": { "description": "Full member details with card balances (admin detail endpoint).", "allOf": [ { "$ref": "#/components/schemas/MemberSummary" }, { "properties": { "card_balances": { "type": "array", "items": { "properties": { "card_id": { "type": "string", "format": "uuid" }, "card_title": { "type": "string" }, "club_name": { "type": "string", "nullable": true }, "balance": { "type": "integer" }, "currency": { "type": "string" } }, "type": "object" } } }, "type": "object" } ] }, "AnalyticsOverview": { "description": "Platform-wide analytics metrics.", "properties": { "total_partners": { "type": "integer" }, "active_partners": { "type": "integer" }, "total_members": { "type": "integer" }, "total_cards": { "type": "integer" }, "total_stamp_cards": { "type": "integer" }, "total_vouchers": { "type": "integer" }, "transactions_today": { "type": "integer" }, "transactions_this_week": { "type": "integer" }, "transactions_this_month": { "type": "integer" } }, "type": "object" }, "HealthResponse": { "description": "Health check response with key identity and capabilities.", "properties": { "status": { "type": "string", "example": "ok" }, "key": { "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "role": { "type": "string", "enum": [ "partner", "admin", "member" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "owner": { "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string" } }, "type": "object" } }, "type": "object" }, "Pagination": { "description": "Pagination metadata included in all list responses.", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 4 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 81 } }, "type": "object" }, "AgentError": { "description": "Structured error response with machine-readable retry strategy.", "required": [ "error", "code", "message", "retry_strategy" ], "properties": { "error": { "type": "boolean", "example": true }, "code": { "type": "string", "example": "VALIDATION_FAILED" }, "message": { "type": "string", "example": "The request data did not pass validation." }, "retry_strategy": { "description": "no_retry = permanent failure; backoff = retry with delay; fix_request = fix payload; contact_support = human action needed", "type": "string", "enum": [ "no_retry", "backoff", "fix_request", "contact_support" ] }, "details": { "type": "object", "nullable": true } }, "type": "object" } }, "securitySchemes": { "AgentKey": { "type": "apiKey", "description": "Agent API key. Prefix indicates role: rl_agent_* (partner), rl_admin_* (admin), rl_member_* (member).", "name": "X-Agent-Key", "in": "header" } } }, "security": [ { "AgentKey": [] } ], "tags": [ { "name": "Admin / Members", "description": "Admin / Members" }, { "name": "Admin / Analytics", "description": "Admin / Analytics" }, { "name": "Admin / Partners", "description": "Admin / Partners" }, { "name": "Health", "description": "Health" }, { "name": "Tools", "description": "Tools" }, { "name": "Member / Wallet", "description": "Member / Wallet" }, { "name": "Member / Discover", "description": "Member / Discover" }, { "name": "Member / Rewards", "description": "Member / Rewards" }, { "name": "Member / Profile", "description": "Member / Profile" }, { "name": "Partner / Loyalty Cards", "description": "Partner / Loyalty Cards" }, { "name": "Partner / Clubs", "description": "Partner / Clubs" }, { "name": "Partner / Members", "description": "Partner / Members" }, { "name": "Partner / Rewards", "description": "Partner / Rewards" }, { "name": "Partner / Staff", "description": "Partner / Staff" }, { "name": "Partner / Stamp Cards", "description": "Partner / Stamp Cards" }, { "name": "Partner / Tiers", "description": "Partner / Tiers" }, { "name": "Partner / Transactions", "description": "Partner / Transactions" }, { "name": "Partner / Vouchers", "description": "Partner / Vouchers" } ] }