{
    "openapi": "3.0.3",
    "info": {
        "title": "loyaltyl∞p.in REST API",
        "version": "1.0.0",
        "description": "Full programmatic access to your loyaltyl∞p.in loyalty platform.\n\n**Authentication**: pass your API key via `X-Api-Key` header or `Authorization: Bearer` token.\n\n**Plans**: Growth = 60 req/min · Pro = 300 req/min · Trial/Basic = blocked.\n\nGet your key at **Settings → API** in your dashboard.",
        "contact": {
            "url": "https://loyaltyloop.in/api-docs"
        }
    },
    "servers": [
        {
            "url": "https://loyaltyloop.in/api",
            "description": "Production"
        }
    ],
    "security": [
        {
            "ApiKeyHeader": []
        },
        {
            "BearerToken": []
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyHeader": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key"
            },
            "BearerToken": {
                "type": "http",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Business"
        },
        {
            "name": "Customers"
        },
        {
            "name": "Stamps"
        },
        {
            "name": "Rewards"
        },
        {
            "name": "Transactions"
        },
        {
            "name": "Analytics"
        },
        {
            "name": "Campaigns"
        },
        {
            "name": "Scratch Cards"
        },
        {
            "name": "Team"
        },
        {
            "name": "Branches"
        }
    ],
    "paths": {
        "/business": {
            "get": {
                "tags": [
                    "Business"
                ],
                "summary": "Get business profile",
                "operationId": "getBusiness",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 1,
                                        "business_name": "Sunrise Cafe",
                                        "plan": "professional"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Business"
                ],
                "summary": "Update business profile",
                "operationId": "patchBusiness",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "business_name": {
                                        "type": "string"
                                    },
                                    "business_type": {
                                        "type": "string"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "pincode": {
                                        "type": "string"
                                    },
                                    "gstin": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 1,
                                        "business_name": "Updated Name"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/program": {
            "get": {
                "tags": [
                    "Business"
                ],
                "summary": "Get loyalty program",
                "operationId": "getProgram",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 3,
                                        "program_name": "Sunrise Stamps",
                                        "stamps_required": 8,
                                        "reward_description": "Free coffee",
                                        "is_active": true
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Business"
                ],
                "summary": "Update loyalty program",
                "operationId": "patchProgram",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "program_name": {
                                        "type": "string"
                                    },
                                    "stamps_required": {
                                        "type": "integer"
                                    },
                                    "reward_description": {
                                        "type": "string"
                                    },
                                    "terms_conditions": {
                                        "type": "string"
                                    },
                                    "birthday_bonus_stamps": {
                                        "type": "integer"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "stamps_required": 10
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/customers": {
            "get": {
                "tags": [
                    "Customers"
                ],
                "summary": "List customers",
                "operationId": "listCustomers",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page number (default 1)"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Results per page (max 100)"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Search by name, email, or phone"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 12,
                                            "name": "Priya Sharma",
                                            "current_stamps": 5,
                                            "total_visits": 14
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "post": {
                "tags": [
                    "Customers"
                ],
                "summary": "Enrol a customer",
                "operationId": "createCustomer",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "birthday": {
                                        "type": "string",
                                        "format": "date"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 249,
                                        "qr_code": "a3f9c2d1",
                                        "card_url": "https://loyaltyloop.in/card/a3f9c2d1"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/customers/{id}": {
            "get": {
                "tags": [
                    "Customers"
                ],
                "summary": "Get customer",
                "operationId": "getCustomer",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 12,
                                        "name": "Priya Sharma",
                                        "recent_activity": []
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Customers"
                ],
                "summary": "Delete customer",
                "operationId": "deleteCustomer",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "deleted": true,
                                        "id": 12
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/stamps/add": {
            "post": {
                "tags": [
                    "Stamps"
                ],
                "summary": "Add stamps",
                "operationId": "stampsAdd",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "qr_code"
                                ],
                                "properties": {
                                    "qr_code": {
                                        "type": "string"
                                    },
                                    "count": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 10,
                                        "default": 1
                                    },
                                    "branch_id": {
                                        "type": "integer"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "customer_id": 12,
                                        "stamps_added": 1,
                                        "current_stamps": 6,
                                        "goal": 8,
                                        "reward_earned": false,
                                        "pending_rewards": 1,
                                        "branch_id": 2
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/rewards/redeem": {
            "post": {
                "tags": [
                    "Rewards"
                ],
                "summary": "Redeem a reward",
                "operationId": "rewardsRedeem",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "qr_code"
                                ],
                                "properties": {
                                    "qr_code": {
                                        "type": "string",
                                        "description": "Customer QR code"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "redeemed": true,
                                        "reward": "Free coffee",
                                        "pending_rewards": 0,
                                        "total_redeemed": 3
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/rewards": {
            "get": {
                "tags": [
                    "Rewards"
                ],
                "summary": "List pending rewards",
                "operationId": "listRewards",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page number (default 1)"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Results per page (max 100)"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 12,
                                            "name": "Priya Sharma",
                                            "pending_rewards": 2,
                                            "qr_code": "a3f9c2d1"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/transactions": {
            "get": {
                "tags": [
                    "Transactions"
                ],
                "summary": "List transactions",
                "operationId": "listTransactions",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page number (default 1)"
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Results per page (max 100)"
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "stamp_add",
                                "reward_redeem"
                            ]
                        },
                        "description": "Filter by type"
                    },
                    {
                        "name": "customer_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Filter by customer"
                    },
                    {
                        "name": "branch_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Filter by branch"
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Start date (YYYY-MM-DD)"
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "End date (YYYY-MM-DD)"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 501,
                                            "customer_name": "Priya Sharma",
                                            "transaction_type": "stamp_add",
                                            "branch_name": "Koramangala",
                                            "stamps_added": 1
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/stats": {
            "get": {
                "tags": [
                    "Analytics"
                ],
                "summary": "Summary stats",
                "operationId": "getStats",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "total_customers": 248,
                                        "total_stamps": 1834,
                                        "active_7d": 38,
                                        "stamps_today": 12
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/analytics": {
            "get": {
                "tags": [
                    "Analytics"
                ],
                "summary": "Detailed analytics",
                "operationId": "getAnalytics",
                "parameters": [
                    {
                        "name": "range",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 7,
                            "maximum": 90,
                            "default": 30
                        },
                        "description": "Days (7–90)"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "range_days": 30,
                                        "stamps_per_day": [],
                                        "branch_performance": [],
                                        "redemption_rate_pct": 87.5
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/campaigns": {
            "get": {
                "tags": [
                    "Campaigns"
                ],
                "summary": "List campaigns",
                "operationId": "listCampaigns",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 3,
                                            "name": "Summer Special",
                                            "status": "sent",
                                            "total_recipients": 67
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "post": {
                "tags": [
                    "Campaigns"
                ],
                "summary": "Create campaign (draft)",
                "operationId": "createCampaign",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "subject",
                                    "message"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "subject": {
                                        "type": "string"
                                    },
                                    "message": {
                                        "type": "string"
                                    },
                                    "segment_filter": {
                                        "type": "string",
                                        "enum": [
                                            "all",
                                            "active_30d",
                                            "near_reward",
                                            "inactive_60d"
                                        ],
                                        "default": "all"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 4,
                                        "status": "draft"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/campaigns/{id}/send": {
            "post": {
                "tags": [
                    "Campaigns"
                ],
                "summary": "Send campaign",
                "operationId": "sendCampaign",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "sent": true,
                                        "recipients": 67
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/campaigns/{id}": {
            "delete": {
                "tags": [
                    "Campaigns"
                ],
                "summary": "Delete campaign (draft only)",
                "operationId": "deleteCampaign",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "deleted": true
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/scratch-cards": {
            "get": {
                "tags": [
                    "Scratch Cards"
                ],
                "summary": "List scratch campaigns",
                "operationId": "listScratchCampaigns",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 1,
                                            "name": "Summer Spin",
                                            "is_active": 1,
                                            "total_issued": 48,
                                            "total_won": 12
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "post": {
                "tags": [
                    "Scratch Cards"
                ],
                "summary": "Create scratch campaign",
                "operationId": "createScratchCampaign",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "prizes"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "description": {
                                        "type": "string"
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "prizes": {
                                        "type": "array",
                                        "minItems": 2,
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "label",
                                                "probability"
                                            ],
                                            "properties": {
                                                "label": {
                                                    "type": "string"
                                                },
                                                "probability": {
                                                    "type": "integer",
                                                    "minimum": 1,
                                                    "maximum": 100
                                                },
                                                "is_winner": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 2,
                                        "name": "Summer Spin",
                                        "is_active": true
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/scratch-cards/redeem": {
            "post": {
                "tags": [
                    "Scratch Cards"
                ],
                "summary": "Mark card redeemed",
                "operationId": "redeemScratchCard",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "redeemed": true,
                                        "prize_label": "Free Coffee",
                                        "is_winner": true
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/scratch-cards/{id}/issue": {
            "post": {
                "tags": [
                    "Scratch Cards"
                ],
                "summary": "Issue a scratch card",
                "operationId": "issueScratchCard",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Campaign ID"
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "customer_id": {
                                        "type": "integer"
                                    },
                                    "expires_days": {
                                        "type": "integer",
                                        "default": 30
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 73,
                                        "token": "4f2a9c1e...",
                                        "card_url": "https://loyaltyloop.in/scratch/4f2a9c1e...",
                                        "expires_at": "2026-06-16"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/scratch-cards/{id}/toggle": {
            "post": {
                "tags": [
                    "Scratch Cards"
                ],
                "summary": "Pause / activate campaign",
                "operationId": "toggleScratchCampaign",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 2,
                                        "is_active": false
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/team": {
            "get": {
                "tags": [
                    "Team"
                ],
                "summary": "List team members",
                "operationId": "listTeam",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 7,
                                            "name": "Neha Staff",
                                            "email": "neha@sunrise.com",
                                            "role": "staff",
                                            "is_active": 1
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "post": {
                "tags": [
                    "Team"
                ],
                "summary": "Add staff member",
                "operationId": "createTeamMember",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "email"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 8,
                                        "name": "Neha Singh",
                                        "email": "neha@sunrise.com",
                                        "role": "staff",
                                        "temp_password": "b3f9a2c1d4e5"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/team/{id}": {
            "delete": {
                "tags": [
                    "Team"
                ],
                "summary": "Remove staff member",
                "operationId": "deleteTeamMember",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "deleted": true,
                                        "id": 8
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/branches": {
            "get": {
                "tags": [
                    "Branches"
                ],
                "summary": "List branches",
                "operationId": "listBranches",
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 2,
                                            "name": "Koramangala",
                                            "city": "Bengaluru",
                                            "latitude": 12.9352,
                                            "longitude": 77.6245,
                                            "is_active": 1
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "post": {
                "tags": [
                    "Branches"
                ],
                "summary": "Create branch",
                "operationId": "createBranch",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "format": "float"
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "format": "float"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 3,
                                        "name": "Indiranagar",
                                        "latitude": 12.9784,
                                        "longitude": 77.6408,
                                        "is_active": 1
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/branches/nearest": {
            "get": {
                "tags": [
                    "Branches"
                ],
                "summary": "Find nearest branch (GPS)",
                "operationId": "branchesNearest",
                "description": "Returns the closest branch to the given GPS coordinates using the Haversine formula. Use this before `POST /stamps/add` to auto-detect which location the customer is at.",
                "parameters": [
                    {
                        "name": "lat",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "float"
                        },
                        "description": "Device latitude"
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "float"
                        },
                        "description": "Device longitude"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "branch_id": 2,
                                        "name": "Koramangala",
                                        "latitude": 12.9352,
                                        "longitude": 77.6245,
                                        "distance_km": 0.084,
                                        "distance_m": 84
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/branches/{id}": {
            "patch": {
                "tags": [
                    "Branches"
                ],
                "summary": "Update branch",
                "operationId": "updateBranch",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "latitude": {
                                        "type": "number",
                                        "format": "float"
                                    },
                                    "longitude": {
                                        "type": "number",
                                        "format": "float"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 3,
                                        "name": "Indiranagar",
                                        "latitude": 12.9784
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Branches"
                ],
                "summary": "Delete branch",
                "operationId": "deleteBranch",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "deleted": true,
                                        "id": 3
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden — plan restriction"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Conflict"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        }
    }
}