{ "openapi": "3.1.0", "info": { "title": "OpenAPI Plant Store", "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.gameball.co" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v4.0/integrations/customers": { "post": { "summary": "Create Customer", "description": "Create or update a customer profile in Gameball using a unique customerId. Serving as a consistent identity, this customerId allows you to track a customer's entire journey.", "operationId": "createCustomer", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Customer payload containing identifiers and attributes.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerRequest" } } } }, "responses": { "200": { "description": "Customer created or updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}": { "get": { "summary": "Get Customer", "description": "Retrieve essential customer information from Gameball using a unique customerId. Returns general customer info (no personal data) with the public key.", "operationId": "getCustomer", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "404": { "description": "Customer not found" } } }, "delete": { "summary": "Delete Customer", "description": "Remove a customer profile and associated data from the system.", "operationId": "deleteCustomer", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer deleted successfully" }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/details": { "get": { "summary": "Get Customer Details", "description": "Retrieve comprehensive customer information including personally identifiable information (PII).", "operationId": "getCustomerDetails", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer details found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDetailsResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/coupons": { "get": { "summary": "Get Customer Coupons", "description": "Retrieve customer's available coupons with detailed information on each coupon's type, status, and usage.", "operationId": "getCustomerCoupons", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer coupons found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCouponsResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/hash": { "get": { "summary": "Get Customer Hash", "description": "Generate a hash for an existing customer based on their unique customerId.", "operationId": "getCustomerHash", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer hash generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerHashResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/referrals/validate": { "get": { "summary": "Validate Referrer Code", "description": "Validate whether a provided referral code is valid and eligible for use during customer signup.", "operationId": "validateReferrerCode", "security": [{ "apiKey": [] }], "parameters": [ { "name": "referrerCode", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The referral code to validate" }, { "name": "forCustomerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Customer ID to prevent self-referral" } ], "responses": { "200": { "description": "Referral code validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralValidationResponse" } } } } } } }, "/api/v4.0/integrations/payments": { "post": { "description": "Track a new payment to reward customer transactions and manage loyalty accrual.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "paymentId", "paymentDate", "totalPaid"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "paymentId": { "type": "string" }, "paymentDate": { "type": "string", "format": "date-time" }, "totalPaid": { "type": "number" }, "totalAmount": { "type": "number" }, "totalDiscount": { "type": "number" }, "totalProcessingFees": { "type": "number" }, "totalTax": { "type": "number" }, "paymentDetails": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string" }, "serviceName": { "type": "string" }, "serviceProvider": { "type": "string" }, "amount": { "type": "number" }, "tax": { "type": "number" }, "discount": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "array", "items": { "type": "string" } }, "extra": { "type": "object", "additionalProperties": true } } } }, "redemption": { "type": "object", "properties": { "pointsHoldReference": { "type": "string" }, "couponsLockReference": { "type": "string" }, "couponCodes": { "type": "array", "items": { "type": "string" } } } }, "extra": { "type": "object", "additionalProperties": true }, "merchant": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "name": { "type": "string" }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string" }, "name": { "type": "string" } } } } }, "guest": { "type": "boolean" }, "channel": { "type": "string", "enum": ["mobile", "pos", "web", "callcenter"] }, "cashbackConfigurations": { "type": "object", "properties": { "returnWindow": { "type": "integer" } } } } } } } }, "responses": { "200": { "description": "Payment tracked", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string" }, "redeemedPoints": { "type": "number" }, "rewardedPoints": { "type": "number" }, "paymentDetails": { "type": "array", "items": { "type": "object", "properties": { "serviceId": { "type": "string" }, "decimalPoints": { "type": "number" }, "points": { "type": "number" }, "score": { "type": "number" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/redeem": { "post": { "description": "Redeem loyalty points as a payment method for customer transactions.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "points", "transactionId"], "properties": { "customerId": { "type": "string" }, "points": { "type": "number" }, "transactionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Points redeemed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "remainingPoints": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/cashback": { "post": { "description": "Issue cashback rewards to customers for their transactions.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "amount", "transactionId"], "properties": { "customerId": { "type": "string" }, "amount": { "type": "number" }, "transactionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cashback issued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "newBalance": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/refund": { "post": { "description": "Process refunds for previous point redemption transactions.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "originalTransactionId", "refundAmount"], "properties": { "customerId": { "type": "string" }, "originalTransactionId": { "type": "string" }, "refundAmount": { "type": "number" } } } } } }, "responses": { "200": { "description": "Refund processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "refundedPoints": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/hold": { "post": { "description": "Place points on hold before redemption to reserve them for a specific transaction.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "points", "holdReference"], "properties": { "customerId": { "type": "string" }, "points": { "type": "number" }, "holdReference": { "type": "string" } } } } } }, "responses": { "200": { "description": "Points placed on hold successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "holdReference": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/release": { "post": { "description": "Release held points for redemption or cancel the hold.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["holdReference", "action"], "properties": { "holdReference": { "type": "string" }, "action": { "type": "string", "enum": ["redeem", "cancel"] } } } } } }, "responses": { "200": { "description": "Hold released successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "pointsReleased": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/hold/{holdReference}": { "get": { "description": "Retrieve details of held points for a specific hold reference.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "holdReference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Hold details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "holdReference": { "type": "string" }, "customerId": { "type": "string" }, "pointsHeld": { "type": "number" }, "holdDate": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions": { "get": { "description": "Retrieve customer transaction history with filtering and pagination options.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/manual": { "post": { "description": "Add manual point adjustments to customer accounts.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "points", "reason"], "properties": { "customerId": { "type": "string" }, "points": { "type": "number" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Manual transaction added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "newBalance": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/otp": { "post": { "description": "Generate one-time password for transaction verification.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "transactionId"], "properties": { "customerId": { "type": "string" }, "transactionId": { "type": "string" }, "mobile": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "otpId": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/transactions/otp/validate": { "post": { "description": "Validate OTP to authorize transaction.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["otpId", "otpCode", "transactionId"], "properties": { "otpId": { "type": "string" }, "otpCode": { "type": "string" }, "transactionId": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "authorized": { "type": "boolean" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/predefined": { "post": { "description": "Create a coupon based on predefined redemption rules.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "ruleId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "ruleId": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Coupon generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "expiryDate": { "type": "string", "format": "date-time" }, "url": { "type": "string" }, "pin": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/{code}/validate": { "post": { "description": "Validate a single coupon and optionally lock it for exclusive use.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "lock": { "type": "boolean" }, "pin": { "type": "string" } } } } } }, "responses": { "200": { "description": "Coupon validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isValid": { "type": "boolean" }, "lockReference": { "type": "string" }, "discountAmount": { "type": "number" }, "discountType": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/validate": { "post": { "description": "Validate multiple coupons at once and optionally lock them for exclusive use.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "coupons"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "coupons": { "type": "array", "items": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" }, "pin": { "type": "string" } } } }, "lock": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Coupons validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "validCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "lockReference": { "type": "string" }, "discountAmount": { "type": "number" }, "discountType": { "type": "string" } } } }, "invalidCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/{code}/burn": { "post": { "description": "Mark a coupon as used/consumed to prevent further usage.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "lockReference": { "type": "string" }, "pin": { "type": "string" } } } } } }, "responses": { "200": { "description": "Coupon burned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "burnedAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/{lockReference}": { "get": { "description": "Retrieve details of locked coupons using the lock reference.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "lockReference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lock details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "lockReference": { "type": "string" }, "customerId": { "type": "string" }, "lockedCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "lockedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "description": "Release locked coupons to make them available for use again.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "lockReference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coupons released successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "releasedAt": { "type": "string", "format": "date-time" }, "releasedCoupons": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/coupons/automatic": { "post": { "description": "Apply predefined automatic coupons based on specific promotional criteria.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "cartId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "cartId": { "type": "string" }, "totalPrice": { "type": "number" }, "totalShipping": { "type": "number" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number" }, "sku": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": "array", "items": { "type": "string" } }, "weight": { "type": "number" }, "vendor": { "type": "string" }, "collection": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "taxes": { "type": "number" }, "discount": { "type": "number" }, "extra": { "type": "object", "additionalProperties": true } } } }, "merchant": { "type": "object", "properties": { "uniqueId": { "type": "string" }, "name": { "type": "string" }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string" }, "name": { "type": "string" } } } } } } } } } }, "responses": { "200": { "description": "Automatic coupon applied successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isApplied": { "type": "boolean" }, "couponName": { "type": "string" }, "discountAmount": { "type": "number" }, "discountType": { "type": "string", "enum": ["shipping", "fixed", "percentage", "product", "buyXgetY"] }, "discountedItems": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "quantity": { "type": "number" }, "discount": { "type": "number" }, "price": { "type": "number" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/rewards/cashback": { "get": { "description": "Retrieve cashback configuration settings for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Cashback settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "type": "number" }, "minimumOrderValue": { "type": "number" }, "maximumCashback": { "type": "number" }, "enabled": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/rewards/redemption": { "get": { "description": "Retrieve point redemption configuration settings for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Redemption settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "minimumPoints": { "type": "number" }, "pointValue": { "type": "number" }, "maximumRedemption": { "type": "number" }, "enabled": { "type": "boolean" }, "redemptionMethods": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/rewards/coupons": { "get": { "description": "Retrieve coupon system configuration settings for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Coupon settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maximumCoupons": { "type": "number" }, "couponTypes": { "type": "array", "items": { "type": "string" } }, "expirationSettings": { "type": "object", "properties": { "defaultExpiryDays": { "type": "number" }, "maxExpiryDays": { "type": "number" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "description": "Update coupon system configuration settings for the loyalty program.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maximumCoupons": { "type": "number" }, "couponTypes": { "type": "array", "items": { "type": "string" } }, "expirationSettings": { "type": "object", "properties": { "defaultExpiryDays": { "type": "number" }, "maxExpiryDays": { "type": "number" } } } } } } } }, "responses": { "200": { "description": "Coupon settings updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/program/campaigns": { "get": { "description": "Retrieve active campaigns configuration for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "isActive": { "type": "boolean" }, "rewardType": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/program/tiers": { "get": { "description": "Retrieve VIP tier configurations for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "VIP tiers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "minimumPoints": { "type": "number" }, "benefits": { "type": "array", "items": { "type": "string" } }, "color": { "type": "string" }, "isActive": { "type": "boolean" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/program/referrals": { "get": { "description": "Retrieve referral program configuration for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Referral settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "referrerReward": { "type": "number" }, "refereeReward": { "type": "number" }, "minimumReferrals": { "type": "number" }, "referralCodeLength": { "type": "number" }, "expirationDays": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/configurations/widget": { "get": { "description": "Retrieve styling settings, including colors and other visual elements for the Gameball widget.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Widget configuration retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "colors": { "type": "object", "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" }, "accent": { "type": "string" }, "background": { "type": "string" }, "text": { "type": "string" } } }, "layout": { "type": "object", "properties": { "position": { "type": "string", "enum": ["bottom-right", "bottom-left", "top-right", "top-left"] }, "size": { "type": "string", "enum": ["small", "medium", "large"] }, "showOnMobile": { "type": "boolean" } } }, "features": { "type": "object", "properties": { "showBalance": { "type": "boolean" }, "showPoints": { "type": "boolean" }, "showTier": { "type": "boolean" }, "showNotifications": { "type": "boolean" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/leaderboard": { "get": { "description": "Retrieve leaderboard rankings of customers within your loyalty program in Gameball, either for a specific date range or for all time.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "from", "in": "query", "description": "The start date of the leaderboard range. If not provided, the leaderboard shows all-time data.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "The end date of the leaderboard range. If not provided, the leaderboard shows all-time data.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "customerId", "in": "query", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. It is used to get the rank of this customer in the leaderboard.", "required": false, "schema": { "type": "string" } }, { "name": "rewardCampaignId", "in": "query", "description": "Filter leaderboard results based on a specific reward campaign.", "required": false, "schema": { "type": "integer" } }, { "name": "customerTag", "in": "query", "description": "Filter results by customers who are tagged with a specific tag.", "required": false, "schema": { "type": "string" } }, { "name": "rewardCampaignTag", "in": "query", "description": "Filter leaderboard results by reward campaign tags.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Leaderboard retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "leaderboard": { "type": "array", "items": { "type": "object", "properties": { "displayName": { "type": "string" }, "customerId": { "type": "string" }, "progress": { "type": "number" }, "rank": { "type": "number" }, "tierName": { "type": "string" }, "tierIcon": { "type": "string" } } } }, "customerRank": { "type": "number" }, "customersCount": { "type": "number" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/customers": { "post": { "description": "Create or update multiple customer profiles in a single API call for bulk user imports and mass profile updates.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer." }, "email": { "type": "string", "description": "Customer's email address. Required if your account uses email-based channel merging." }, "mobile": { "type": "string", "description": "Customer's mobile number. Required if your account uses mobile-based channel merging." }, "deviceToken": { "type": "string", "description": "Token used to identify the device." }, "osType": { "type": "string", "description": "Operating system type of the device." }, "customerAttributes": { "type": "object", "description": "Additional customer-specific attributes. Includes attributes such as the customer's name, contact details, and purchase history.", "properties": { "displayName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "gender": { "type": "string" }, "mobile": { "type": "string" }, "dateOfBirth": { "type": "string" }, "joinDate": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "zip": { "type": "string" }, "preferredLanguage": { "type": "string" }, "tags": { "type": "string" }, "source": { "type": "string" }, "utms": { "type": "array" }, "devices": { "type": "array" }, "paymentMethods": { "type": "array" }, "totalSpent": { "type": "number" }, "lastOrderDate": { "type": "string" }, "totalOrders": { "type": "integer" }, "avgOrderAmount": { "type": "number" }, "channel": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "Batch customer data processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/orders": { "post": { "description": "Register multiple orders for single or multiple customers in a single API call for efficient order management and tracking.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId", "orderId", "orderDate", "totalPaid"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer." }, "orderId": { "type": "string", "description": "Unique identifier for the order." }, "orderDate": { "type": "string", "format": "date-time", "description": "Date and time of the order." }, "totalPaid": { "type": "number", "description": "Total amount paid for the order." } } } } } } } } }, "responses": { "200": { "description": "Batch order processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/balance-inquiry": { "post": { "description": "Retrieve customer loyalty balances for multiple customers in a single API call for efficient balance management.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer." } } } } } } } } }, "responses": { "200": { "description": "Batch balance inquiry processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/balance-adjustment": { "post": { "description": "Adjust customer loyalty balances for multiple customers in a single API call for efficient balance management.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId", "amount"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer." }, "amount": { "type": "number", "description": "Amount to adjust the balance by." }, "reason": { "type": "string", "description": "Reason for the balance adjustment." } } } } } } } } }, "responses": { "200": { "description": "Batch balance adjustment processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/cashback": { "post": { "description": "Award loyalty points to customers through cashback program for multiple customers in a single API call.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId", "transactionId", "transactionTime", "amount"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime." }, "email": { "type": "string", "description": "Customer's email address. Required if your account uses email-based channel merging." }, "mobile": { "type": "string", "description": "Customer's mobile number. Required if your account uses mobile-based channel merging." }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number)." }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system." }, "amount": { "type": "number", "description": "Monetary value of the transaction for which the customer will be rewarded." } } } } } } } } }, "responses": { "200": { "description": "Batch cashback reward processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/redeem": { "post": { "description": "Enable customers to redeem loyalty points as a payment method for multiple customers in a single API call.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId", "transactionId", "transactionTime"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime." }, "email": { "type": "string", "description": "Customer's email address. Required if your account uses email-based channel merging." }, "mobile": { "type": "string", "description": "Customer's mobile number. Required if your account uses mobile-based channel merging." }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number)." }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system." }, "amount": { "type": "number", "description": "The actual monetary value the customer wants to redeem." }, "points": { "type": "integer", "description": "The number of points the customer wants to redeem from their balance." }, "holdReference": { "type": "string", "description": "A unique reference obtained from the Hold Points API." } } } } } } } } }, "responses": { "200": { "description": "Batch redemption processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batch/events": { "post": { "description": "Track multiple user actions or multiple actions for a single user in a single API call for efficient event tracking and analytics.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "array", "items": { "type": "object", "required": ["customerId", "events"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer." }, "events": { "type": "object", "description": "Object containing event names as keys and their metadata as values.", "additionalProperties": { "type": "object", "description": "Event metadata containing relevant attributes for the event." } } } } } } } } } }, "responses": { "200": { "description": "Batch event processing initiated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "number", "description": "The assigned job ID, which is later used for status verification and response retrieval." } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batches/{batchId}/status": { "get": { "description": "Monitor batch job status and results for ongoing batch operations.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the batch operation" } ], "responses": { "200": { "description": "Batch status retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "progress": { "type": "number" }, "totalItems": { "type": "number" }, "processedItems": { "type": "number" }, "failedItems": { "type": "number" }, "results": { "type": "array" }, "errors": { "type": "array" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/batches/{batchId}/stop": { "post": { "description": "Stop ongoing batch operations when needed.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the batch operation" } ], "responses": { "200": { "description": "Batch operation stopped successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v4.0/integrations/orders": { "post": { "summary": "Track Order", "description": "The API call is used to track a new order and is specifically designed for e-commerce solutions. It helps capture essential order details, enabling better tracking of customer purchases and order management.\n\n**Security:** Requires both `apikey` and `secretkey` headers.\n\n**Channel Merging Available:** If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer's mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.", "operationId": "trackOrder", "tags": ["Orders"], "security": [ { "apiKey": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "orderId", "orderDate", "totalPaid"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.", "example": "cust_123456789" }, "email": { "type": "string", "description": "Customer's email address. **Note:** This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. **Note:** This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "orderId": { "type": "string", "description": "Unique identifier for the order on your system. This ID is case-sensitive.", "example": "ORD12345" }, "orderDate": { "type": "string", "format": "date-time", "description": "Timestamp of when the order was placed.", "example": "2024-10-16T08:13:29.290Z" }, "totalPaid": { "type": "number", "description": "The actual amount paid by the customer for the order, accounting for any discounts or coupons applied. Unlike `totalPrice`, which reflects the original cost of the order, `totalPaid` represents the final amount the customer paid at checkout after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the order. **Example:** A customer purchases items worth $120, including taxes and shipping. If a $20 coupon is applied, the `totalPaid` becomes $100, reflecting the discounted amount the customer paid.", "example": 250.75 }, "totalPrice": { "type": "number", "description": "The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value. **Example:** A customer purchases items worth $120, including taxes and shipping. Even if a $20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.", "example": 300 }, "totalDiscount": { "type": "number", "description": "Total discount applied to the order.", "example": 50 }, "totalShipping": { "type": "number", "description": "Total shipping cost associated with the order.", "example": 10 }, "totalTax": { "type": "number", "description": "Total tax amount for the order.", "example": 15 }, "lineItems": { "type": "array", "description": "An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product or service being purchased.", "example": "PROD98765" }, "quantity": { "type": "number", "description": "Number of units purchased for this product or service.", "example": 2 }, "price": { "type": "number", "description": "The original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order. **Example:** If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.", "example": 100 }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) for the product.", "example": "SKU98765" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the product for categorization or promotional purposes.", "example": ["electronics", "smartphone"] }, "category": { "type": "array", "items": { "type": "string" }, "description": "Product category, such as fashion or electronics. It can include one or multiple categories.", "example": ["mobile phones"] }, "weight": { "type": "number", "description": "Weight of the product.", "example": 0.5 }, "vendor": { "type": "string", "description": "Vendor or manufacturer of the product.", "example": "TechVendor" }, "collection": { "type": "array", "items": { "type": "string" }, "description": "Collection ID(s) to which the product belongs. It can include one or multiple collections.", "example": ["latest gadgets"] }, "title": { "type": "string", "description": "Product title or name.", "example": "Smartphone XYZ" }, "taxes": { "type": "number", "description": "The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.", "example": 7.5 }, "discount": { "type": "number", "description": "The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.", "example": 25 }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number.", "example": { "subClass": "SUBCLASS123" } } } } }, "redemption": { "type": "object", "description": "Redemption details for the order, including points held for redemption.", "properties": { "pointsHoldReference": { "type": "string", "description": "Reference from the Hold Points API for redeeming held points. For more details on how hold references are generated and utilized, refer to the Transactions section.", "example": "HOLD123" }, "couponsLockReference": { "type": "string", "description": "The lock reference for the coupon is a unique identifier used to 'lock' a coupon for a specific customer or order. This prevents the coupon from being used by others or on multiple transactions. For more details on how to generate and use lock references, refer to the Coupons section.", "example": "LOCK123" }, "couponCodes": { "type": "array", "items": { "type": "string" }, "description": "A list of coupon codes that were applied to the order. Each code in the array represents a different discount or promotional coupon used during the checkout process. Coupon codes must be locked before they can be used for redemption.", "example": ["DISCOUNT10"] } } }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the order. The values must be of type string or number. **Example:** If your business offers gift options, you might want to include a personalized gift message with the order. Additionally, specific delivery instructions can be recorded to ensure smooth delivery and provide a personalized experience.", "example": { "paymentMethod": "CREDIT CARD" } }, "merchant": { "type": "object", "description": "This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the merchant.", "example": "MERCH001" }, "name": { "type": "string", "description": "Name of the merchant.", "example": "TechGadgetStore" }, "branch": { "type": "object", "description": "Branch information where the order took place.", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the order took place.", "example": "BRANCH001" }, "name": { "type": "string", "description": "Name of the branch where the order took place.", "example": "Downtown Branch" } } } } }, "guest": { "type": "boolean", "description": "Indicates whether the customer is a guest (not signed up). Set this to `true` for guest users; otherwise, they are treated as registered customers by default.", "default": false, "example": false }, "channel": { "type": "string", "enum": ["mobile", "pos", "web", "callcenter"], "description": "The channel through which the order was placed helps track the origin of the order, particularly useful for systems that support multiple sales or communication channels. By identifying the channel, you can gain valuable insights into customer behavior, optimize channel-specific strategies, and ensure efficient handling of orders across platforms. **Possible values:** `mobile` - The order was placed through your mobile application. `pos` - The order was placed in person using a Point of Sale (POS) system, such as at a physical store or outlet. `web` - The order was placed through your website. `callcenter` - The order was placed over the phone by contacting a customer service representative or a call center.", "example": "pos" }, "cartId": { "type": "string", "description": "Identifier for the shopping cart associated with the order.", "example": "CART98765" }, "cashbackConfigurations": { "type": "object", "description": "This object contains configurations related to the cashback settings.", "properties": { "returnWindow": { "type": "integer", "description": "The number of days the cashback will stay in a **pending** state, typically aligning with the return window in e-commerce to account for potential order cancellations or refunds. The value should be between **0 and 7,300 days (20 years)**.", "minimum": 0, "maximum": 7300, "example": 7 } } } } } } } }, "responses": { "200": { "description": "Order tracked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.", "example": "cust_123456789" }, "redeemedPoints": { "type": "number", "description": "Points redeemed by the customer for this order, if applicable. **Example:** If a customer has accumulated 500 points and decides to redeem 100 points for a discount on their current order, the `redeemedPoints` value for that transaction will be 100. This helps track how many points were used in the transaction and what benefits were applied to the order based on the customer's redeemed points.", "example": 1000 }, "rewardedPoints": { "type": "number", "description": "The total number of points rewarded to the customer for making this order. These points are typically awarded based on your configured cashback rewards. **Example:** If the store rewards 10 points for every $1 spent, and a customer places an order worth $50, the **rewardedPoints** for this order would be 500 points.", "example": 101 }, "lineItems": { "type": "array", "description": "Details about each product or service in the order, including points rewarded.", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product or service.", "example": "PROD98765" }, "quantity": { "type": "number", "description": "Number of units purchased for this product or service.", "example": 2 }, "decimalPoints": { "type": "number", "description": "Fractional points rewarded for this line item.", "example": 91.25 }, "points": { "type": "number", "description": "Any points rewarded for this line item.", "example": 91 }, "score": { "type": "number", "description": "Any score awarded for the line item, if applicable.", "example": 0 } } } } } } } } }, "400": { "description": "Bad request" } } } }, "/api/v4.0/integrations/orders/cashback": { "post": { "summary": "Calculate Order Cashback", "description": "This API calculates the cashback points to be rewarded for a specific order in Gameball, based on provided order details. It considers configured cashback rules and customer eligibility.\n\n**Security:** Requires `apiKey` header.\n\n**Channel Merging Available:** If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer's mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.\n\n**Important:** This API calculates the expected cashback points but does not perform any actual reward or action for the customer.", "operationId": "calculateOrderCashback", "tags": ["Orders"], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["totalPaid", "totalDiscount", "totalShipping"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. If provided, the cashback calculation will consider the customer's tier. Special tier-based configurations, such as enhanced point accrual rates, may affect the points calculation.", "example": "cust_12345abc" }, "email": { "type": "string", "description": "Customer's email address. **Note:** This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. **Note:** This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "totalPaid": { "type": "number", "description": "The actual amount paid by the customer for the order, accounting for any discounts or coupons applied. Unlike `totalPrice`, which reflects the original cost of the order, `totalPaid` represents the final amount the customer paid at checkout after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the order. **Example:** A customer purchases items worth $120, including taxes and shipping. If a $20 coupon is applied, the `totalPaid` becomes $100, reflecting the discounted amount the customer paid. This is the value used to calculate any points or rewards earned from the order.", "example": 350 }, "totalPrice": { "type": "number", "description": "The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value. **Example:** A customer purchases items worth $120, including taxes and shipping. Even if a $20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.", "example": 350 }, "totalDiscount": { "type": "number", "description": "Total discount applied to the order. Must be positive.", "minimum": 0, "example": 0 }, "totalShipping": { "type": "number", "description": "Total shipping cost for the order.", "example": 0 }, "lineItems": { "type": "array", "description": "An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product or service being purchased.", "example": "875511" }, "quantity": { "type": "number", "description": "Number of units purchased for this product or service.", "example": 1 }, "price": { "type": "number", "description": "The original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order. **Example:** If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.", "example": 150 }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) for the product.", "example": "sku123" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the product for categorization or promotional purposes." }, "category": { "type": "array", "items": { "type": "string" }, "description": "Product category, such as fashion or electronics. It can include one or multiple categories. Example: [\"natural\", \"cosmetics\"]" }, "weight": { "type": "number", "description": "Weight of the product." }, "vendor": { "type": "string", "description": "Vendor or manufacturer of the product." }, "collection": { "type": "array", "items": { "type": "string" }, "description": "Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: [\"14313\", \"4343\"]", "example": ["123"] }, "title": { "type": "string", "description": "Product title or name." }, "taxes": { "type": "number", "description": "The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.", "example": 0 }, "discount": { "type": "number", "description": "The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.", "example": 0 }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number." } } } }, "merchant": { "type": "object", "description": "This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the merchant.", "example": "MERCH001" }, "name": { "type": "string", "description": "Name of the merchant.", "example": "TechGadgetStore" }, "branch": { "type": "object", "description": "Branch information where the order took place.", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the order took place.", "example": "BRANCH001" }, "name": { "type": "string", "description": "Name of the branch where the order took place.", "example": "Downtown Branch" } } } } } } } } } }, "responses": { "200": { "description": "Cashback calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalPoints": { "type": "number", "description": "Total points expected to be earned from the entire order.", "example": 19000 }, "totalScore": { "type": "number", "description": "Total score expected to be earned from the entire order.", "example": 0 }, "lineItems": { "type": "array", "description": "An array of individual line items and their cashback calculation details.", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product.", "example": "875511" }, "quantity": { "type": "number", "description": "The quantity of the product purchased.", "example": 1 }, "totalDecimalPoints": { "type": "number", "description": "The total decimal points earned for this line item, including any campaign impact.", "example": 15000.0 }, "totalPoints": { "type": "number", "description": "The total points earned for this line item, including any campaign impact. **Example:** If the base points for a product are 50 and a campaign adds 150 points, the totalPoints would be 200.", "example": 15000 }, "totalScore": { "type": "number", "description": "The total score earned for this line item. This value is separate from point and is based on your cashback rewards configuration.", "example": 0 }, "rewardWalletFactor": { "type": "number", "description": "The multiplier applied to the product price to calculate the base points earned for this line item. This factor represents how many points are earned per unit of currency spent on the product. **Example:** If the store rewards 10 points for every $1 spent, the rewardWalletFactor would be 10.", "example": 20.0 }, "campaignId": { "type": ["integer", "null"], "description": "The unique identifier for the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null.", "example": 2149 }, "campaignName": { "type": ["string", "null"], "description": "The name of the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null. **Example:** If a store is running a \"Double Points Weekend\" campaign, the campaignName could be \"Double Points Weekend.\"", "example": "5x Points Campaign" }, "campaignEndDate": { "type": ["string", "null"], "format": "date-time", "description": "The end date of the active campaign affecting the line item. This is the date when the campaign will no longer influence points or rewards.", "example": "2024-11-01T08:39:00" }, "campaignImpactWalletFactor": { "type": "number", "description": "The multiplier applied by the campaign to the base points calculation. This factor adjusts the final points earned for the line item based on the campaign's impact. Present only if a campaign is applicable. **Example:** If the campaign offers 3x points, the campaignImpactWalletFactor would be 3, multiplying the regular points earned by three.", "example": 5.0 }, "campaignImpactPoints": { "type": "number", "description": "The total number of points given for this line item due to the campaign's impact. This value reflects the additional points earned from the campaign. **Example:** If the base points for an item are 100 and the campaign offers 5x points, the campaignImpactPoints would be 400 (totaling 500 points with the base points included).", "example": 12000.0 } } } } } } } } } } } }, "/api/v4.0/integrations/orders/{orderId}/transactions": { "get": { "summary": "Order Transactions", "description": "This API retrieves the transactional details for a specified order in Gameball, identified by `orderId`. It includes information on rewards, refunds, and equivalent points, giving a detailed view of the financial activities associated with the order.\n\n**Security:** Requires both `apikey` and `secretkey` headers.", "operationId": "getOrderTransactions", "tags": ["Orders"], "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the order, which is case-sensitive. It is used to reference and retrieve the order's transactions accurately.", "example": "ORD12345" } ], "responses": { "200": { "description": "Order transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "description": "List of transactions associated with the order. **Example:** If a customer places an order and redeems points, the transactions array will contain both the cashback reward transaction and the redemption transaction.", "items": { "type": "object", "properties": { "transactionDate": { "type": "string", "format": "date-time", "description": "The date and time when the transaction occurred.", "example": "2024-10-16T08:13:29.29" }, "gameballTransactionId": { "type": "integer", "description": "Unique identifier for the transaction in the Gameball system.", "example": 11034754 }, "transactionType": { "type": "string", "description": "Type of transaction. Possible values include: **AchievementReward** - Captured when a customer reaches a VIP tier, participates in a reward campaign, or makes a referral. **PaymentReward** - Recorded for rewarding a customer with points for every placed order. **Refund** - Captured when points redeemed from a refunded order are returned to the customer. **Redemption** - Recorded whenever a customer redeems their points for rewards. **Expiry** - Captured when a customer's points expire, indicating a reduction in their total points. **Cancel** - Recorded when a customer cancels an order, leading to the deduction of rewarded points. **Migration** - Captured during updates or migrations of customer data via a CSV file, reflecting added or deducted points. **ManualAccumulation** - Recorded for points that are manually added to a customer's balance. **DiscountCode** - Captured when a customer creates a coupon code. **ManualDeduction** - Recorded for points manually removed from a customer's balance. **ManualReward** - Similar to AchievementReward, but specifically for manually awarding achievements to a customer.", "enum": ["AchievementReward", "PaymentReward", "Refund", "Redemption", "Expiry", "Cancel", "Migration", "ManualAccumulation", "DiscountCode", "ManualDeduction", "ManualReward"], "example": "PaymentReward" }, "amount": { "type": "number", "description": "The monetary value involved in the transaction.", "example": 250.75 }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.", "example": "ORD12345" }, "equivalentPoints": { "type": "number", "description": "The points equivalent to the monetary value of the transaction.", "example": 192.0 } } } }, "count": { "type": "integer", "description": "Total number of transactions associated with the order.", "example": 1 } } } } } } } }, "delete": { "description": "Delete a customer by customerId.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "x-codeSamples": [ { "lang": "C#", "label": "C#", "source": "using System.Net.Http;\nusing System.Threading.Tasks;\n\nvar client = new HttpClient();\nclient.BaseAddress = new System.Uri(\"https://api.gameball.co\");\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar request = new HttpRequestMessage(HttpMethod.Delete, \"/api/v4.0/integrations/customers/12345\");\nvar response = await client.SendAsync(request);\nresponse.EnsureSuccessStatusCode();" } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique customer identifier" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/balance": { "get": { "summary": "Get Customer Balance", "description": "Retrieve customer loyalty progress including tier, points balance, and referrals.", "operationId": "getCustomerBalance", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Unique identifier for the customer", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" } ], "responses": { "200": { "description": "Customer progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProgress" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/tier-progress": { "get": { "description": "Retrieve customer loyalty progress including tier, points balance, and referrals.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/12345/progress' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/progress', { headers: { apikey: 'YOUR_API_KEY', secretkey: 'YOUR_SECRET_KEY' } }); const data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import requests\nresp = requests.get('https://api.gameball.co/api/v4.0/integrations/customers/12345/progress', headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY'})\nprint(resp.json())" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar response = await client.GetAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/progress\");\nresponse.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": " ['apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique customer identifier" }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" } ], "responses": { "200": { "description": "Customer progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerProgress" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress": { "get": { "summary": "Get Customer Campaigns Progress", "description": "Retrieve customer's progress within Gameball's reward campaigns, providing insights into achievements and current status in each campaign.", "operationId": "getCustomerCampaignsProgress", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer campaigns progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCampaignsProgressResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals": { "get": { "summary": "Get Customer Referrals", "description": "Retrieve a list of customers referred by a specified customer, including each referral's join date and current status.", "operationId": "getCustomerReferrals", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which Gameball customer id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Number of referrals to return per page" } ], "responses": { "200": { "description": "Customer referrals found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals/count": { "get": { "summary": "Get Customer Referrals Count", "description": "Retrieve the total count of customers referred by a specified customer, providing the number of completed and pending referrals.", "operationId": "getCustomerReferralsCount", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer referrals count found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsCountResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/activities": { "get": { "summary": "Get Customer Activities", "description": "Retrieve a log of customer activities within Gameball, including tier changes, campaign rewards, referrals, redemptions, and more.", "operationId": "getCustomerActivities", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which activity id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Number of activities to return per page" }, { "name": "activityType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["TierUpgraded", "TierDowngraded", "TierMigration", "CampaignRewarded", "SuccessfulAction", "Referral", "Referred", "ReferralBonusReward", "PaymentReward", "Refund", "Redemption", "Cancel", "Expiry", "Migration", "Lifetime", "Automation"] }, "description": "Filter activities by specific type" } ], "responses": { "200": { "description": "Customer activities found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/activities/count": { "get": { "summary": "Get Customer Activities Count", "description": "Retrieve the total count of customer activities within Gameball, with optional filtering by activity type.", "operationId": "getCustomerActivitiesCount", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "activityType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["TierUpgraded", "TierDowngraded", "TierMigration", "CampaignRewarded", "SuccessfulAction", "Referral", "Referred", "ReferralBonusReward", "PaymentReward", "Refund", "Redemption", "Cancel", "Expiry", "Migration", "Lifetime", "Automation"] }, "description": "Filter activities by specific type" } ], "responses": { "200": { "description": "Customer activities count found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesCountResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/automation": { "get": { "summary": "Get Customer Automation Campaigns", "description": "Retrieve available automation campaigns for the customer, including onboarding journeys, engagement triggers, or milestone-based campaigns.", "operationId": "getCustomerAutomationCampaigns", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "campaignType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mission", "all"], "default": "mission" }, "description": "Filter automation steps by specific type" } ], "responses": { "200": { "description": "Customer automation campaigns found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAutomationCampaignsResponse" } } } }, "404": { "description": "Customer not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/action-streak/{challengeId}": { "get": { "summary": "Get Customer Action Streak Progress", "description": "Retrieve the progress of a specific customer within a particular Action Streak challenge.", "operationId": "getCustomerActionStreakProgress", "security": [{ "apiKey": [] }, { "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "challengeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique identifier of the Action Streak challenge" } ], "responses": { "200": { "description": "Customer action streak progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionStreakProgressResponse" } } } }, "404": { "description": "Customer or challenge not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/tags": { "get": { "operationId": "listCustomerTags", "description": "List tags attached to a customer.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/12345/tags' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags', { headers: { apikey: 'YOUR_API_KEY', secretkey: 'YOUR_SECRET_KEY' } }); const data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import requests\nresp = requests.get('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags', headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY'})\nprint(resp.json())" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar res = await client.GetAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/tags\");\nres.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": " ['apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "responses": { "200": { "description": "Tags list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTags" } } } } } }, "post": { "operationId": "attachCustomerTags", "description": "Attach one or more tags to a customer.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachTagsRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/12345/tags' -H 'Content-Type: application/json' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY' -d '{\"tags\":[\"vip\",\"newsletter\"]}'" }, { "lang": "javascript", "label": "JavaScript", "source": "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags',{method:'POST',headers:{'Content-Type':'application/json',apikey:'YOUR_API_KEY',secretkey:'YOUR_SECRET_KEY'},body:JSON.stringify({tags:['vip','newsletter']})});" }, { "lang": "python", "label": "Python", "source": "import requests\nrequests.post('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags', json={'tags':['vip','newsletter']}, headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY','Content-Type':'application/json'})" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http; using System.Text;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar content = new StringContent(\"{\\\"tags\\\":[\\\"vip\\\",\\\"newsletter\\\"]}\", Encoding.UTF8, \"application/json\");\nvar res = await client.PostAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/tags\", content);\nres.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": "['vip','newsletter']]);\\ncurl_setopt_array($ch, [CURLOPT_POST=>true, CURLOPT_HTTPHEADER => ['Content-Type: application/json','apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_POSTFIELDS => $payload, CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "responses": { "200": { "description": "Tags attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/tags/{tag}": { "delete": { "operationId": "removeCustomerTag", "description": "Remove a tag from a customer.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://api.gameball.co/api/v4.0/integrations/customers/12345/tags/vip' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY'" }, { "lang": "javascript", "label": "JavaScript", "source": "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags/vip',{method:'DELETE',headers:{apikey:'YOUR_API_KEY',secretkey:'YOUR_SECRET_KEY'}});" }, { "lang": "python", "label": "Python", "source": "import requests\nrequests.delete('https://api.gameball.co/api/v4.0/integrations/customers/12345/tags/vip', headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY'})" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar res = await client.DeleteAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/tags/vip\");\nres.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": "'DELETE', CURLOPT_HTTPHEADER => ['apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "responses": { "200": { "description": "Tag removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/notifications": { "get": { "operationId": "listCustomerNotifications", "summary": "Get Customer Notifications", "description": "Retrieve a paged list of notifications for a specific customer in Gameball, including details such as title, message content, read status, and timestamp.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which notification id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Number of notifications to return per page" }, { "name": "isRead", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter notifications based on their read status" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Language in which notifications will be retrieved" } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications',{ headers:{ apikey:'YOUR_API_KEY', secretkey:'YOUR_SECRET_KEY'}}); const data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import requests\nresp = requests.get('https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications', headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY'})\nprint(resp.json())" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar res = await client.GetAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications\");\nres.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": " ['apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "responses": { "200": { "description": "Notifications list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNotifications" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/notifications/count": { "get": { "operationId": "getCustomerNotificationsCount", "summary": "Get Customer Notifications Count", "description": "Retrieve the total count of notifications for a specific customer in Gameball, providing the number of notifications matching the specified criteria.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "isRead", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter notifications based on their read status" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Language in which notifications will be retrieved" } ], "responses": { "200": { "description": "Notifications count found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNotificationsCountResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/notifications/read": { "put": { "operationId": "markNotificationsRead", "summary": "Mark Customer Notifications as Read", "description": "Mark specific notifications as read for a customer in Gameball by providing notification IDs.", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkNotificationsReadRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications/read' -H 'Content-Type: application/json' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY' -d '{\"notificationIds\":[\"n_01\",\"n_02\"]}'" }, { "lang": "javascript", "label": "JavaScript", "source": "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications/read',{method:'POST',headers:{'Content-Type':'application/json',apikey:'YOUR_API_KEY',secretkey:'YOUR_SECRET_KEY'},body:JSON.stringify({notificationIds:['n_01','n_02']})});" }, { "lang": "python", "label": "Python", "source": "import requests\nrequests.post('https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications/read', json={'notificationIds':['n_01','n_02']}, headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY','Content-Type':'application/json'})" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http; using System.Text;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar content = new StringContent(\"{\\\"notificationIds\\\":[\\\"n_01\\\",\\\"n_02\\\"]}\", Encoding.UTF8, \"application/json\");\nvar res = await client.PostAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications/read\", content);\nres.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": "['n_01','n_02']]);\\ncurl_setopt_array($ch, [CURLOPT_POST=>true, CURLOPT_HTTPHEADER => ['Content-Type: application/json','apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_POSTFIELDS => $payload, CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } } } } }, "/api/v4.0/integrations/events": { "post": { "summary": "Send Events", "description": "Send events to capture customer actions, enabling targeted rewards and engagement.", "operationId": "sendEvents", "security": [ { "apiKey": [] } ], "requestBody": { "description": "Event payload containing the customerId and one or more events with metadata.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" }, "examples": { "sample": { "summary": "Sample request", "value": { "customerId": "1848877205", "events": { "write_review": { "product_id": "1653503260", "review": "5 Stars Product" } } } } } } } }, "responses": { "200": { "description": "Events accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" }, "examples": { "accepted": { "value": { "success": true, "message": "Events processed" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - missing or invalid API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plants": { "get": { "description": "Returns all plants from the system that the user has access to", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of results to return", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Plant response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plant" } } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "description": "Creates a new plant in the store", "requestBody": { "description": "Plant to add to the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } }, "required": true }, "responses": { "200": { "description": "plant response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plant" } } } }, "400": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/plants/{id}": { "delete": { "description": "Deletes a single plant based on the ID supplied", "parameters": [ { "name": "id", "in": "path", "description": "ID of plant to delete", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "Plant deleted", "content": {} }, "400": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "/plant/webhook": { "post": { "description": "Information about a new plant added to the store", "requestBody": { "description": "Plant added to the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } } } } }, "components": { "schemas": { "UpsertCustomerRequest": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "deviceToken": { "type": "string" }, "osType": { "type": "string" }, "customerAttributes": { "type": "object", "additionalProperties": true }, "Custom": { "type": "object", "additionalProperties": true } } }, "Customer": { "type": "object", "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": true } } }, "CustomerDetails": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "tier": { "type": "string" }, "pointsBalance": { "type": "number" } } }, "Coupon": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "value": { "type": "number" }, "type": { "type": "string" }, "target": { "type": "string" }, "currency": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "expiryDate": { "type": "string", "format": "date-time" }, "isExpired": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "CustomerCoupons": { "type": "object", "properties": { "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } } } }, "CustomerHash": { "type": "object", "properties": { "hash": { "type": "string" } } }, "ReferralValidation": { "type": "object", "properties": { "isValid": { "type": "boolean" } } }, "CustomerProgress": { "type": "object", "properties": { "customerId": { "type": "string" }, "pointsBalance": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "rank": { "type": "integer" } } }, "referrals": { "type": "object", "properties": { "total": { "type": "integer" }, "successful": { "type": "integer" } } } } }, "CustomerTags": { "type": "object", "properties": { "customerId": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "nextCursor": { "type": ["string", "null"] } } }, "AttachTagsRequest": { "type": "object", "required": ["tags"], "properties": { "tags": { "type": "array", "items": { "type": "string" } } } }, "CustomerNotifications": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "isRead": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "nextCursor": { "type": ["string", "null"] } } }, "MarkNotificationsReadRequest": { "type": "object", "required": ["notificationIds"], "properties": { "notificationIds": { "type": "array", "items": { "type": "string" } } } }, "EventRequest": { "type": "object", "required": ["customerId", "events"], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer" }, "events": { "type": "object", "description": "A mapping of event names to metadata objects", "additionalProperties": { "type": "object", "additionalProperties": true } } } }, "Success": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "Plant": { "required": [ "name" ], "type": "object", "properties": { "name": { "description": "The name of the plant", "type": "string" }, "tag": { "description": "Tag to specify the type", "type": "string" } } }, "NewPlant": { "allOf": [ { "$ref": "#/components/schemas/Plant" }, { "required": [ "id" ], "type": "object", "properties": { "id": { "description": "Identification number of the plant", "type": "integer", "format": "int64" } } } ] }, "Error": { "required": [ "error", "message" ], "type": "object", "properties": { "error": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }, "CustomerResponse": { "type": "object", "properties": { "gameballId": { "type": "number", "description": "The customer's unique ID within the Gameball system" }, "customerId": { "type": "string", "description": "Unique identifier for the customer" }, "customerAttributes": { "type": "object", "description": "Customer attributes (minimized, excluding PII)" }, "referralCode": { "type": "string", "description": "The referral code of the customer" }, "referralLink": { "type": "string", "description": "The referral link generated for the customer" }, "isReferred": { "type": "boolean", "description": "Boolean indicating if this customer was referred" }, "dynamicReferralLink": { "type": "string", "description": "Dynamic referral link for mobile apps" } } }, "CustomerDetailsResponse": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer" }, "gameballId": { "type": "number", "description": "The customer's unique ID within the Gameball system" }, "customerAttributes": { "type": "object", "description": "Complete customer attributes including PII" }, "referralCode": { "type": "string", "description": "The referral code of the customer" }, "referralLink": { "type": "string", "description": "The referral link generated for the customer" }, "isReferred": { "type": "boolean", "description": "Boolean indicating if this customer was referred" }, "dynamicReferralLink": { "type": "string", "description": "Dynamic referral link for mobile apps" } } }, "CustomerCouponsResponse": { "type": "object", "properties": { "coupons": { "type": "array", "description": "List of coupon objects associated with the customer", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the coupon" }, "code": { "type": "string", "description": "The coupon code that the customer will use" }, "value": { "type": "number", "description": "The monetary value or percentage value of the coupon" }, "type": { "type": "string", "description": "Type of the coupon", "enum": ["Free Shipping", "Fixed Rate Discount", "Percentage", "Free Product", "Custom", "Percentage-based Fees Discount", "Percentage-based Cashback"] }, "target": { "type": "string", "description": "How the coupon is associated with the customer", "enum": ["Online", "POS", "Permanent", "Reward", "Automation"] }, "currency": { "type": "string", "description": "Currency code if the coupon has a fixed monetary value" }, "startDate": { "type": "string", "format": "date-time", "description": "The date and time when the coupon becomes valid" }, "expiryDate": { "type": "string", "format": "date-time", "description": "The date and time when the coupon will expire" }, "isExpired": { "type": "boolean", "description": "Indicates if the coupon has expired" }, "isActive": { "type": "boolean", "description": "Status of the coupon, whether it is active or not" }, "usageLimit": { "type": "number", "description": "The total number of times the coupon can be used" }, "limitPerCustomer": { "type": "number", "description": "The number of times a single customer can use the coupon" }, "usedCount": { "type": "number", "description": "Number of times the coupon has been used" }, "customerUsedCount": { "type": "number", "description": "Number of times the coupon has been used by this customer" }, "isAvailableToUse": { "type": "boolean", "description": "Flag determining whether coupon can be used by customer at given time" } } } } } }, "CustomerHashResponse": { "type": "object", "properties": { "hash": { "type": "string", "description": "A unique, rotating identifier generated for each customer for secure verification" } } }, "ReferralValidationResponse": { "type": "object", "properties": { "isValid": { "type": "boolean", "description": "Indicates whether the provided referral code is valid and eligible for use" } } }, "UpsertCustomerResponse": { "type": "object", "properties": { "gameballId": { "type": "number", "description": "The customer's unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard." } } }, "CustomerCampaignsProgressResponse": { "type": "array", "items": { "type": "object", "properties": { "rewardsCampaignName": { "type": "string", "description": "The name of the rewards campaign" }, "rewardsCampaignId": { "type": "number", "description": "The unique ID of the rewards campaign" }, "isUnlocked": { "type": "boolean", "description": "Indicates if the customer has unlocked the campaign" }, "completionPercentage": { "type": "number", "description": "The percentage of the campaign the customer has completed" }, "achievedCount": { "type": "number", "description": "The number of times the customer has achieved the campaign" }, "canAchieve": { "type": "boolean", "description": "Whether the customer is currently eligible to participate in the campaign" } } } }, "CustomerReferralsResponse": { "type": "object", "properties": { "referredFriends": { "type": "array", "description": "A list of friends referred by the customer", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Unique identifier for the referred friend" }, "displayName": { "type": "string", "description": "Display name of the referred friend" }, "email": { "type": "string", "description": "Email address of the referred friend" }, "mobileNumber": { "type": "string", "description": "Mobile number of the referred friend" }, "joinDate": { "type": "string", "description": "The date when the referred friend joined" }, "status": { "type": "string", "enum": ["Active", "Pending"], "description": "The current status of the referral" } } } }, "count": { "type": "number", "description": "The total number of friends on the current page" }, "hasMore": { "type": "boolean", "description": "Whether there are additional friends to be fetched" } } }, "CustomerReferralsCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of friends referred by the customer" }, "totalPending": { "type": "number", "description": "The total number of referred friends who have joined but not yet completed the referral criteria" }, "totalActive": { "type": "number", "description": "The total number of referred friends who have successfully completed the referral criteria" } } }, "CustomerActivitiesResponse": { "type": "object", "properties": { "activities": { "type": "array", "description": "An array of activity records for the customer", "items": { "type": "object", "properties": { "activityId": { "type": "number", "description": "Unique identifier for the activity" }, "activityType": { "type": "string", "description": "The type of activity that occurred" }, "activityDay": { "type": "string", "description": "The day of the week when the activity took place" }, "activityDate": { "type": "string", "description": "The date of the activity" }, "activityTime": { "type": "string", "description": "The time when the activity occurred" }, "customerId": { "type": "string", "description": "The unique identifier of the customer" }, "email": { "type": "string", "description": "The email address of the customer" }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system" }, "isManualActivity": { "type": "boolean", "description": "Whether the activity was manually triggered" }, "points": { "type": "number", "description": "The number of points involved in the activity" }, "score": { "type": "number", "description": "The score involved in the activity" } } } }, "count": { "type": "number", "description": "The total number of activities on the current page" }, "hasMore": { "type": "boolean", "description": "Whether there are additional logs to be fetched" } } }, "CustomerActivitiesCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of activities available in Gameball system" } } }, "CustomerAutomationCampaignsResponse": { "type": "object", "properties": { "campaigns": { "type": "array", "description": "A list of campaigns containing automation workflows", "items": { "type": "object", "properties": { "automation": { "type": "array", "description": "A list of automation workflows within a campaign", "items": { "type": "object", "properties": { "order": { "type": "number", "description": "The order in which this automation appears" }, "name": { "type": "string", "description": "The internal name of the automation workflow" }, "isUnlocked": { "type": "boolean", "description": "Whether this automation is unlocked" }, "completed": { "type": "boolean", "description": "Whether the automation has been fully completed" }, "completionPercentage": { "type": "number", "description": "Percentage of completion for the automation" } } } }, "automationCount": { "type": "number", "description": "Total number of automations available within this campaign" } } } }, "count": { "type": "number", "description": "The total number of automation campaigns available" } } }, "CustomerActionStreakProgressResponse": { "type": "object", "properties": { "numberOfCompletedSteps": { "type": "number", "description": "The number of steps completed by the customer in the current challenge cycle" }, "numberOfTimesEarned": { "type": "number", "description": "The total number of times the customer has successfully completed the challenge" }, "canAchieveAgain": { "type": "boolean", "description": "Whether the customer is currently eligible to continue the challenge" }, "remainingTries": { "type": "number", "description": "The number of remaining allowed completions within the current time interval" }, "challengeEndDate": { "type": "string", "description": "The end date of the challenge in the client's local timezone" }, "rewardName": { "type": "string", "description": "The name of the reward as defined in the client's configured language" }, "couponName": { "type": "string", "description": "The name or value of the discount coupon assigned" } } }, "CustomerNotificationsCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of notifications available for the customer in Gameball system" } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "apikey" }, "secretKey": { "type": "apiKey", "in": "header", "name": "secretkey" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }