{ "openapi": "3.0.0", "info": { "title": "Reward Loyalty API", "description": "The Reward Loyalty API provides programmatic access to the Reward Loyalty platform, enabling integration with external systems, mobile apps, and custom workflows. This RESTful API supports authentication, loyalty card management, member operations, partner operations, and transaction processing.\n\n## Authentication\n\nAll authenticated endpoints use Bearer token authentication via Laravel Sanctum. Include your token in the Authorization header.\n\nTokens are obtained by calling the login endpoints for each user type (Admin, Partner, or Member).\n\n## Rate Limiting\n\nAPI requests are rate-limited to ensure fair usage. Standard limits apply per authenticated user.\n\n## Response Format\n\nAll responses are returned in JSON format. Successful responses include the requested data, while errors include a message field describing the issue.", "contact": { "name": "Reward Loyalty Website", "url": "https://rewardloyalty.co" }, "license": { "name": "Proprietary" }, "version": "2.1.0" }, "servers": [ { "url": "/api", "description": "Current Server" } ], "paths": { "/{locale}/v1/admin/login": { "post": { "tags": [ "Admin" ], "summary": "Authenticate an administrator or manager", "description": "Authenticate using email and password to obtain a bearer token for subsequent API requests. This endpoint does not require authentication.", "operationId": "loginAdmin", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`, `de-de`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "description": "Login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "Admin email address", "type": "string", "format": "email", "example": "admin@example.com" }, "password": { "description": "Admin password (6-48 characters)", "type": "string", "format": "password", "example": "welcome3210" } }, "type": "object" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLoginSuccess" } } } }, "422": { "description": "Validation failed or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/{locale}/v1/admin/logout": { "post": { "tags": [ "Admin" ], "summary": "Deauthenticate an administrator or manager", "description": "Revokes all access tokens for the authenticated administrator or manager.", "operationId": "logoutAdmin", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Admin logged out successfully" }, "401": { "description": "Unauthorized" } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/admin": { "get": { "tags": [ "Admin" ], "summary": "Retrieve authenticated administrator or manager data", "description": "Fetches data of the authenticated administrator or manager.", "operationId": "getAdmin", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Admin data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Admin" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/admin/partners": { "get": { "tags": [ "Admin" ], "summary": "List all accessible partners", "description": "Retrieve a list of all partners the authenticated administrator has access to. Administrators (role=1) can view all partners; Managers see only partners within their assigned networks.", "operationId": "getAdminPartners", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "List of partners", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPartner" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Create a new partner", "description": "Create a new partner account with optional permissions and limits. A default club is automatically created for the partner.", "operationId": "createAdminPartner", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "description": "Partner data", "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "network_id" ], "properties": { "name": { "description": "Partner name", "type": "string", "example": "Coffee Corner" }, "email": { "description": "Partner email", "type": "string", "format": "email", "example": "partner@example.com" }, "password": { "description": "Password (6-48 chars)", "type": "string", "format": "password", "example": "securepass123" }, "network_id": { "description": "Network ID to assign partner to", "type": "integer", "example": 1 }, "locale": { "description": "Locale", "type": "string", "example": "en_US" }, "currency": { "description": "Currency code", "type": "string", "example": "USD" }, "time_zone": { "description": "Time zone", "type": "string", "example": "America/New_York" }, "is_active": { "description": "Active status", "type": "boolean", "example": true }, "permissions": { "$ref": "#/components/schemas/PartnerPermissions" } }, "type": "object" } } } }, "responses": { "201": { "description": "Partner created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPartnerFull" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/admin/partner/{partnerId}": { "get": { "tags": [ "Admin" ], "summary": "Get partner details", "description": "Retrieve detailed information about a specific partner including their permissions and limits.", "operationId": "getAdminPartner", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPartnerFull" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] }, "put": { "tags": [ "Admin" ], "summary": "Update partner details", "description": "Update a partner's profile information. Does not include permissions - use the permissions endpoint for that.", "operationId": "updateAdminPartner", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Partner data to update", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Partner Name" }, "email": { "type": "string", "example": "partner@example.com" }, "password": { "description": "New password (optional)", "type": "string", "format": "password" }, "locale": { "type": "string", "example": "en_US" }, "currency": { "type": "string", "example": "USD" }, "time_zone": { "type": "string", "example": "America/Los_Angeles" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPartner" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Delete a partner", "description": "Permanently delete a partner and all associated data. This action cannot be undone.", "operationId": "deleteAdminPartner", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Partner deleted successfully" } }, "type": "object" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Partner not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/admin/partner/{partnerId}/permissions": { "get": { "tags": [ "Admin" ], "summary": "Get partner permissions and limits", "description": "Retrieve the feature permissions and usage limits for a partner. Used for SaaS billing management.", "operationId": "getAdminPartnerPermissions", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerPermissions" } } } }, "403": { "description": "Permission denied" }, "404": { "description": "Partner not found" } }, "security": [ { "admin_auth_token": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Update partner permissions and limits", "description": "Update the feature permissions and usage limits for a partner. Used for SaaS billing tier management. Use -1 for unlimited.", "operationId": "updateAdminPartnerPermissions", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Permissions to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerPermissions" } } } }, "responses": { "200": { "description": "Updated permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerPermissions" } } } }, "403": { "description": "Permission denied" }, "404": { "description": "Partner not found" } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/admin/partner/{partnerId}/usage": { "get": { "tags": [ "Admin" ], "summary": "Get partner usage vs limits", "description": "Retrieve current usage counts compared to limits for a partner. Useful for billing dashboards and limit enforcement.", "operationId": "getAdminPartnerUsage", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "partnerId", "in": "path", "description": "Partner ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner usage statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUsage" } } } }, "403": { "description": "Permission denied" }, "404": { "description": "Partner not found" } }, "security": [ { "admin_auth_token": [] } ] } }, "/{locale}/v1/member/register": { "post": { "tags": [ "Member" ], "summary": "Register a new member", "description": "Allows a new member to create an account by providing necessary details.", "operationId": "registerMember", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "email", "in": "query", "description": "The email of the member", "required": true, "schema": { "type": "string", "format": "email", "example": "email@example.com" } }, { "name": "name", "in": "query", "description": "The name of the member", "required": true, "schema": { "type": "string", "example": "John Doe", "maxLength": 64 } }, { "name": "password", "in": "query", "description": "The password of the member, if empty a password is generated", "required": false, "schema": { "type": "string", "example": "password123", "maxLength": 48, "minLength": 6 } }, { "name": "time_zone", "in": "query", "description": "The time zone of the member", "required": false, "schema": { "type": "string", "example": "America/New_York" } }, { "name": "locale", "in": "query", "description": "The locale of the member (e.g., `en_US`)", "required": false, "schema": { "type": "string", "example": "en_US", "maxLength": 12, "minLength": 5 } }, { "name": "currency", "in": "query", "description": "The currency of the member (e.g., `USD`)", "required": false, "schema": { "type": "string", "example": "USD", "maxLength": 3, "minLength": 3 } }, { "name": "accepts_emails", "in": "query", "description": "Whether the member accepts marketing emails from a partner or not", "required": false, "schema": { "type": "integer", "example": 0, "enum": [ 0, 1 ] } }, { "name": "send_mail", "in": "query", "description": "Whether to send an email with the password to the newly created member", "required": false, "schema": { "type": "integer", "example": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "Member registration successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRegistration" } } } }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/{locale}/v1/member/login": { "post": { "tags": [ "Member" ], "summary": "Authenticate a member", "description": "Authenticate using email and password to obtain a bearer token for subsequent API requests. This endpoint does not require authentication.", "operationId": "loginMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`, `de-de`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "description": "Login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "Member email address", "type": "string", "format": "email", "example": "member@example.com" }, "password": { "description": "Member password (6-48 characters)", "type": "string", "format": "password", "example": "welcome3210" } }, "type": "object" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberLoginSuccess" } } } }, "422": { "description": "Validation failed or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/{locale}/v1/member/logout": { "post": { "tags": [ "Member" ], "summary": "Log out a member", "description": "Revokes all access tokens for the authenticated member, effectively logging them out.", "operationId": "logoutMember", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Member logged out successfully" }, "401": { "description": "Unauthorized" } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member": { "get": { "tags": [ "Member" ], "summary": "Retrieve member data", "description": "Fetches the data of the authenticated member.", "operationId": "getMember", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Member data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/all-cards": { "get": { "tags": [ "Member" ], "summary": "Retrieve all cards followed and transacted by the member", "description": "Retrieve all cards that the authenticated member follows and has transacted with.", "operationId": "getAllCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Successful operation, returns the array of followed and transacted cards", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } }, "401": { "description": "Unauthorized access, invalid or missing member token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/followed-cards": { "get": { "tags": [ "Member" ], "summary": "Retrieve all active cards followed by the member", "description": "Retrieve all active cards that the authenticated member follows.", "operationId": "getMemberFollowedCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Successful operation, returns the array of followed cards", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } }, "401": { "description": "Unauthorized access, invalid or missing member token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/transacted-cards": { "get": { "tags": [ "Member" ], "summary": "Retrieve all active cards transacted by the member", "description": "Retrieve all active cards that the authenticated member has transacted with.", "operationId": "getMemberTransactedCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Successful operation, returns the array of cards with member's transactions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } }, "401": { "description": "Unauthorized access, invalid or missing member token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/balance/{cardId}": { "get": { "tags": [ "Member" ], "summary": "Retrieve member's balance for a specific card", "description": "Retrieve the balance of the authenticated member for a specific card.", "operationId": "getMemberBalance", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "ID of the card", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation, returns the member's balance for the specific card", "content": { "application/json": { "schema": { "properties": { "balance": { "description": "The member's balance for the specific card", "type": "integer", "example": 0 } }, "type": "object" } } } }, "401": { "description": "Unauthorized access, invalid or missing member token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/my-stamp-cards": { "get": { "tags": [ "Member" ], "summary": "Get enrolled stamp cards", "description": "Retrieve all stamp cards the member has added to their collection (enrolled).", "operationId": "getMemberMyStampCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Stamp cards retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StampCard" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/stamp-cards/{stampCardId}/enroll": { "post": { "tags": [ "Member" ], "summary": "Add stamp card to My Cards", "description": "Enroll the member in a stamp card program (add to My Cards). This is equivalent to 'following' the stamp card.", "operationId": "enrollMemberStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully enrolled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Successfully enrolled in stamp card" }, "enrollment": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Stamp card not found" } }, "security": [ { "member_auth_token": [] } ] }, "delete": { "tags": [ "Member" ], "summary": "Remove stamp card from My Cards", "description": "Unenroll the member from a stamp card program. The enrollment record is marked inactive but not deleted, preserving progress.", "operationId": "unenrollMemberStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully unenrolled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Stamp card removed from My Cards" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Stamp card not found or not enrolled" } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/my-vouchers": { "get": { "tags": [ "Member" ], "summary": "Get saved vouchers", "description": "Retrieve all vouchers the member has saved to their collection (My Cards).", "operationId": "getMemberMyVouchers", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Vouchers retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Voucher" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/vouchers/{voucherId}/save": { "post": { "tags": [ "Member" ], "summary": "Add voucher to My Cards", "description": "Save a voucher to the member's collection (add to My Cards). This is equivalent to 'following' the voucher.", "operationId": "saveMemberVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Voucher saved", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Voucher added to My Cards" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher not found" }, "409": { "description": "Voucher already saved" } }, "security": [ { "member_auth_token": [] } ] }, "delete": { "tags": [ "Member" ], "summary": "Remove voucher from My Cards", "description": "Remove a saved voucher from the member's collection. Only manually saved vouchers can be removed (not claimed via QR).", "operationId": "unsaveMemberVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Voucher removed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Voucher removed from My Cards" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher not found or not saved" } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/stamp-cards": { "get": { "tags": [ "Member" ], "summary": "Retrieve member's stamp cards", "description": "Retrieve all stamp cards the authenticated member is enrolled in, including current progress, stamps collected, and rewards earned. Also returns aggregate statistics.", "operationId": "getMemberStampCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Stamp cards retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCardsResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/member/stamp-cards/{id}/history": { "get": { "tags": [ "Member" ], "summary": "Retrieve stamp card transaction history", "description": "Retrieve the transaction history for a specific stamp card, including stamps earned, redeemed, and expired. History viewing must be enabled for the stamp card by the partner.", "operationId": "getMemberStampCardHistory", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "id", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "integer", "example": 81559402807296 } } ], "responses": { "200": { "description": "Transaction history retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampHistoryResponse" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "History viewing not enabled for this stamp card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Stamp card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "member_auth_token": [] } ] } }, "/{locale}/v1/partner/login": { "post": { "tags": [ "Partner" ], "summary": "Authenticate a partner", "description": "Authenticate using email and password to obtain a bearer token for subsequent API requests. This endpoint does not require authentication.", "operationId": "loginPartner", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code (e.g., `en-us`, `de-de`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "description": "Login credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "Partner email address", "type": "string", "format": "email", "example": "partner@example.com" }, "password": { "description": "Partner password (6-48 characters)", "type": "string", "format": "password", "example": "welcome3210" } }, "type": "object" } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerLoginSuccess" } } } }, "422": { "description": "Validation failed or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/{locale}/v1/partner/logout": { "post": { "tags": [ "Partner" ], "summary": "Log out the authenticated partner", "description": "Revoke all access tokens for the authenticated partner and log them out.", "operationId": "logoutPartner", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Partner logged out successfully" }, "401": { "description": "Unauthorized" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner": { "get": { "tags": [ "Partner" ], "summary": "Retrieve authenticated partner's data", "description": "Retrieve the data of the authenticated partner.", "operationId": "getPartner", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Partner data retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/cards": { "get": { "tags": [ "Partner" ], "summary": "List all loyalty cards", "description": "Retrieve all active loyalty cards owned by the authenticated partner.", "operationId": "getPartnerCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Cards retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new loyalty card", "description": "Create a new points-based loyalty card for the partner.", "operationId": "createPartnerCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "club_id" ], "properties": { "name": { "description": "Card name", "type": "string", "example": "Coffee Rewards" }, "club_id": { "description": "Club ID", "type": "string", "format": "uuid", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" }, "head": { "description": "Card headline", "type": "string", "example": "Earn points with every purchase" }, "currency": { "description": "Currency code", "type": "string", "example": "USD" }, "initial_bonus_points": { "description": "Signup bonus points", "type": "integer", "example": 100 }, "points_per_currency": { "description": "Points earned per currency unit", "type": "number", "example": 1.5 }, "point_value": { "description": "Value per point in cents", "type": "number", "example": 1 }, "is_active": { "description": "Active status", "type": "boolean", "example": true }, "is_visible_homepage": { "description": "Show on homepage", "type": "boolean", "example": true }, "is_visible_by_link": { "description": "Accessible by link", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Card created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/cards/{cardId}": { "get": { "tags": [ "Partner" ], "summary": "Get card details", "description": "Retrieve details of a specific loyalty card by ID.", "operationId": "getCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "Card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a loyalty card", "description": "Update an existing loyalty card's details.", "operationId": "updatePartnerCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "Card ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Card Name" }, "head": { "type": "string", "example": "New headline" }, "initial_bonus_points": { "type": "integer", "example": 150 }, "points_per_currency": { "type": "number", "example": 2 }, "point_value": { "type": "number", "example": 1 }, "is_active": { "type": "boolean", "example": true }, "is_visible_homepage": { "type": "boolean", "example": true }, "is_visible_by_link": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Card updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Card" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Card not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a loyalty card", "description": "Delete a loyalty card and all associated data. This action cannot be undone.", "operationId": "deletePartnerCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "Card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Card deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Card deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Card not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/clubs": { "get": { "tags": [ "Partner" ], "summary": "List all clubs", "description": "Retrieve all active clubs owned by the authenticated partner.", "operationId": "getPartnerClubs", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Clubs retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Club" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new club", "description": "Create a new loyalty club for the partner.", "operationId": "createPartnerClub", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "description": "Club name", "type": "string", "example": "Coffee Lovers Club" }, "is_active": { "description": "Active status", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Club created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Club" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/clubs/{clubId}": { "get": { "tags": [ "Partner" ], "summary": "Get club details", "description": "Retrieve details of a specific club by ID.", "operationId": "getPartnerClub", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "clubId", "in": "path", "description": "Club ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Club details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Club" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Club not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a club", "description": "Update an existing club's details.", "operationId": "updatePartnerClub", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "clubId", "in": "path", "description": "Club ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Club Name" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Club updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Club" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Club not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a club", "description": "Delete a club and all associated data. This action cannot be undone.", "operationId": "deletePartnerClub", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "clubId", "in": "path", "description": "Club ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Club deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Club deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Club not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/": { "put": { "tags": [ "Partner" ], "summary": "Update the authenticated partner's details", "description": "Update the profile details of the currently authenticated partner. Only include fields you wish to modify.", "operationId": "updatePartner", "parameters": [ { "name": "locale", "in": "path", "description": "The locale (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "description": "Provide the partner data you wish to update. Omit any key/value pairs that should remain unchanged.", "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "description": "Partner's name", "type": "string", "example": "Partner Name" }, "email": { "description": "Partner's email", "type": "string", "example": "partner@example.com" }, "locale": { "description": "Locale setting", "type": "string", "example": "en-us" }, "currency": { "description": "Currency setting", "type": "string", "example": "USD" }, "time_zone": { "description": "Time zone setting", "type": "string", "example": "America/Los_Angeles" } }, "type": "object" } } } }, "responses": { "200": { "description": "Partner updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/members": { "get": { "tags": [ "Partner" ], "summary": "List all members", "description": "Retrieve all members registered in the partner's clubs.", "operationId": "getPartnerMembers", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Members retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new member", "description": "Register a new member in one of the partner's clubs.", "operationId": "createPartnerMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "club_id" ], "properties": { "name": { "description": "Member name", "type": "string", "example": "Jane Customer" }, "email": { "description": "Member email", "type": "string", "format": "email", "example": "jane@example.com" }, "password": { "description": "Password (optional, auto-generated if not provided)", "type": "string", "format": "password" }, "club_id": { "description": "Club ID", "type": "string", "format": "uuid", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" }, "accepts_emails": { "description": "Accepts marketing emails", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Member created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/members/{memberId}": { "get": { "tags": [ "Partner" ], "summary": "Get member details", "description": "Retrieve details of a specific member by ID.", "operationId": "getPartnerMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "memberId", "in": "path", "description": "Member ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Member details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Member not found" } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a member", "description": "Update an existing member's details.", "operationId": "updatePartnerMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "memberId", "in": "path", "description": "Member ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Name" }, "email": { "type": "string", "format": "email", "example": "updated@example.com" }, "password": { "description": "New password (optional)", "type": "string", "format": "password" }, "accepts_emails": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Member updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Member not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a member", "description": "Delete a member. This action cannot be undone.", "operationId": "deletePartnerMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "memberId", "in": "path", "description": "Member ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Member deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Member deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Member not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/rewards": { "get": { "tags": [ "Partner" ], "summary": "List all rewards", "description": "Retrieve all rewards owned by the authenticated partner.", "operationId": "getPartnerRewards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "card_id", "in": "query", "description": "Filter by card ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rewards retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Reward" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new reward", "description": "Create a new reward for a loyalty card.", "operationId": "createPartnerReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "card_id", "points_required" ], "properties": { "title": { "description": "Reward title", "type": "string", "example": "Free Coffee" }, "card_id": { "description": "Card ID", "type": "string", "format": "uuid", "example": "019b8d49-5678-7abc-8def-27f2107a8ec1" }, "description": { "description": "Reward description", "type": "string", "example": "Enjoy a free coffee of your choice" }, "points_required": { "description": "Points needed to redeem", "type": "integer", "example": 100 }, "is_active": { "description": "Active status", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Reward created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/rewards/{rewardId}": { "get": { "tags": [ "Partner" ], "summary": "Get reward details", "description": "Retrieve details of a specific reward by ID.", "operationId": "getPartnerReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "rewardId", "in": "path", "description": "Reward ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reward details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Reward not found" } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a reward", "description": "Update an existing reward's details.", "operationId": "updatePartnerReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "rewardId", "in": "path", "description": "Reward ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Updated Reward Title" }, "description": { "type": "string", "example": "Updated description" }, "points_required": { "type": "integer", "example": 150 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reward" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Reward not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a reward", "description": "Delete a reward. This action cannot be undone.", "operationId": "deletePartnerReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "rewardId", "in": "path", "description": "Reward ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reward deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Reward deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Reward not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/staff": { "get": { "tags": [ "Partner" ], "summary": "List all staff members", "description": "Retrieve all active staff members for the authenticated partner.", "operationId": "getPartnerStaffMembers", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Staff retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StaffMember" } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new staff member", "description": "Create a new staff member for the partner.", "operationId": "createPartnerStaff", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "password", "club_id" ], "properties": { "name": { "description": "Staff name", "type": "string", "example": "John Smith" }, "email": { "description": "Staff email", "type": "string", "format": "email", "example": "john@example.com" }, "password": { "description": "Password (6-48 chars)", "type": "string", "format": "password", "example": "securepass123" }, "club_id": { "description": "Club ID", "type": "string", "format": "uuid", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" }, "role": { "description": "Role: 1=Manager, 2=Staff", "type": "integer", "example": 2 }, "is_active": { "description": "Active status", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Staff created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMember" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/staff/{staffId}": { "get": { "tags": [ "Partner" ], "summary": "Get staff member details", "description": "Retrieve details of a specific staff member by ID.", "operationId": "getPartnerStaffMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "staffId", "in": "path", "description": "Staff ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Staff details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMember" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Staff not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a staff member", "description": "Update an existing staff member's details.", "operationId": "updatePartnerStaff", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "staffId", "in": "path", "description": "Staff ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Name" }, "email": { "type": "string", "format": "email", "example": "updated@example.com" }, "password": { "description": "New password (optional)", "type": "string", "format": "password" }, "role": { "type": "integer", "example": 2 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Staff updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMember" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Staff not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a staff member", "description": "Delete a staff member. This action cannot be undone.", "operationId": "deletePartnerStaff", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "staffId", "in": "path", "description": "Staff ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Staff deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Staff member deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Staff not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/stamp-cards": { "get": { "tags": [ "Partner" ], "summary": "List all stamp cards", "description": "Retrieve all stamp cards owned by the authenticated partner.", "operationId": "getPartnerStampCards", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Stamp cards retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StampCard" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new stamp card", "description": "Create a new stamp-based loyalty card for the partner.", "operationId": "createPartnerStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "club_id", "stamps_required" ], "properties": { "title": { "description": "Card title", "type": "string", "example": "Coffee Stamp Card" }, "club_id": { "description": "Club ID", "type": "string", "format": "uuid", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" }, "description": { "description": "Card description", "type": "string", "example": "Collect stamps with every purchase" }, "stamps_required": { "description": "Stamps needed for reward", "type": "integer", "example": 10 }, "reward_title": { "description": "Reward title", "type": "string", "example": "Free Coffee" }, "reward_description": { "description": "Reward description", "type": "string", "example": "Get a free coffee of your choice" }, "is_active": { "description": "Active status", "type": "boolean", "example": true }, "is_visible_homepage": { "description": "Show on homepage", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Stamp card created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCard" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/stamp-cards/{stampCardId}": { "get": { "tags": [ "Partner" ], "summary": "Get stamp card details", "description": "Retrieve details of a specific stamp card by ID.", "operationId": "getPartnerStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stamp card details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCard" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Stamp card not found" } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a stamp card", "description": "Update an existing stamp card's details.", "operationId": "updatePartnerStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Updated Stamp Card" }, "description": { "type": "string", "example": "Updated description" }, "stamps_required": { "type": "integer", "example": 12 }, "reward_title": { "type": "string", "example": "Free Item" }, "reward_description": { "type": "string", "example": "Get a free item" }, "is_active": { "type": "boolean", "example": true }, "is_visible_homepage": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Stamp card updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCard" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Stamp card not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a stamp card", "description": "Delete a stamp card. This action cannot be undone.", "operationId": "deletePartnerStampCard", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stamp card deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Stamp card deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Stamp card not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/cards/{cardUID}/{memberUID}/transactions/purchases": { "post": { "tags": [ "Partner" ], "summary": "Add a purchase to a card", "description": "Add a new purchase transaction to a card where the authenticated partner has access to.", "operationId": "addPurchase", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardUID", "in": "path", "description": "Unique identifier of the card to which the transaction will be added", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } }, { "name": "memberUID", "in": "path", "description": "Unique identifier for the member", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } } ], "requestBody": { "description": "Purchase data", "required": true, "content": { "application/json": { "schema": { "properties": { "purchase_amount": { "description": "The amount of money spent on the purchase", "type": "number", "example": 100 }, "image": { "description": "The image associated with the transaction", "type": "string", "example": "" }, "note": { "description": "An optional note for the purchase", "type": "string", "example": "", "nullable": true }, "staffId": { "description": "Staff ID", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-57f2107a8eb4" } }, "type": "object" } } } }, "responses": { "201": { "description": "Purchase created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/cards/{cardUID}/{memberUID}/transactions/points": { "post": { "tags": [ "Partner" ], "summary": "Add points to a card", "description": "Add new points to a card where the authenticated partner has access to.", "operationId": "addPoints", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardUID", "in": "path", "description": "Unique identifier of the card to which the transaction will be added", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } }, { "name": "memberUID", "in": "path", "description": "Unique identifier for the member", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } } ], "requestBody": { "description": "Points data", "required": true, "content": { "application/json": { "schema": { "properties": { "points": { "description": "The number of points to add", "type": "number", "example": 100 }, "image": { "description": "The image associated with the transaction", "type": "string", "example": "" }, "note": { "description": "An optional note for the points addition", "type": "string", "example": "", "nullable": true }, "staffId": { "description": "Staff ID", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-57f2107a8eb4" } }, "type": "object" } } } }, "responses": { "201": { "description": "Points added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "404": { "description": "Card not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "422": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/cards/{cardUID}/{memberUID}/transactions/deductions": { "post": { "tags": [ "Partner" ], "summary": "Deduct points from a member's card", "description": "Deduct a custom number of points from a member's loyalty card balance. Creates a negative-point transaction with a required audit note. The partner must own the card. Use this to redeem points for off-platform rewards such as gift cards or external services.", "operationId": "deductPoints", "parameters": [ { "name": "locale", "in": "path", "description": "Locale setting (e.g., `en-us`)", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardUID", "in": "path", "description": "Unique identifier of the card to deduct points from", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } }, { "name": "memberUID", "in": "path", "description": "Unique identifier for the member", "required": true, "schema": { "type": "string", "format": "xxx-xxx-xxx-xxx", "example": "123-456-789-012" } } ], "requestBody": { "description": "Deduction data", "required": true, "content": { "application/json": { "schema": { "required": [ "points", "note" ], "properties": { "points": { "description": "Number of points to deduct (must be a positive integer)", "type": "integer", "example": 500 }, "note": { "description": "Required note explaining the reason for the deduction", "type": "string", "example": "Gift card redemption - $50 Amazon card" }, "reference": { "description": "Optional external reference for linking to an external system", "type": "string", "example": "giftcard:order:12345", "nullable": true }, "staffId": { "description": "Optional staff member ID for audit attribution (must be authorized for the card)", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-57f2107a8eb4", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Points deducted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Points deducted successfully" }, "points_deducted": { "type": "integer", "example": 500 }, "new_balance": { "type": "integer", "example": 1200 }, "transaction": { "$ref": "#/components/schemas/Transaction" } }, "type": "object" } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "404": { "description": "Card, member, or staff not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "422": { "description": "Validation error or insufficient points", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/vouchers": { "get": { "tags": [ "Partner" ], "summary": "List all vouchers", "description": "Retrieve all vouchers owned by the authenticated partner.", "operationId": "getPartnerVouchers", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "club_id", "in": "query", "description": "Filter by club ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Vouchers retrieved", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Voucher" } } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "partner_auth_token": [] } ] }, "post": { "tags": [ "Partner" ], "summary": "Create a new voucher", "description": "Create a new voucher for the partner.", "operationId": "createPartnerVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "club_id", "type" ], "properties": { "title": { "description": "Voucher title", "type": "string", "example": "Summer Sale 20% Off" }, "club_id": { "description": "Club ID", "type": "string", "format": "uuid", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" }, "code": { "description": "Voucher code (auto-generated if not provided)", "type": "string", "example": "SUMMER20" }, "type": { "description": "Type: percentage, fixed_amount, bonus_points", "type": "string", "example": "percentage" }, "discount_amount": { "description": "Discount amount in cents (for fixed) or percentage", "type": "integer", "example": 2000 }, "min_purchase_amount": { "description": "Minimum purchase in cents", "type": "integer", "example": 5000 }, "max_uses": { "description": "Maximum total uses (-1 for unlimited)", "type": "integer", "example": 100 }, "max_uses_per_member": { "description": "Max uses per member (-1 for unlimited)", "type": "integer", "example": 1 }, "valid_from": { "description": "Start date", "type": "string", "format": "date-time" }, "valid_until": { "description": "End date", "type": "string", "format": "date-time" }, "is_active": { "description": "Active status", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Voucher created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voucher" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/partner/vouchers/{voucherId}": { "get": { "tags": [ "Partner" ], "summary": "Get voucher details", "description": "Retrieve details of a specific voucher by ID.", "operationId": "getPartnerVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Voucher details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voucher" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher not found" } }, "security": [ { "partner_auth_token": [] } ] }, "put": { "tags": [ "Partner" ], "summary": "Update a voucher", "description": "Update an existing voucher's details.", "operationId": "updatePartnerVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string", "example": "Updated Voucher Title" }, "discount_amount": { "type": "integer", "example": 2500 }, "min_purchase_amount": { "type": "integer", "example": 6000 }, "max_uses": { "type": "integer", "example": 200 }, "valid_until": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voucher" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher not found" } }, "security": [ { "partner_auth_token": [] } ] }, "delete": { "tags": [ "Partner" ], "summary": "Delete a voucher", "description": "Delete a voucher. This action cannot be undone.", "operationId": "deletePartnerVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Voucher deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Voucher deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher not found" } }, "security": [ { "partner_auth_token": [] } ] } }, "/{locale}/v1/staff/login": { "post": { "tags": [ "Staff" ], "summary": "Staff login", "description": "Authenticate a staff member and receive an API token for subsequent requests.", "operationId": "staffLogin", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "description": "Staff email", "type": "string", "format": "email", "example": "staff@example.com" }, "password": { "description": "Staff password", "type": "string", "format": "password", "example": "welcome3210" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "token": { "description": "API Bearer token", "type": "string", "example": "1|abc123..." }, "staff": { "$ref": "#/components/schemas/StaffMember" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials" } } } }, "/{locale}/v1/staff/logout": { "post": { "tags": [ "Staff" ], "summary": "Staff logout", "description": "Invalidate the current API token and log out.", "operationId": "staffLogout", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Successfully logged out" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff": { "get": { "tags": [ "Staff" ], "summary": "Get staff profile", "description": "Retrieve the authenticated staff member's profile including their assigned club.", "operationId": "getStaffProfile", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "responses": { "200": { "description": "Staff profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffMember" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/member/{identifier}": { "get": { "tags": [ "Staff" ], "summary": "Find a member", "description": "Look up a member by ID, unique identifier, email, or phone. Returns member details and balances.", "operationId": "staffFindMember", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "identifier", "in": "path", "description": "Member ID, unique identifier, email, or phone", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Member found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Member not found" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/cards/{cardId}/purchase": { "post": { "tags": [ "Staff" ], "summary": "Add purchase and award points", "description": "Record a purchase transaction and award points to a member based on the card's earning rules. This is the primary transaction for points-based loyalty programs.", "operationId": "staffAddPurchase", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "Loyalty card ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_id", "purchase_amount" ], "properties": { "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "purchase_amount": { "description": "Purchase amount in currency units", "type": "number", "format": "float", "example": 25.5 }, "points": { "description": "Override calculated points (optional)", "type": "integer", "example": null }, "points_only": { "description": "Award points without purchase amount", "type": "boolean", "example": false }, "note": { "description": "Transaction note", "type": "string", "example": "Birthday bonus" } }, "type": "object" } } } }, "responses": { "201": { "description": "Transaction created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Purchase recorded successfully" }, "transaction": { "type": "object" }, "points_earned": { "type": "integer", "example": 25 }, "new_balance": { "type": "integer", "example": 150 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Staff not authorized for this card" }, "404": { "description": "Card or member not found" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/cards/{cardId}/rewards/{rewardId}/redeem": { "post": { "tags": [ "Staff" ], "summary": "Redeem a loyalty reward", "description": "Redeem a reward for a member, deducting the required points from their balance.", "operationId": "staffRedeemReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "cardId", "in": "path", "description": "Loyalty card ID", "required": true, "schema": { "type": "string" } }, { "name": "rewardId", "in": "path", "description": "Reward ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_id" ], "properties": { "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "note": { "description": "Redemption note", "type": "string", "example": "VIP customer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward redeemed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Reward redeemed successfully" }, "points_deducted": { "type": "integer", "example": 100 }, "new_balance": { "type": "integer", "example": 50 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Staff not authorized" }, "404": { "description": "Card, reward, or member not found" }, "422": { "description": "Insufficient points" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/stamp-cards/{stampCardId}/stamps": { "post": { "tags": [ "Staff" ], "summary": "Add stamps to a card", "description": "Add one or more stamps to a member's stamp card. Automatically handles card completion and pending rewards.", "operationId": "staffAddStamps", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_id" ], "properties": { "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "stamps": { "description": "Number of stamps to add (default: 1)", "type": "integer", "example": 1 }, "purchase_amount": { "description": "Optional purchase amount", "type": "number", "format": "float", "example": 12.5 }, "note": { "description": "Transaction note", "type": "string", "example": "Morning coffee" } }, "type": "object" } } } }, "responses": { "201": { "description": "Stamps added", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Stamps added successfully" }, "stamps_added": { "type": "integer", "example": 1 }, "current_stamps": { "type": "integer", "example": 5 }, "stamps_required": { "type": "integer", "example": 10 }, "pending_rewards": { "type": "integer", "example": 0 }, "card_completed": { "type": "boolean", "example": false } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Staff not authorized" }, "404": { "description": "Stamp card or member not found" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/stamp-cards/{stampCardId}/redeem": { "post": { "tags": [ "Staff" ], "summary": "Redeem a stamp card reward", "description": "Redeem a pending reward from a completed stamp card.", "operationId": "staffRedeemStampReward", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "stampCardId", "in": "path", "description": "Stamp card ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_id" ], "properties": { "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "note": { "description": "Redemption note", "type": "string", "example": "Free coffee claimed" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reward redeemed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Stamp reward redeemed successfully" }, "reward_title": { "type": "string", "example": "Free Coffee" }, "remaining_rewards": { "type": "integer", "example": 0 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Staff not authorized" }, "404": { "description": "Stamp card or member not found" }, "422": { "description": "No pending rewards" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/vouchers/validate": { "post": { "tags": [ "Staff" ], "summary": "Validate a voucher code", "description": "Check if a voucher code is valid, not expired, and can be used by the member. Returns discount details if valid.", "operationId": "staffValidateVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "member_id" ], "properties": { "code": { "description": "Voucher code", "type": "string", "example": "SUMMER20" }, "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "order_amount": { "description": "Order amount in cents (for min purchase check)", "type": "integer", "example": 5000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher validation result", "content": { "application/json": { "schema": { "properties": { "valid": { "type": "boolean", "example": true }, "voucher": { "type": "object" }, "discount_type": { "type": "string", "example": "percentage" }, "discount_amount": { "type": "integer", "example": 20 }, "message": { "type": "string", "example": "Voucher is valid" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "staff_auth_token": [] } ] } }, "/{locale}/v1/staff/vouchers/{voucherId}/redeem": { "post": { "tags": [ "Staff" ], "summary": "Redeem a voucher", "description": "Apply a voucher to a transaction. Records the redemption and returns the discount applied.", "operationId": "staffRedeemVoucher", "parameters": [ { "name": "locale", "in": "path", "description": "Locale code", "required": true, "schema": { "type": "string", "default": "en-us" } }, { "name": "voucherId", "in": "path", "description": "Voucher ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "member_id" ], "properties": { "member_id": { "description": "Member ID", "type": "string", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "order_amount": { "description": "Order amount in cents", "type": "integer", "example": 5000 }, "order_reference": { "description": "Order/receipt reference", "type": "string", "example": "INV-2026-001" } }, "type": "object" } } } }, "responses": { "200": { "description": "Voucher redeemed", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Voucher redeemed successfully" }, "discount_applied": { "type": "integer", "example": 1000 }, "redemption_id": { "type": "string", "example": "019b8d49-1234-7abc-8def-17f2107a8ec0" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Voucher or member not found" }, "422": { "description": "Voucher cannot be redeemed" } }, "security": [ { "staff_auth_token": [] } ] } } }, "components": { "schemas": { "ErrorResponse": { "description": "Standard error response for failed operations", "required": [ "message" ], "properties": { "message": { "description": "Human-readable error message", "type": "string", "example": "The provided credentials are incorrect." }, "code": { "description": "Application-specific error code", "type": "integer", "example": 400 } }, "type": "object" }, "UnauthenticatedResponse": { "description": "Response when authentication is required but not provided or invalid", "required": [ "message" ], "properties": { "message": { "description": "Authentication error message", "type": "string", "example": "Unauthenticated." } }, "type": "object" }, "NotFoundResponse": { "description": "Response when the requested resource does not exist", "required": [ "message" ], "properties": { "message": { "description": "Not found error message", "type": "string", "example": "Resource not found." } }, "type": "object" }, "ForbiddenResponse": { "description": "Response when the user lacks permission to access the resource", "required": [ "message" ], "properties": { "message": { "description": "Permission error message", "type": "string", "example": "You do not have permission to access this resource." } }, "type": "object" }, "ValidationErrorResponse": { "description": "Response when request validation fails", "properties": { "message": { "description": "General validation error message", "type": "string", "example": "The given data was invalid." }, "errors": { "description": "Field-specific validation errors", "type": "object" } }, "type": "object" }, "AdminLoginSuccess": { "description": "Successful admin authentication response", "required": [ "token" ], "properties": { "token": { "description": "Bearer token for authenticating subsequent requests", "type": "string", "example": "1|laravel_sanctum_j3ffUNZdoP0JZJn0y3GzgcAONlDzekQrUWI2sqk3c473f47b" } }, "type": "object" }, "PartnerLoginSuccess": { "description": "Successful partner authentication response", "required": [ "token" ], "properties": { "token": { "description": "Bearer token for authenticating subsequent requests", "type": "string", "example": "2|laravel_sanctum_abc123xyz789partnerToken" } }, "type": "object" }, "MemberLoginSuccess": { "description": "Successful member authentication response", "required": [ "token" ], "properties": { "token": { "description": "Bearer token for authenticating subsequent requests", "type": "string", "example": "3|laravel_sanctum_def456uvw321memberToken" } }, "type": "object" }, "LogoutSuccess": { "description": "Successful logout response", "required": [ "message" ], "properties": { "message": { "description": "Logout confirmation message", "type": "string", "example": "Successfully logged out" } }, "type": "object" }, "Admin": { "description": "Administrator or manager user account", "required": [ "id", "role", "name", "email", "created_at", "updated_at" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-17f2107a8eb0" }, "role": { "description": "User role: 1 = Administrator, 2 = Manager", "type": "integer", "example": 1 }, "name": { "description": "Display name", "type": "string", "example": "John Admin", "maxLength": 64 }, "email": { "description": "Email address", "type": "string", "format": "email", "example": "admin@example.com" }, "locale": { "description": "Preferred locale", "type": "string", "example": "en_US", "nullable": true }, "currency": { "description": "Preferred currency code", "type": "string", "example": "USD", "nullable": true }, "time_zone": { "description": "IANA time zone identifier", "type": "string", "example": "America/New_York", "nullable": true }, "number_of_times_logged_in": { "description": "Total login count", "type": "integer", "example": 42 }, "last_login_at": { "description": "Timestamp of last login", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "description": "Account creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" }, "avatar": { "description": "URL to avatar image", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "AdminPartner": { "description": "Partner data as viewed by an administrator", "required": [ "id", "name", "email" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-27f2107a8eb1" }, "network_id": { "description": "Associated network identifier", "type": "string", "format": "uuid", "nullable": true }, "name": { "description": "Business name", "type": "string", "example": "Coffee Corner", "maxLength": 64 }, "email": { "description": "Contact email", "type": "string", "format": "email", "example": "partner@coffecorner.com" }, "email_verified_at": { "description": "Email verification timestamp", "type": "string", "format": "date-time", "nullable": true }, "locale": { "description": "Preferred locale", "type": "string", "example": "en_US", "nullable": true }, "currency": { "description": "Default currency", "type": "string", "example": "USD", "nullable": true }, "time_zone": { "description": "Time zone", "type": "string", "example": "America/New_York", "nullable": true }, "is_active": { "description": "Whether the partner account is active", "type": "boolean", "example": true }, "number_of_times_logged_in": { "description": "Total login count", "type": "integer", "example": 15 }, "last_login_at": { "description": "Last login timestamp", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "description": "Account creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" }, "avatar": { "description": "URL to avatar image", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "Partner": { "description": "Partner (merchant) account information", "required": [ "id", "name", "email" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-37f2107a8eb2" }, "network_id": { "description": "Associated network identifier", "type": "string", "format": "uuid", "nullable": true }, "name": { "description": "Business name", "type": "string", "example": "Coffee Corner", "maxLength": 64 }, "email": { "description": "Contact email", "type": "string", "format": "email", "example": "partner@coffecorner.com" }, "email_verified_at": { "description": "Email verification timestamp", "type": "string", "format": "date-time", "nullable": true }, "locale": { "description": "Preferred locale", "type": "string", "example": "en_US", "nullable": true }, "currency": { "description": "Default currency", "type": "string", "example": "USD", "nullable": true }, "time_zone": { "description": "Time zone", "type": "string", "example": "America/Los_Angeles", "nullable": true }, "number_of_times_logged_in": { "description": "Total login count", "type": "integer", "example": 28 }, "last_login_at": { "description": "Last login timestamp", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "description": "Account creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" }, "avatar": { "description": "URL to avatar image", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "Member": { "description": "Loyalty program member (customer) account", "required": [ "id", "unique_identifier", "name", "email" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-47f2107a8eb3" }, "unique_identifier": { "description": "Human-readable unique ID", "type": "string", "example": "700-857-223-945" }, "name": { "description": "Member name", "type": "string", "example": "Jane Customer", "maxLength": 64 }, "email": { "description": "Email address", "type": "string", "format": "email", "example": "jane@example.com" }, "email_verified_at": { "description": "Email verification timestamp", "type": "string", "format": "date-time", "nullable": true }, "locale": { "description": "Preferred locale", "type": "string", "example": "en_US", "nullable": true }, "currency": { "description": "Preferred currency", "type": "string", "example": "USD", "nullable": true }, "time_zone": { "description": "Time zone", "type": "string", "example": "America/New_York", "nullable": true }, "accepts_emails": { "description": "Whether member accepts marketing emails", "type": "boolean", "example": true }, "number_of_times_logged_in": { "description": "Total login count", "type": "integer", "example": 12 }, "last_login_at": { "description": "Last login timestamp", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "description": "Account creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" }, "avatar": { "description": "URL to avatar image", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "MemberRegistration": { "description": "Response after successful member registration", "required": [ "email", "name" ], "properties": { "email": { "description": "Registered email", "type": "string", "format": "email", "example": "newmember@example.com" }, "name": { "description": "Member name", "type": "string", "example": "New Member", "maxLength": 64 }, "password": { "description": "Generated password (only returned if auto-generated)", "type": "string", "example": "123456" }, "time_zone": { "description": "Time zone", "type": "string", "example": "America/New_York", "nullable": true }, "locale": { "description": "Locale", "type": "string", "example": "en_US", "nullable": true }, "currency": { "description": "Currency", "type": "string", "example": "USD", "nullable": true }, "accepts_emails": { "description": "Email preference", "type": "integer", "example": 0 }, "send_mail": { "description": "Whether welcome email was sent", "type": "integer", "example": 0 } }, "type": "object" }, "StaffMember": { "description": "Staff member who can process transactions", "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-57f2107a8eb4" }, "club_id": { "description": "Associated club identifier", "type": "string", "format": "uuid" }, "name": { "description": "Staff member name", "type": "string", "example": "Alex Staff" }, "email": { "description": "Email address", "type": "string", "format": "email", "example": "alex@coffeecorner.com" }, "time_zone": { "description": "Time zone", "type": "string", "nullable": true }, "number_of_times_logged_in": { "description": "Total login count", "type": "integer" }, "last_login_at": { "description": "Last login timestamp", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" }, "avatar": { "description": "URL to avatar image", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "Club": { "description": "A loyalty club containing cards and members", "required": [ "id", "name" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-67f2107a8eb5" }, "name": { "description": "Club name", "type": "string", "example": "Coffee Lovers Club", "maxLength": 120 }, "is_active": { "description": "Whether the club is active", "type": "boolean", "example": true }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time" } }, "type": "object" }, "Card": { "description": "A points-based loyalty card", "required": [ "id", "club_id", "name", "unique_identifier", "currency" ], "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "019b8d48-97df-7177-8aa0-77f2107a8eb6" }, "club_id": { "description": "Parent club identifier", "type": "string", "format": "uuid" }, "name": { "description": "Card name", "type": "string", "example": "Coffee Rewards Card" }, "head": { "description": "Multilingual header text", "type": "object" }, "title": { "description": "Multilingual card title", "type": "object" }, "description": { "description": "Multilingual card description", "type": "object" }, "unique_identifier": { "description": "Unique identifier for QR codes", "type": "string" }, "issue_date": { "description": "When the card became active", "type": "string", "format": "date-time", "nullable": true }, "expiration_date": { "description": "When the card expires", "type": "string", "format": "date-time", "nullable": true }, "bg_color": { "description": "Background color (hex)", "type": "string", "example": "#8B4513" }, "bg_color_opacity": { "description": "Background opacity percentage", "type": "integer", "example": 90 }, "text_color": { "description": "Text color (hex)", "type": "string", "example": "#FFFFFF" }, "currency": { "description": "Currency code (ISO 4217)", "type": "string", "example": "USD" }, "initial_bonus_points": { "description": "Bonus points on first use", "type": "integer", "example": 10 }, "points_expiration_months": { "description": "Months until points expire", "type": "integer", "nullable": true }, "currency_unit_amount": { "description": "Amount per currency unit", "type": "integer" }, "points_per_currency": { "description": "Points per currency unit spent", "type": "integer" }, "min_points_per_purchase": { "description": "Minimum points per transaction", "type": "integer" }, "max_points_per_purchase": { "description": "Maximum points per transaction", "type": "integer" }, "is_visible_by_default": { "description": "Whether publicly discoverable", "type": "boolean" }, "is_visible_when_logged_in": { "description": "Visible to logged-in members", "type": "boolean" }, "total_amount_purchased": { "description": "Total purchase amount (minor units)", "type": "integer" }, "number_of_points_issued": { "description": "Total points issued", "type": "integer" }, "last_points_issued_at": { "type": "string", "format": "date-time", "nullable": true }, "number_of_points_redeemed": { "description": "Total points redeemed", "type": "integer" }, "number_of_rewards_redeemed": { "description": "Total rewards redeemed", "type": "integer" }, "last_reward_redeemed_at": { "type": "string", "format": "date-time", "nullable": true }, "views": { "description": "Total card page views", "type": "integer" }, "last_view": { "type": "string", "format": "date-time", "nullable": true }, "meta": { "description": "Additional metadata", "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "balance": { "description": "Member's current point balance (-1 if not applicable)", "type": "integer", "example": 250 } }, "type": "object" }, "StampCard": { "description": "A stamp-based loyalty card", "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid" }, "title": { "description": "Card title", "type": "string" }, "description": { "description": "Card description", "type": "string", "nullable": true }, "reward_title": { "description": "Reward title", "type": "string" }, "reward_description": { "description": "Reward description", "type": "string", "nullable": true }, "current_stamps": { "description": "Member's current stamp count", "type": "integer" }, "stamps_required": { "description": "Stamps needed to complete", "type": "integer" }, "progress_percentage": { "description": "Completion progress (0-100)", "type": "number", "format": "float" }, "pending_rewards": { "description": "Unclaimed completed rewards", "type": "integer" }, "completed_count": { "description": "Total times completed", "type": "integer" }, "redeemed_count": { "description": "Total rewards redeemed", "type": "integer" }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_stamp_at": { "type": "string", "format": "date-time", "nullable": true }, "last_completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_stamp_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "stamp_icon": { "description": "Icon identifier", "type": "string", "nullable": true }, "colors": { "description": "Card color scheme", "type": "object" }, "media": { "description": "Card media assets", "type": "object" }, "settings": { "description": "Card behavior settings", "type": "object" }, "reward_value": { "type": "number", "format": "float", "nullable": true }, "reward_points": { "type": "integer", "nullable": true } }, "type": "object" }, "StampCardsResponse": { "description": "Response containing member's stamp cards and statistics", "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "stamp_cards": { "type": "array", "items": { "$ref": "#/components/schemas/StampCard" } }, "stats": { "type": "object" } }, "type": "object" } }, "type": "object" }, "StampTransaction": { "description": "A stamp card transaction record", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "description": "Transaction type", "type": "string", "example": "earned" }, "stamps": { "description": "Number of stamps", "type": "integer" }, "purchase_amount": { "type": "number", "format": "float", "nullable": true }, "notes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "staff_name": { "type": "string", "nullable": true } }, "type": "object" }, "StampHistoryResponse": { "description": "Response containing stamp card transaction history", "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/StampTransaction" } } }, "type": "object" } }, "type": "object" }, "PurchaseRequest": { "description": "Request body for adding a purchase transaction", "required": [ "purchase_amount" ], "properties": { "purchase_amount": { "description": "Purchase amount", "type": "number", "format": "float", "example": 25.5 }, "note": { "description": "Optional note", "type": "string", "nullable": true }, "image": { "description": "Optional image", "type": "string", "nullable": true }, "staffId": { "description": "Staff member ID", "type": "string", "nullable": true } }, "type": "object" }, "Transaction": { "description": "A completed loyalty card transaction", "properties": { "id": { "type": "string", "format": "uuid" }, "staff_id": { "type": "string", "format": "uuid", "nullable": true }, "member_id": { "type": "string", "format": "uuid" }, "card_id": { "type": "string", "format": "uuid" }, "partner_name": { "type": "string" }, "partner_email": { "type": "string" }, "purchase_amount": { "type": "number", "format": "float", "nullable": true }, "note": { "type": "string", "nullable": true }, "points_issued": { "type": "integer" }, "reward_redeemed": { "type": "boolean" }, "reward_id": { "type": "string", "format": "uuid", "nullable": true }, "transaction_date": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "BalanceResponse": { "description": "Response containing a member's point balance", "required": [ "balance" ], "properties": { "balance": { "description": "Current point balance", "type": "integer", "example": 250 } }, "type": "object" }, "AdminPartnerFull": { "description": "Partner data with permissions as viewed by an administrator", "allOf": [ { "$ref": "#/components/schemas/AdminPartner" }, { "properties": { "permissions": { "$ref": "#/components/schemas/PartnerPermissions" } }, "type": "object" } ] }, "PartnerPermissions": { "description": "Partner feature permissions and limits for SaaS billing management", "properties": { "loyalty_cards_permission": { "description": "Can create loyalty cards", "type": "boolean", "example": true }, "loyalty_cards_limit": { "description": "Max loyalty cards (-1 = unlimited)", "type": "integer", "example": -1 }, "stamp_cards_permission": { "description": "Can create stamp cards", "type": "boolean", "example": true }, "stamp_cards_limit": { "description": "Max stamp cards (-1 = unlimited)", "type": "integer", "example": -1 }, "vouchers_permission": { "description": "Can create vouchers", "type": "boolean", "example": true }, "voucher_batches_permission": { "description": "Can create voucher batches", "type": "boolean", "example": true }, "vouchers_limit": { "description": "Max vouchers (-1 = unlimited)", "type": "integer", "example": -1 }, "rewards_limit": { "description": "Max rewards (-1 = unlimited)", "type": "integer", "example": -1 }, "staff_members_limit": { "description": "Max staff members (-1 = unlimited)", "type": "integer", "example": -1 }, "email_campaigns_permission": { "description": "Can create email campaigns", "type": "boolean", "example": true }, "activity_permission": { "description": "Can view activity logs", "type": "boolean", "example": true }, "cards_on_homepage": { "description": "Can display cards on homepage", "type": "boolean", "example": true } }, "type": "object" }, "PartnerUsage": { "description": "Partner usage statistics compared to limits", "properties": { "loyalty_cards": { "properties": { "used": { "description": "Current count", "type": "integer", "example": 5 }, "limit": { "description": "Maximum allowed (-1 = unlimited)", "type": "integer", "example": -1 }, "allowed": { "description": "Feature enabled", "type": "boolean", "example": true } }, "type": "object" }, "stamp_cards": { "properties": { "used": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "example": -1 }, "allowed": { "type": "boolean", "example": true } }, "type": "object" }, "vouchers": { "properties": { "used": { "type": "integer", "example": 10 }, "limit": { "type": "integer", "example": 100 }, "allowed": { "type": "boolean", "example": true } }, "type": "object" }, "rewards": { "properties": { "used": { "type": "integer", "example": 8 }, "limit": { "type": "integer", "example": -1 }, "allowed": { "type": "boolean", "example": true } }, "type": "object" }, "staff_members": { "properties": { "used": { "type": "integer", "example": 2 }, "limit": { "type": "integer", "example": 5 }, "allowed": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "Voucher": { "description": "A promotional voucher or discount code", "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid" }, "club_id": { "description": "Associated club ID", "type": "string", "format": "uuid" }, "title": { "description": "Voucher title", "type": "string", "example": "Summer Sale 20% Off" }, "code": { "description": "Voucher code", "type": "string", "example": "SUMMER20" }, "type": { "description": "Type: percentage, fixed_amount, bonus_points", "type": "string", "example": "percentage" }, "discount_amount": { "description": "Discount amount (cents or percentage)", "type": "integer", "example": 2000 }, "min_purchase_amount": { "description": "Minimum purchase in cents", "type": "integer", "example": 5000 }, "max_uses": { "description": "Maximum uses (-1 = unlimited)", "type": "integer", "example": 100 }, "max_uses_per_member": { "description": "Max uses per member", "type": "integer", "example": 1 }, "uses_count": { "description": "Current use count", "type": "integer", "example": 42 }, "valid_from": { "description": "Validity start date", "type": "string", "format": "date-time", "nullable": true }, "valid_until": { "description": "Validity end date", "type": "string", "format": "date-time", "nullable": true }, "is_active": { "description": "Active status", "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Reward": { "description": "A loyalty reward that can be redeemed", "properties": { "id": { "description": "Unique identifier", "type": "string", "format": "uuid" }, "card_id": { "description": "Associated card ID", "type": "string", "format": "uuid" }, "title": { "description": "Reward title", "type": "string", "example": "Free Coffee" }, "description": { "description": "Reward description", "type": "string", "nullable": true }, "points_required": { "description": "Points needed to redeem", "type": "integer", "example": 100 }, "is_active": { "description": "Active status", "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "securitySchemes": { "admin_auth_token": { "type": "http", "description": "Administrator authentication token obtained from the login endpoint. Include in the Authorization header as `Bearer `.", "bearerFormat": "sanctum", "scheme": "bearer" }, "partner_auth_token": { "type": "http", "description": "Partner authentication token obtained from the login endpoint. Include in the Authorization header as `Bearer `.", "bearerFormat": "sanctum", "scheme": "bearer" }, "member_auth_token": { "type": "http", "description": "Member authentication token obtained from the login endpoint. Include in the Authorization header as `Bearer `.", "bearerFormat": "sanctum", "scheme": "bearer" } } }, "tags": [ { "name": "Admin", "description": "Endpoints for platform administrators and managers. Admins can manage partners, view system-wide data, and configure platform settings." }, { "name": "Partner", "description": "Endpoints for business partners (merchants). Partners can manage their clubs, loyalty cards, staff members, and process customer transactions." }, { "name": "Member", "description": "Endpoints for loyalty program members (customers). Members can view their cards, check balances, and track their stamp card progress." }, { "name": "Staff", "description": "Endpoints for staff members operating point-of-sale systems. Staff can look up members, add purchases, award points, add stamps, and redeem rewards and vouchers." } ] }