{ "openapi": "3.0.3", "info": { "title": "ScreenGrid Smart Cards API", "version": "1.0.0", "description": "Tenant-scoped referrals and purchase-based rewards. Test and live keys are isolated. See /smart-cards/docs for complete workflows." }, "servers": [ { "url": "https://screengrid.co/api/smart-cards/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "sg_test_ or sg_live_ secret API key; backend only" } }, "schemas": { "Member": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "balance": { "type": "integer" }, "verified": { "type": "boolean" }, "phone_hint": { "type": "string" }, "google_linked": { "type": "boolean" }, "created_at": { "type": "string" } } }, "Referral": { "type": "object", "properties": { "valid": { "type": "boolean" }, "referrer_verified": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "code": { "type": "string", "nullable": true } } }, "Eligibility": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string", "nullable": true, "enum": [ null, "invalid_code", "verification_required", "self_referral", "referral_not_attached", "already_qualified" ] }, "minimum_cents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "CAD", "USD" ] } } }, "Conversion": { "type": "object", "properties": { "id": { "type": "string" }, "program_id": { "type": "string" }, "external_id": { "type": "string" }, "member_id": { "type": "string" }, "referrer_id": { "type": "string" }, "created_at": { "type": "string" }, "amount_cents": { "type": "integer" }, "referral_points": { "type": "integer" }, "welcome_points": { "type": "integer" }, "status": { "type": "string", "enum": [ "confirmed", "refunded" ] }, "replayed": { "type": "boolean" } } }, "Reward": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "points": { "type": "integer" } } }, "Voucher": { "type": "object", "properties": { "code": { "type": "string" }, "reward_name": { "type": "string" }, "member_id": { "type": "string" }, "expires_at": { "type": "string" }, "used_at": { "type": "string", "nullable": true }, "points": { "type": "integer" }, "valid": { "type": "boolean" }, "replayed": { "type": "boolean" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "request_id": { "type": "string" } } } } }, "paths": { "/referrals/{code}": { "get": { "summary": "Validate a referral", "description": "Required scope: referrals:read", "operationId": "get_referrals_code", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Referral" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/members/resolve": { "post": { "summary": "Exchange a one-use customer handoff", "description": "Required scope: members:read", "operationId": "post_members_resolve", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket" ], "properties": { "ticket": { "type": "string" } } } } } } } }, "/members/{id}": { "get": { "summary": "Read a member", "description": "Required scope: members:read", "operationId": "get_members_id", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/eligibility": { "post": { "summary": "Check first-purchase eligibility", "description": "Required scope: referrals:read", "operationId": "post_eligibility", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eligibility" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "member_id", "referral_code" ], "properties": { "member_id": { "type": "string", "format": "uuid" }, "referral_code": { "type": "string" } } } } } } } }, "/conversions": { "post": { "summary": "Confirm a first purchase", "description": "Required scope: conversions:write", "operationId": "post_conversions", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "member_id", "external_id", "amount_cents" ], "properties": { "member_id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 } } } } } } } }, "/refunds": { "post": { "summary": "Reverse points for a refund", "description": "Required scope: conversions:write", "operationId": "post_refunds", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversion" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_id" ], "properties": { "external_id": { "type": "string" } } } } } } } }, "/rewards": { "get": { "summary": "List available rewards", "description": "Required scope: rewards:read", "operationId": "get_rewards", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "$ref": "#/components/schemas/Reward" } } } } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/vouchers/check": { "post": { "summary": "Inspect a voucher", "description": "Required scope: rewards:read", "operationId": "post_vouchers_check", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voucher" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } } } }, "/vouchers/redeem": { "post": { "summary": "Redeem a voucher once", "description": "Required scope: rewards:redeem", "operationId": "post_vouchers_redeem", "responses": { "200": { "description": "Successful request. Idempotent purchase/redemption retries may return replayed=true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voucher" } } } }, "400": { "description": "Invalid input or business rule failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } } } } } }