{ "openapi": "3.1.0", "info": { "title": "Gameball API", "description": "Gameball REST API v4.0 - Complete API reference for integrating loyalty, gamification, and customer engagement features", "version": "4.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" } } } } } } }, "/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" } } } } } }, "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" } } } }, "/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" } } } } } } }, "/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" } } } } } } }, "/api/v4.0/integrations/customers/social-challenges": { "post": { "summary": "Achieve Social Campaign", "description": "Mark a social campaign as achieved for a customer and grant the configured reward from your backend. This is the server-to-server equivalent of the in-widget social action for Social Activities campaigns.", "operationId": "achieveSocialChallenge", "security": [{ "apiKey": [], "secretKey": [] }], "requestBody": { "description": "Social challenge achievement payload.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "challengeId"], "properties": { "customerId": { "type": "string", "maxLength": 100, "description": "The customer's unique ID in your system. The customer must already exist in Gameball.", "example": "customer_123" }, "challengeId": { "type": "integer", "minimum": 1, "description": "The ID of the Social Activities campaign to award.", "example": 11664 }, "email": { "type": "string", "description": "Customer's email address. Helps identify the customer when channel merging is enabled.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. Helps identify the customer when channel merging is enabled.", "example": "+1234567890" } } }, "examples": { "sample": { "summary": "Sample request", "value": { "customerId": "customer_123", "challengeId": 11664 } } } } } }, "responses": { "202": { "description": "Social challenge achievement accepted for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "The customer ID from the request.", "example": "customer_123" }, "challengeId": { "type": "integer", "description": "The social campaign ID from the request.", "example": 11664 }, "gameballStatus": { "type": "string", "description": "Present when the Gameball program is disabled. Omitted while Gameball is enabled." }, "message": { "type": "string", "description": "Informational message when the Gameball program is disabled." }, "learnMore": { "type": "string", "description": "Link to learn more when the Gameball program is disabled." } } }, "examples": { "accepted": { "value": { "customerId": "customer_123", "challengeId": 11664 } } } } } }, "400": { "description": "Invalid request (missing fields, duplicate submission, etc.)" }, "401": { "description": "Missing or invalid secret key" }, "404": { "description": "Customer does not exist" }, "500": { "description": "Unexpected server error" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges' \\\n -H 'Content-Type: application/json' \\\n -H 'apikey: YOUR_API_KEY' \\\n -H 'secretkey: YOUR_SECRET_KEY' \\\n -d '{\"customerId\":\"customer_123\",\"challengeId\":11664}'" }, { "lang": "javascript", "label": "JavaScript", "source": "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/social-challenges', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n apikey: 'YOUR_API_KEY',\n secretkey: 'YOUR_SECRET_KEY'\n },\n body: JSON.stringify({ customerId: 'customer_123', challengeId: 11664 })\n});" }, { "lang": "python", "label": "Python", "source": "import requests\n\nrequests.post(\n 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',\n json={'customerId': 'customer_123', 'challengeId': 11664},\n headers={'apikey': 'YOUR_API_KEY', 'secretkey': 'YOUR_SECRET_KEY', 'Content-Type': 'application/json'}\n)" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nusing System.Text;\n\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar content = new StringContent(\"{\\\"customerId\\\":\\\"customer_123\\\",\\\"challengeId\\\":11664}\", Encoding.UTF8, \"application/json\");\nvar response = await client.PostAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/social-challenges\", content);\nresponse.EnsureSuccessStatusCode();" } ] } }, "/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" } } } } } } }, "/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": "The API call tracks new payments, specifically tailored for fintech solutions. It captures key payment details, ensuring accurate tracking of customer transactions.\n\nThis API triggers the **\"Payment Processed\"** event, allowing you to automate follow-up actions such as initiating workflows, sending notifications, or rewarding customers with badges.\n\nThe event includes all properties provided in the payload.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "paymentId", "paymentDate", "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": "cust456" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "paymentId": { "type": "string", "description": "Unique identifier for the payment on your system.", "example": "6253e03b" }, "paymentDate": { "type": "string", "format": "date-time", "description": "Timestamp of when the payment was occurred.", "example": "2024-09-21T16:53:28.190Z" }, "totalPaid": { "type": "number", "description": "The actual amount paid by the customer for the payment, accounting for any discounts or coupons applied. Unlike totalAmount, which reflects the original cost of the payment, totalPaid represents the final amount the customer paid after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the payment. Example: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid.", "example": 100 }, "totalAmount": { "type": "number", "description": "The total cost of the payment, including all item prices, processing fees and taxes. 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 payment. Must be a positive value. Example: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalAmount remains $120 as it represents the original cost of the payment before any discounts are applied.", "example": 120 }, "totalDiscount": { "type": "number", "description": "Total discount applied to the payment.", "example": 20 }, "totalProcessingFees": { "type": "number", "description": "Total processing fees associated with the payment.", "example": 10 }, "totalTax": { "type": "number", "description": "Total tax amount for the payment.", "example": 10 }, "paymentDetails": { "type": "array", "description": "An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Unique identifier for the service.", "example": "s_1234" }, "serviceName": { "type": "string", "description": "Service title or name.", "example": "Vodafone Topup" }, "serviceProvider": { "type": "string", "description": "Company or entity that provides the service being paid for. This could be a telecom operator, an electricity provider, a streaming platform, or any other service vendor.", "example": "Vodafone" }, "amount": { "type": "number", "description": "The original amount of a single service before any tax or discount is applied. This reflects the cost of the service, not the total for multiple quantities in a payment.", "example": 100 }, "tax": { "type": "number", "description": "The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.", "example": 10 }, "discount": { "type": "number", "description": "The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.", "example": 20 }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the service for categorization or promotional purposes.", "example": ["Telecom", "Topup"] }, "category": { "type": "array", "items": { "type": "string" }, "description": "Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: [\"Telecom Top-up\", \"Internet Bill\", \"Streaming Subscription\"]", "example": ["Telecom Topup"] }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the service, such as size, color, or other custom attributes. The values must be of type string or number.", "example": {} } } } }, "redemption": { "type": "object", "description": "Redemption details for the payment, 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: If you lock a coupon for a specific transaction, the lockReference could look like \"lockReference\": \"abc123def456\".", "example": "LOCK123" }, "couponCodes": { "type": "array", "items": { "type": "string" }, "description": "A list of coupon codes that were applied to the payment. 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: If a customer applied two coupon codes, one for a 10% discount and another for free fees, the couponCodes array might look like this: [\"DISCOUNT10\", \"FREEFEES2024\"]", "example": ["DISCOUNT10"] } } }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the payment. The values must be of type string or number. Example: The extra attribute can store additional details like the billing address and payment status. For instance, when a customer completes a payment, the billing address ensures accurate invoicing by including details like the company name and tax identification number. At the same time, the payment status helps track the transaction—whether it's \"Pending\" for deferred payments or \"Completed\" when successfully processed—ensuring smooth order management and financial compliance.", "example": { "billingAddress": "Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321", "paymentStatus": "Pending" } }, "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." }, "name": { "type": "string", "description": "Name of the merchant." }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the payment took place." }, "name": { "type": "string", "description": "Name of the branch where the payment took place." } } } } }, "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.", "example": false }, "channel": { "type": "string", "enum": ["mobile", "pos", "web", "callcenter"], "description": "The channel through which the payment was placed helps track the origin of the payment, 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 payments across platforms. Possible values: mobile (The payment was placed through your mobile application), pos (The payment was placed in person using a Point of Sale system), web (The payment was placed through your website), callcenter (The payment was placed over the phone by contacting a customer service representative).", "example": "web" }, "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).", "example": 7 } } } } } } } }, "responses": { "200": { "description": "Payment tracked", "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 payment, if applicable. Example: If a customer has accumulated 500 points and decides to redeem 100 points for a discount on their current payment, 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 payment 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 payment. 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 completes a payment worth $50, the rewardedPoints for this order would be 500 points.", "example": 101 }, "paymentDetails": { "type": "array", "description": "Details about each service in the payment, including points rewarded.", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Unique identifier for the service.", "example": "service_123" }, "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 } } } } } } } } } } } }, "/api/v4.0/integrations/payments/cashback": { "post": { "summary": "Calculate Payment Cashback", "description": "This API calculates the cashback points to be rewarded for a specific payment in Gameball, based on provided payment 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": "calculatePaymentCashback", "tags": ["Payments"], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "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. 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": "cust456" }, "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 payment, accounting for any discounts or coupons applied. Unlike `totalAmount`, which reflects the original cost of the payment, `totalPaid` represents the final amount the customer paid after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the payment. **Example:** A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the `totalPaid` becomes $100, reflecting the discounted amount the customer paid.", "example": 100 }, "totalAmount": { "type": "number", "description": "The total cost of the payment, including all item prices, processing fees, and taxes. 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 payment. Must be a positive value.", "example": 120 }, "totalDiscount": { "type": "number", "description": "Total discount applied to the payment. Must be positive.", "minimum": 0, "example": 20 }, "totalProcessingFees": { "type": "number", "description": "Total processing fees associated with the payment.", "example": 10 }, "totalTax": { "type": "number", "description": "Total tax amount for the payment.", "example": 10 }, "paymentDetails": { "type": "array", "description": "An array containing details about each service in the payment. If not provided, the calculation will only consider the total payment values.", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Unique identifier for the service.", "example": "s_1234" }, "serviceName": { "type": "string", "description": "Service title or name.", "example": "Vodafone Topup" }, "serviceProvider": { "type": "string", "description": "Company or entity that provides the service being paid for.", "example": "Vodafone" }, "amount": { "type": "number", "description": "The original amount of a single service before any tax or discount is applied.", "example": 100 }, "tax": { "type": "number", "description": "The total amount of taxes applied to the service. Must be positive.", "example": 10 }, "discount": { "type": "number", "description": "The total discount applied to this service, expressed as a positive value.", "example": 20 }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the service for categorization or promotional purposes.", "example": ["Telecom", "Topup"] }, "category": { "type": "array", "items": { "type": "string" }, "description": "Service category. It can include one or multiple categories.", "example": ["Telecom Topup"] }, "extra": { "type": "object", "additionalProperties": true, "description": "Key-value pairs containing any extra information about the service. The values must be of type string or number.", "example": {} } } } }, "merchant": { "type": "object", "description": "Details about the specific merchant involved in the payment, particularly useful for businesses managing multiple merchants or branches under the same Gameball account.", "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 payment took place.", "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch.", "example": "BRANCH001" }, "name": { "type": "string", "description": "Name of the branch.", "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 payment.", "example": 19000 }, "totalScore": { "type": "number", "description": "Total score expected to be earned from the entire payment.", "example": 0 }, "paymentDetails": { "type": "array", "description": "An array of individual payment services and their cashback calculation details.", "items": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "Unique identifier for the service.", "example": "s_1234" }, "quantity": { "type": "number", "description": "The quantity of the service.", "example": 1 }, "totalDecimalPoints": { "type": "number", "description": "The total decimal points earned for this service, including any campaign impact.", "example": 15000.0 }, "totalPoints": { "type": "number", "description": "The total points earned for this service, including any campaign impact. **Example:** If the base points for a service 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 service. This value is separate from points and is based on your cashback rewards configuration.", "example": 0 }, "rewardWalletFactor": { "type": "number", "description": "The multiplier applied to the service amount to calculate the base points earned. This factor represents how many points are earned per unit of currency spent. **Example:** If the account 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 this service. 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 this service. If no campaign is applicable, this field will be null.", "example": "5x Points Campaign" }, "campaignEndDate": { "type": ["string", "null"], "format": "date-time", "description": "The end date of the active campaign affecting this service. 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. **Example:** If the campaign offers 3x points, the campaignImpactWalletFactor would be 3.", "example": 5.0 }, "campaignImpactPoints": { "type": "number", "description": "The total number of additional points given for this service due to the campaign's impact. **Example:** If the base points for a service are 100 and the campaign offers 5x points, the campaignImpactPoints would be 400.", "example": 12000.0 } } } } } } } } }, "400": { "description": "Invalid request payload" }, "401": { "description": "Authentication failed" }, "500": { "description": "Internal server error" } } } }, "/api/v4.0/integrations/transactions/redeem": { "post": { "description": "This API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points in place of monetary value during transactions. By providing details such as customerId and amount, this endpoint facilitates point-based redemptions within the purchase process.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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. Could be a database ID, random string, email, or anything that uniquely identifies the customer.", "example": "cust_12345abc" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "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": "txn98765" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).", "example": "2024-10-11T10:57:43.382Z" }, "amount": { "type": "number", "description": "The actual monetary value the customer wants to redeem. This will be deducted from their points balance based on the redemption factor. For instance, if the customer wants to redeem $10 and the redemption factor is 0.1, then 100 points will be deducted from their balance to cover this amount. Note: Only one of amount, points, or holdReference must be provided for the redemption.", "example": 10 }, "points": { "type": "integer", "description": "The number of points the customer wants to redeem from their balance. This allows the customer to specify exactly how many points they wish to use. Note: Only one of amount, points, or holdReference must be provided for the redemption.", "example": 0 }, "holdReference": { "type": "string", "description": "A unique reference obtained from the Hold Points API. If provided, the points in the hold will be used. It is used when points have been reserved previously, allowing the system to redeem the points that are on hold. Example: If you previously used the Hold Points API to hold 100 points, you would provide the holdReference obtained from that hold transaction to redeem the 100 points that were held. Note: Only one of amount, points, or holdReference must be provided for the redemption.", "example": null }, "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." }, "name": { "type": "string", "description": "Name of the merchant." }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the transaction took place." }, "name": { "type": "string", "description": "Name of the branch where the transaction took place." } } } } }, "hash": { "type": "string", "description": "A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. For more details on how the hash is generated and validated, refer to the Customer's Hash section.", "example": "HASH1234" }, "otp": { "type": "string", "description": "One-time password (OTP) required if OTP is enabled for the customer. This OTP serves as an additional layer of security for verifying the redemption request. For more details on how OTP works and when it is required, refer to the Transaction Validation section.", "example": "123456" }, "ignoreOTP": { "type": "boolean", "description": "This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.", "example": false }, "reason": { "type": "string", "maxLength": 255, "description": "An optional reason for the redemption. This can be used to provide context about why the customer is redeeming points (e.g., 'Discount on order', 'Loyalty reward'). The reason will be stored with the transaction and displayed in the dashboard transaction details.", "example": "Discount on order #12345" } } } } } }, "responses": { "200": { "description": "Points redeemed 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_12345abc" }, "gameballTransactionId": { "type": "string", "description": "Unique identifier for the transaction in the Gameball system.", "example": "11034734" }, "transactionId": { "type": "string", "description": "A unique identifier for the 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": "txn98765" }, "redeemAmount": { "type": "number", "description": "The amount of money redeemed in the transaction, based on the points redeemed. Example: If a customer redeems points equivalent to $10 off their purchase, the redeemAmount will be 10.0.", "example": 10 }, "redeemEquivalentPoints": { "type": "number", "description": "The number of points used to redeem the specified monetary value in the transaction. Example: If a customer uses 100 points to redeem $10, the redeemEquivalentPoints will be 100.", "example": 100 }, "reason": { "type": "string", "description": "The reason provided for the redemption, if one was included in the request.", "example": "Discount on order #12345" } } } } } } } } }, "/api/v4.0/integrations/transactions/cashback": { "post": { "description": "This API awards loyalty points to customers in Gameball through a cashback program based on the amount.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "amount", "transactionId", "transactionTime"], "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_12345abc" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID is critical for managing transaction lifecycle events such as reversals, cancellations, or refunds in Gameball.", "example": "TXN987654321" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).", "example": "2024-10-11T10:48:56.719Z" }, "amount": { "type": "number", "description": "Monetary value of the transaction for which the customer will be rewarded, based on the Cashback program configuration.", "example": 150.75 }, "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." }, "name": { "type": "string", "description": "Name of the merchant." }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the transaction took place." }, "name": { "type": "string", "description": "Name of the branch where the transaction took place." } } } } }, "configurations": { "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).", "example": 7 } } } } } } } }, "responses": { "200": { "description": "Cashback issued 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_12345abc" }, "gameballTransactionId": { "type": "number", "description": "Unique identifier for the transaction in the Gameball system.", "example": 11034733 }, "rewardAmount": { "type": "number", "description": "The monetary value equivalent of the points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase and each point is worth $0.10, the rewardAmount will be $5.", "example": 150.75 }, "rewardEquivalentPoints": { "type": "number", "description": "The number of points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase, the rewardEquivalentPoints will be 50.", "example": 0 } } } } } } } } }, "/api/v4.0/integrations/transactions/refund": { "post": { "description": "This API processes refunds or cancellations of cashback and points redemption transactions in Gameball. By providing a reverseTransactionId, Gameball identifies the related cashback or redemption transaction and adjusts the customer's points balance accordingly to reflect the refunded or canceled transaction.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "refundTransactionId", "reverseTransactionId", "transactionTime"], "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_12345abc" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "refundTransactionId": { "type": "string", "description": "A unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If a refund is processed for an item, the refundTransactionId could be REFUND-98765, which refers to the specific new refund transaction.", "example": "txn987657111" }, "reverseTransactionId": { "type": "string", "description": "The unique transaction ID representing the original order being refunded, reversed, or canceled. This ID is sent as reverseTransactionId in the payload and links to the previous transaction. Example: If a customer requests a refund for an order previously made with transaction ID ORDER-12345, the reverseTransactionId will be ORDER-12345 to indicate which order is being refunded.", "example": "txn6342347194477" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The timestamp of the original transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).", "example": "2024-10-13T17:11:00.249Z" }, "refundAmount": { "type": "number", "description": "The amount to be refunded from the original transaction. The entire transaction is refunded if this field is not provided. Note: For a full refund, you can use any of the following approaches: Send the refund request without the refundAmount field, Send the refund request with refundAmount set to null, Send the refund request with refundAmount equal to the total paid in the original order.", "example": 15.00 }, "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." }, "name": { "type": "string", "description": "Name of the merchant." }, "branch": { "type": "object", "required": ["uniqueId"], "properties": { "uniqueId": { "type": "string", "description": "Unique identifier for the branch where the transaction took place." }, "name": { "type": "string", "description": "Name of the branch where the transaction took place." } } } } }, "lineItems": { "type": "array", "description": "An array of items from the original transaction that are being refunded. If provided, only the items listed in this array will be refunded from the reverseTransactionId. If this field is not provided, the entire transaction specified by the reverseTransactionId will be refunded.", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Unique identifier for the product or service being purchased." }, "quantity": { "type": "number", "description": "Number of units purchased for this product or service." }, "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." }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) for the product." }, "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\"]" }, "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." }, "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." }, "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." } } } } } } } } }, "responses": { "200": { "description": "Refund processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "gameballTransactionId": { "type": "string", "description": "Unique identifier for the refund transaction in the Gameball system.", "example": "11034735" }, "refundTransactionId": { "type": "string", "description": "Unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If the refund process for an order has a transaction ID REFUND-54321, this ID will be used to track the refund operation.", "example": "txn987657111" }, "refundAmount": { "type": "number", "description": "The amount refunded from the original transaction. Example: If a customer was originally charged $100 and you refunded $40, the refundAmount will be 40.", "example": 15.00 }, "refundEquivalentPoints": { "type": "number", "description": "The number of points equivalent to the monetary value refunded in the transaction. Example: If $40 is refunded and your points-to-currency ratio is 1 point = $0.10, then the refundEquivalentPoints would be 400 points.", "example": 150 } } } } } } } } }, "/api/v4.0/integrations/transactions/hold": { "post": { "description": "This API holds loyalty points for a specified duration, reserving them until a redemption request is made through Order or Redeem. If no redemption occurs within the hold period, the points are released. The default hold time is 10 minutes, adjustable in the Gameball dashboard, with a maximum of 15 days and a minimum of 1 minute.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "transactionTime"], "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_abc12345xyz67890" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).", "example": "2024-10-11T16:15:15.071Z" }, "otp": { "type": "string", "description": "A one-time password (OTP) sent to the customer for authentication purposes. This is used only if your account has OTP configuration enabled. For more details on how the OTP is generated and validated, refer to the OTP Generation and Validation section.", "example": "654321" }, "ignoreOTP": { "type": "boolean", "description": "This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.", "example": false }, "amountToHold": { "type": "number", "description": "The monetary value (in the system's currency) that will be held from the customer's points balance. This allows you to reserve a specific monetary amount using the customer's points. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.", "example": null }, "pointsToHold": { "type": "integer", "description": "The number of points to be held from the customer's points balance. This allows you to reserve a certain number of points for later use. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.", "example": 50 }, "ruleId": { "type": "string", "description": "The ID of a redemption rule configured within Gameball's system. Clients can create custom redemption rules through the Gameball dashboard to specify different redemption options. For example, a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts. You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.", "example": null }, "hash": { "type": "string", "description": "A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. This number changes with each transaction to ensure secure validation. For more details on how the hash is generated and validated, refer to the Customer's Hash section.", "example": "123456" } } } } } }, "responses": { "200": { "description": "Points placed on hold 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_abc12345xyz67890" }, "holdAmount": { "type": "number", "description": "The monetary value that has been held from the customer's points balance. This value represents the amount reserved based on the customer's available points.", "example": "5" }, "holdEquivalentPoints": { "type": "number", "description": "The number of points that have been held from the customer's points balance. These points are reserved for future use or specific transactions.", "example": 50 }, "holdReference": { "type": "string", "description": "A unique identifier for the hold transaction. This reference is used to track and manage the held points for future actions, such as redeeming the held points or canceling the hold. This hold reference can also be used in Order API to redeem the held points.", "example": "a2a199ad-86f3-45c4-8253-7aaee50e4798" } } } } } } } } }, "/api/v4.0/integrations/transactions/hold/{holdReferenceId}": { "get": { "description": "This API retrieves the details of a specific hold in Gameball using holdReferenceId. It returns information on the amount of loyalty points held, their monetary value, the hold's status (active, used, or expired), and the time remaining until expiration, supporting effective management and tracking of held points.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "holdReferenceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the hold transaction, used to retrieve the details of the specific hold." } ], "responses": { "200": { "description": "Hold details retrieved 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_abc12345xyz67890" }, "holdAmount": { "type": "number", "description": "The monetary value held from the customer's points balance in this specific hold transaction. This is the amount that has been reserved and is associated with the holdReference provided. Example: If a customer has reserved $50 worth of points, the holdAmount in the response would be 50, representing the monetary value currently held under the specified hold reference.", "example": "2" }, "holdEquivalentPoints": { "type": "number", "description": "The number of points held from the customer's points balance for this specific hold transaction. This represents the exact quantity of points currently locked under the holdReference provided. Example: If the system has held 200 points from the customer's balance, the holdEquivalentPoints in the response would be 200, indicating the points associated with the provided hold reference that are currently unavailable for redemption until further action is taken (e.g., redemption or expiration).", "example": 20 }, "state": { "type": "string", "description": "The current status of the hold: Active (The hold is currently in effect and the points or amount are locked), Expired (The hold has expired and the points or amount have been released), Used (The hold has been used, meaning the points or amount have been redeemed).", "example": "active" }, "dateToExpire": { "type": "string", "format": "date-time", "description": "The date and time when the hold will expire. After this time, the hold reference will no longer be valid for usage.", "example": "2024-10-16T08:11:24.675401" } } } } } } } }, "delete": { "description": "This API cancels a specific hold on loyalty points in Gameball using the provided holdReferenceId. It releases the held points back into the customer's account, enabling flexibility in point management.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "holdReferenceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the hold transaction, used to release the held points or amount." } ], "responses": { "200": { "description": "Hold released successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the hold was successfully released.", "example": true }, "message": { "type": "string", "description": "Confirmation message indicating the hold has been released.", "example": "Hold released successfully" } } } } } } } } }, "/api/v4.0/integrations/transactions": { "get": { "description": "This API retrieves a paged list of transactions from Gameball, allowing for optional filtering. Each transaction record includes details such as type, direction, points, amount, transaction time, and balance changes, providing a comprehensive view of customer activity.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "direction", "in": "query", "schema": { "type": "string" }, "description": "Direction of the transaction: + (Accumulation - points or rewards added to the customer), - (Deduction - points or rewards removed from the customer)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Represents the current status of the transaction. Possible values are: Active (The transaction is fully completed, and any points or rewards have been successfully added or redeemed), Pending (Points or rewards from the transaction are pending during the return window period), Blocked (The transaction has been flagged and blocked due to suspected fraud or other security concerns), Expired (The points or rewards earned in this transaction have expired and are no longer available for redemption or use)." }, { "name": "startAfter", "in": "query", "schema": { "type": "integer" }, "description": "Specifies the page will start after which transaction id. Defaults to 0." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page." }, { "name": "customerId", "in": "query", "schema": { "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. This is used to filter the transactions of the specified customer." } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "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": "txn123456" }, "gameballTransactionId": { "type": "string", "description": "Unique identifier for the transaction in the Gameball system.", "example": "11034736" }, "type": { "type": "string", "description": "Type of the transaction. Possible values: AchievementReward, PaymentReward, Refund, Redemption, Expiry, Cancel, Migration, ManualAccumulation, DiscountCode, ManualDeduction, ManualReward.", "example": "Cancel" }, "direction": { "type": "string", "description": "Direction of the transaction: + (Accumulation), - (Deduction).", "example": "-" }, "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_12345abc" }, "points": { "type": "number", "description": "Number of points involved in the transaction.", "example": 10 }, "amount": { "type": "number", "description": "Monetary value associated with the transaction.", "example": 10.0 }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime), in UTC.", "example": "2024-10-13T17:11:00.249" }, "status": { "type": "string", "description": "Status of the transaction: Active (The transaction is completed, and any rewards or points have been applied successfully), Pending (The points or rewards from the transaction are temporarily on hold during the return window or any other pending period), Blocked (The transaction was flagged for potential fraud or another issue and is currently blocked from processing), Expired (Points or rewards from the transaction have expired and are no longer available for use).", "example": "Active" }, "couponCode": { "type": "string", "description": "The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer.", "example": null }, "isCouponUsed": { "type": "boolean", "description": "Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again.", "example": false }, "couponType": { "type": "string", "description": "The type of the coupon code that the customer has redeemed during the redemption transaction. Possible values: free_shipping, percentage_discount, fixed_discount, free_product, fixed_rate_discount, custom.", "example": null }, "merchantName": { "type": "string", "description": "Name of the merchant involved in the transaction, if any.", "example": "MERCH1234" }, "branchName": { "type": "string", "description": "Name of the branch involved in the transaction, if any.", "example": "BRANCH123" }, "reason": { "type": "string", "description": "Reason for the transaction, if applicable.", "example": "trx reason" }, "achievementName": { "type": "string", "description": "The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable.", "example": null }, "expiryDate": { "type": "string", "format": "date-time", "description": "Date when the points or rewards from the transaction will expire, if applicable.", "example": "2025-10-13T17:11:00.249" }, "pointsBalanceBefore": { "type": "number", "description": "The customer's points balance before the transaction occurred.", "example": 1164 }, "pointsBalanceAfter": { "type": "number", "description": "The customer's points balance after the transaction is completed.", "example": 1154 }, "achievementType": { "type": "string", "description": "Type of achievement earned during the transaction, if applicable.", "example": null }, "achievedRewardCampaignId": { "type": "string", "description": "The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign.", "example": null }, "achievedTierId": { "type": "number", "description": "The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier.", "example": null } } } }, "count": { "type": "number", "description": "The total number of transactions on the current page.", "example": 2 }, "hasMore": { "type": "boolean", "description": "Indicating whether there are additional transactions to be fetched beyond the current page.", "example": true } } } } } } } } }, "/api/v4.0/integrations/transactions/manual": { "post": { "description": "This API allows for the manual addition or deduction of points for a customer in Gameball. It provides flexibility in managing loyalty points, enabling adjustments based on specific needs or circumstances.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "transactionId", "username", "reason"], "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_abc12345xyz67890" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "john.doe@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "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": "txn543211" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). Defaults to the current time in UTC when omitted.", "example": "2024-10-11T15:54:10.944Z" }, "username": { "type": "string", "description": "The username of the admin performing the manual transaction.", "example": "admin_user" }, "reason": { "type": "string", "description": "Reason for manually rewarding or deducting points (e.g., 'Referral bonus').", "example": "Referral bonus" }, "points": { "type": "integer", "description": "The number of points to be rewarded or deducted. Provide either points or amount. Positive values add points, and negative values deduct points.", "example": 50 }, "amount": { "type": "number", "description": "The monetary value, in system currency, associated with the transaction. Provide either points or amount. Positive values add points, and negative values deduct points.", "example": 0 }, "expiryAfter": { "type": "integer", "minimum": 0, "nullable": true, "description": "The number of days after which the points added in this transaction will expire, counted from the time of the addition. For example, 30 means the awarded points expire 30 days from now. When omitted, null, or 0, the points follow the client's default points-expiry setting configured in the dashboard. This replicates the custom-expiry option available when manually adding points from the Gameball dashboard. expiryAfter applies only to point additions; it cannot be used when deducting points.", "example": 30 } } } } } }, "responses": { "200": { "description": "Manual transaction added 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_abc12345xyz67890" }, "gameballTransactionId": { "type": "number", "description": "The unique identifier for the transaction within Gameball.", "example": 11035201 }, "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": "txn54321221" }, "points": { "type": "number", "description": "The number of points rewarded or deducted in the transaction.", "example": 50 }, "amount": { "type": "number", "description": "The monetary value processed in the transaction.", "example": 5.0 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "negativeExpiry": { "summary": "Negative expiryAfter", "value": { "error": 400, "message": "Expiry cannot be negative" } }, "deductionWithExpiry": { "summary": "expiryAfter on a deduction", "value": { "error": 400, "message": "Deduction cannot have expiry" } }, "multipleRewardingMethods": { "summary": "Both points and amount provided", "value": { "error": 400, "message": "Only one rewarding method may be specified" } }, "missingRewardingCriteria": { "summary": "Neither points nor amount provided", "value": { "error": 400, "message": "A rewarding criteria is required" } } } } } } } } }, "/api/v4.0/integrations/transactions/customer-view": { "get": { "description": "This API retrieves a paged list of transactions from Gameball, with support for optional filtering. It provides the same comprehensive transaction data as the previous version — including type, direction, points, amount, transaction time, and balance changes — but with an important enhancement: Each transaction now includes associated customer details, such as: Customer Name, Customer Email, Customer Deletion Status. This allows for better traceability and visibility into who performed each transaction, even if the customer has since been deleted.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "direction", "in": "query", "schema": { "type": "string" }, "description": "Direction of the transaction: + (Accumulation - points or rewards added to the customer), - (Deduction - points or rewards removed from the customer)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Represents the current status of the transaction. Possible values are: Active (The transaction is fully completed, and any points or rewards have been successfully added or redeemed), Pending (Points or rewards from the transaction are pending during the return window period), Blocked (The transaction has been flagged and blocked due to suspected fraud or other security concerns), Expired (The points or rewards earned in this transaction have expired and are no longer available for redemption or use)." }, { "name": "startAfter", "in": "query", "schema": { "type": "integer" }, "description": "Specifies the page will start after which transaction id. Defaults to 0." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page." }, { "name": "customerId", "in": "query", "schema": { "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. This is used to filter the transactions of the specified customer." } ], "responses": { "200": { "description": "Transactions with customer data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "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": "txn123456" }, "gameballTransactionId": { "type": "string", "description": "Unique identifier for the transaction in the Gameball system.", "example": "11034736" }, "type": { "type": "string", "description": "Type of the transaction. Possible values: AchievementReward, PaymentReward, Refund, Redemption, Expiry, Cancel, Migration, ManualAccumulation, DiscountCode, ManualDeduction, ManualReward.", "example": "Cancel" }, "direction": { "type": "string", "description": "Direction of the transaction: + (Accumulation), - (Deduction).", "example": "-" }, "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_12345abc" }, "customerName": { "type": "string", "description": "The display name of the customer associated with this transaction.", "example": "John Doe" }, "customerEmail": { "type": "string", "description": "The email address of the customer associated with this transaction.", "example": "john.doe@example.com" }, "isCustomerDeleted": { "type": "boolean", "description": "Indicates whether the customer has been marked as deleted in our system and is an existing customer or not.", "example": false }, "points": { "type": "number", "description": "Number of points involved in the transaction.", "example": 10 }, "amount": { "type": "number", "description": "Monetary value associated with the transaction.", "example": 10.0 }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime), in UTC.", "example": "2024-10-13T17:11:00.249" }, "status": { "type": "string", "description": "Status of the transaction: Active (The transaction is completed, and any rewards or points have been applied successfully), Pending (The points or rewards from the transaction are temporarily on hold during the return window or any other pending period), Blocked (The transaction was flagged for potential fraud or another issue and is currently blocked from processing), Expired (Points or rewards from the transaction have expired and are no longer available for use).", "example": "Active" }, "couponCode": { "type": "string", "description": "The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer.", "example": null }, "isCouponUsed": { "type": "boolean", "description": "Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again.", "example": false }, "couponType": { "type": "string", "description": "The type of the coupon code that the customer has redeemed during the redemption transaction. Possible values: free_shipping, percentage_discount, fixed_discount, free_product, fixed_rate_discount, custom.", "example": null }, "merchantName": { "type": "string", "description": "Name of the merchant involved in the transaction, if any.", "example": "MERCH1234" }, "branchName": { "type": "string", "description": "Name of the branch involved in the transaction, if any.", "example": "BRANCH123" }, "reason": { "type": "string", "description": "Reason for the transaction, if applicable.", "example": "trx reason" }, "achievementName": { "type": "string", "description": "The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable.", "example": null }, "expiryDate": { "type": "string", "format": "date-time", "description": "Date when the points or rewards from the transaction will expire, if applicable.", "example": "2025-10-13T17:11:00.249" }, "pointsBalanceBefore": { "type": "number", "description": "The customer's points balance before the transaction occurred.", "example": 1164 }, "pointsBalanceAfter": { "type": "number", "description": "The customer's points balance after the transaction is completed.", "example": 1154 }, "achievementType": { "type": "string", "description": "Type of achievement earned during the transaction, if applicable.", "example": null }, "achievedRewardCampaignId": { "type": "string", "description": "The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign.", "example": null }, "achievedTierId": { "type": "number", "description": "The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier.", "example": null } } } }, "count": { "type": "number", "description": "The total number of transactions on the current page.", "example": 2 }, "hasMore": { "type": "boolean", "description": "Indicating whether there are additional transactions to be fetched beyond the current page.", "example": true } } } } } } } } }, "/api/v4.0/integrations/transactions/count": { "get": { "description": "This API retrieves the total count of transactions from Gameball, allowing for optional filtering. It provides the number of transactions matching the specified criteria without returning detailed transaction records.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "direction", "in": "query", "schema": { "type": "string" }, "description": "Direction of the transaction: + (Accumulation - points or rewards added to the customer), - (Deduction - points or rewards removed from the customer)." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Represents the current status of the transaction. Possible values are: Active (The transaction is fully completed, and any points or rewards have been successfully added or redeemed), Pending (Points or rewards from the transaction are pending during the return window period), Blocked (The transaction has been flagged and blocked due to suspected fraud or other security concerns), Expired (The points or rewards earned in this transaction have expired and are no longer available for redemption or use)." }, { "name": "customerId", "in": "query", "schema": { "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. This is used to filter the transactions of the specified customer." } ], "responses": { "200": { "description": "Transaction count retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of transactions available in Gameball system.", "example": 240 } } } } } } } } }, "/api/v4.0/integrations/transactions/{transactionId}/activate": { "put": { "description": "This API is used to immediately activate loyalty points that are currently in a pending state, bypassing the configured return window duration. This endpoint overrides that duration and activates the points immediately, making them available for use by the customer without waiting for the pending return window duration to elapse. This API is especially useful for scenarios where the client determines that the order is confirmed and the points can be safely activated ahead of schedule. Note: Once points are activated, the action cannot be reversed via this API.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The transaction id on your system which you want to activate." } ], "responses": { "200": { "description": "Transaction activated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "pointsActivated": { "type": "number", "description": "Number of points that has been successfully activated by the transaction", "example": 50 }, "gameballTransactionId": { "type": "number", "description": "The unique identifier for the transaction within Gameball.", "example": 11035201 }, "clientTransactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number).", "example": "txn54321221" } } } } } } } } }, "/api/v4.0/integrations/transactions/otp": { "post": { "description": "The API call generates a new one-time password (OTP) for redeeming or holding loyalty points and sends it via SMS. This service ensuring that only authorized transactions can be completed with the provided OTP. This API is effective only if SMS & OTP are enabled in your Gameball account.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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.", "example": "cust_abc12345xyz67890" }, "email": { "type": "string", "description": "Customer's email address. This is required if your account uses email-based channel merging.", "example": "alex.jones@example.com" }, "mobile": { "type": "string", "description": "Customer's mobile number. This is required if your account uses mobile-based channel merging.", "example": "+1234567890" }, "amount": { "type": "number", "description": "The monetary value associated with the redemption or hold operation for which the OTP is being generated. This allows you to secure specific financial transactions by tying the OTP to an exact amount. Note: Only one of ruleId, points, or amount must be provided for the OTP request to proceed.", "example": 100.00 }, "points": { "type": "integer", "description": "The number of loyalty points for which the OTP is being generated. This allows the customer to redeem or hold a specific quantity of points, adding an extra layer of security to the transaction. Note: Only one of ruleId, points, or amount must be provided for the OTP request to proceed.", "example": null }, "ruleId": { "type": "integer", "description": "The ID of a redemption rule configured within Gameball's system that the customer wants to use. Clients can create custom redemption rules through the Gameball dashboard to specify different redemption options. For example, a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts. You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API. Note: Only one of ruleId, points, or amount must be provided for the OTP request to proceed.", "example": null } } } } } } } }, "/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" } } } } } } } } }, "/api/v4.0/integrations/coupons/{code}/validate": { "post": { "description": "This API validates a single coupon identified by {code} and checks its eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves the coupon by creating a lock reference. This ensures the coupon cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupon.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The coupon code you want to validate." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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." }, "lock": { "type": "boolean", "description": "Indicates whether the request is intended to validate the coupon or to lock it for a future redemption." }, "lockReference": { "type": "string", "description": "Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session." }, "lockDuration": { "type": "integer", "description": "Represents the number of minutes for which a coupon will be locked if the lock flag is set to True." }, "merchantId": { "type": "string", "description": "This parameter is required only if the coupon is designed to apply to specific merchants." }, "collectionId": { "type": "string", "description": "This parameter is required only if the coupon is configured to apply to specific collections." }, "collectionsIds": { "type": "array", "items": { "type": "string" }, "description": "This parameter is required only when the coupon is configured to apply to specific collections." }, "totalPurchaseAmount": { "type": "number", "description": "This parameter represents the total value of the purchase where the coupon will be applied." } } } } } }, "responses": { "200": { "description": "Coupon validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Indicates whether the coupon is valid to be used by the customer or not." }, "coupon": { "$ref": "#/components/schemas/Coupon" }, "lockReference": { "type": "string", "description": "The unique reference code associated with the coupon lock session." }, "dateToExpire": { "type": "string", "format": "date-time", "description": "The exact date and time when the coupon lock will expire." } } } } } } } } }, "/api/v4.0/integrations/coupons/validate": { "post": { "description": "This API validates a list of coupons and checks their eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves eligible coupons by creating hold references. This ensures that locked coupons cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupons.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "coupons"], "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." }, "coupons": { "type": "array", "items": { "type": "string" }, "description": "A list of coupon codes to validate." }, "lock": { "type": "boolean", "description": "Indicates whether the request is intended to validate the coupon or to lock it for a future redemption." }, "lockReference": { "type": "string", "description": "Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session." }, "lockDuration": { "type": "integer", "description": "Represents the number of minutes for which a coupon will be locked if the lock flag is set to True." }, "merchantId": { "type": "string", "description": "This parameter is required only if the coupon is designed to apply to specific merchants." }, "collectionId": { "type": "string", "description": "This parameter is required only if the coupon is configured to apply to specific collections." }, "collectionsIds": { "type": "array", "items": { "type": "string" }, "description": "This parameter is required only when the coupon is configured to apply to specific collections." }, "totalPurchaseAmount": { "type": "number", "description": "This parameter represents the total value of the purchase where the coupon will be applied." } } } } } }, "responses": { "200": { "description": "Coupons validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Indicates whether the coupons are valid." }, "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" }, "description": "An array containing the details of the coupons that need to be locked or validated in the request." }, "lockReference": { "type": "string", "description": "The unique reference code associated with the coupon lock session." }, "dateToExpire": { "type": "string", "format": "date-time", "description": "The exact date and time when the coupon lock will expire." } } } } } } } } }, "/api/v4.0/integrations/coupons/burn": { "post": { "description": "This API processes the use of one or more coupons associated with a customer in Gameball. By providing customer details and a list of coupons, this endpoint marks the coupons as redeemed, completing the transaction. Optionally, a lockReference can be included to burn previously locked coupons.", "security": [ { "apiKey": [], "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "transactionId": { "type": "string", "description": "A unique identifier for the transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any coupon burn transactions in Gameball.", "example": "txn98765" }, "transactionTime": { "type": "string", "format": "date-time", "description": "The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).", "example": "2024-10-11T10:57:43.382Z" }, "coupons": { "type": "array", "items": { "type": "string" }, "description": "List of coupons that need to be burned. Only one of coupons or lockReference must be provided." }, "lockReference": { "type": "string", "description": "Reference used to burn the locked coupons from the validation step. Only one of coupons or lockReference must be provided." } } } } } }, "responses": { "200": { "description": "Coupon burned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "burnedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/v4.0/integrations/coupons/{lockReference}": { "delete": { "description": "This API releases the lock on coupons identified by the provided {lockReference} in Gameball. Once released, the coupons become available for use again, offering flexibility in managing coupon availability and redemption.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "lockReference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the previously locked coupons to be available for others to use again or for another session." } ], "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" } } } } } } } } } }, "/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" } } } } } } } } } } } }, "/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" } } } } } } } } } }, "/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" } } } } } } } } } }, "/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" } } } } } } } } } }, "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" } } } } } } } } }, "/api/v4.0/integrations/configurations/reward-campaigns": { "get": { "summary": "Campaigns Configurations", "description": "The API retrieves your reward campaign configurations, including both event-based and transactional campaigns. If the customerId, productSku, or collectionId query parameters are provided, the response will include the reward campaigns that are applicable for the specified customer or product.", "operationId": "getCampaignsConfigurations", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "query", "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 API filters and returns only the campaigns that can be achieved by this customer.", "required": false, "schema": { "type": "string" } }, { "name": "collectionId", "in": "query", "description": "Unique identifier for a product collection. If provided, the API returns the transactional campaigns applicable to the specified collection.", "required": false, "schema": { "type": "string" } }, { "name": "productSku", "in": "query", "description": "The SKU (Stock Keeping Unit) of a product. If provided, the API returns the transactional campaigns applicable to the specified product.", "required": false, "schema": { "type": "string" } }, { "name": "lang", "in": "header", "description": "If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RewardCampaignConfiguration" } } } } } } } }, "/api/v4.0/integrations/configurations/tiers": { "get": { "summary": "Tiers Configurations", "description": "This API call retrieves the tiers configuration, including the benefits and rewards associated with each tier.", "operationId": "getTiersConfigurations", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "lang", "in": "header", "description": "If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "VIP tiers retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TierConfiguration" } } } } } } } }, "/api/v4.0/integrations/configurations/referrals": { "get": { "summary": "Referrals Configurations", "description": "This API retrieves the referral configuration, including customer and friend rewards, as well as metadata related to the events that trigger referral rewards.", "operationId": "getReferralsConfigurations", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "lang", "in": "header", "description": "If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral settings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralConfiguration" } } } } } } }, "/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" } } } } } } } } } } }, "/api/v4.0/integrations/leaderboard": { "get": { "description": "This API retrieves the leaderboard rankings of customers within your loyalty program in Gameball, either for a specific date range or for all time. Results are ordered from the highest to the lowest rank, displaying each customer's rank, progress, and tier details.", "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", "description": "An array of customers ranked on the leaderboard, sorted by their score. Each entry in the array includes details about each customer, providing a comprehensive overview of their standing within the entire customer base.", "items": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The display name of the customer on the leaderboard.", "example": "John Doe" }, "customerId": { "type": "string", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime.", "example": "cust_12345" }, "progress": { "type": "number", "description": "The progress made by the customer, such as points earned.", "example": 2500 }, "rank": { "type": "number", "description": "The customer's position on the leaderboard, determined by their performance, such as points accumulated. The rank is typically higher for those with more points or progress.", "example": 1 }, "tierName": { "type": "string", "description": "The name of the customer's current tier.", "example": "Gold" }, "tierIcon": { "type": "string", "description": "URL for the icon representing the customer's current tier.", "example": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp" } } } }, "customerRank": { "type": "number", "description": "The position of the requested customer on the leaderboard, reflecting their rank relative to all other customers in your entire customer base. A lower rank number (e.g., 1) indicates a higher standing, typically based on points or achievements.", "example": 1 }, "customersCount": { "type": "number", "description": "The total number of customers on the leaderboard.", "example": 100 } } } } } } } } }, "/api/v4.0/integrations/configurations/cashback": { "get": { "description": "This API call retrieves your cashback configurations, providing essential details about how cashback rewards are structured and managed in Gameball. If the customerId is provided, the API will return any special cashback rules associated with the customer's tier, including potential bonuses or customized reward factors specific to that customer.", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "query", "description": "Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be database ID, random string, email or anything that uniquely identifies the customer. If provided, the response will return the cashback rules specific to this customer's tier, reflecting any special configurations or bonuses this customer is eligible for based on their tier cashback rules.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cashback configurations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultCashbackRule": { "type": "object", "description": "The default cashback rule applied to all customers if no tier-specific rules are available.", "properties": { "amountRewardThreshold": { "type": "number", "description": "The minimum amount that must be spent by the customer to qualify for a cashback reward. Transactions below this threshold will not earn any cashback, incentivizing higher spending. Example: If the amountRewardThreshold is set to $50, a customer must spend at least $50 to be eligible for cashback rewards.", "example": 1.0 }, "rewardWalletFactor": { "type": "number", "description": "The factor used to calculate the amount of loyalty points added to the customer's wallet based on the cashback amount earned from transactions. This factor determines how many points customers receive relative to the cashback they earn. Example: If a customer receives $10 in cashback and the rewardWalletFactor is 2, the customer will earn 20 loyalty points (2 times the cashback amount).", "example": 1.0 }, "rewardRankFactor": { "type": "number", "description": "In case your tiering-up method is based on score, this factor determines the score rewarded for each unit of currency your customer spends. It directly impacts how quickly customers can progress through tiers in your loyalty program. Example: If the rewardRankFactor is set to 2, the customer earns 2 score points for every 1 USD spent.", "example": 1.0 }, "rewardFactor": { "type": "number", "description": "It is a calculated value that determines the reward a customer earns relative to their spending. It considers the AmountRewardThreshold (Minimum Amount Required), RewardWalletFactor (Earning Rate), and RedemptionFactor (Monetary Value of Points). Formula: Reward Factor = (Amount Reward Threshold / Reward Wallet Factor) × Redemption Factor × 100. This indicates the percentage of what the customer earns as a cashback reward based on their spendings.", "example": 10.0 } } }, "tierCashbackRules": { "type": "array", "description": "A list of tier-specific cashback rules, which override the default cashback rule for customers in a specific tier.", "items": { "type": "object", "properties": { "tierName": { "type": "string", "description": "The name of the tier that has its own cashback rule.", "example": "Gold" }, "amountRewardThreshold": { "type": "number", "description": "The minimum amount that must be spent by the customer to qualify for a cashback reward. Transactions below this threshold will not earn any cashback, incentivizing higher spending. Example: If the amountRewardThreshold is set to $50, a customer must spend at least $50 to be eligible for cashback rewards.", "example": 1.0 }, "rewardWalletFactor": { "type": "number", "description": "The factor used to calculate the amount of loyalty points added to the customer's wallet based on the cashback amount earned from transactions. This factor determines how many points customers receive relative to the cashback they earn. Example: If a customer receives $10 in cashback and the rewardWalletFactor is 2, the customer will earn 20 loyalty points (2 times the cashback amount).", "example": 20.0 }, "rewardRankFactor": { "type": "number", "description": "In case your tiering-up method is based on score, this factor determines the score rewarded for each unit of currency your customer spends. It directly impacts how quickly customers can progress through tiers in your loyalty program. Example: If the rewardRankFactor is set to 2, the customer earns 2 score points for every 1 USD spent.", "example": 1.0 }, "rewardFactor": { "type": "number", "description": "It is a calculated value that determines the reward a customer earns relative to their spending. It considers the AmountRewardThreshold (Minimum Amount Required), RewardWalletFactor (Earning Rate), and RedemptionFactor (Monetary Value of Points). Formula: Reward Factor = (Amount Reward Threshold / Reward Wallet Factor) × Redemption Factor × 100. This indicates the percentage of what the customer earns as a cashback reward based on their spendings.", "example": 0.0 } } } } } } } } } } } }, "/api/v4.0/integrations/configurations/redemption": { "get": { "description": "This API retrieves the configurations and rules associated with how customers can redeem points for discounts, coupons, or other rewards.", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "query", "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 API will return redemption configurations that match the customer based on various criteria, such as RFM, tiers, segments and specific customer attributes. This approach ensures that the redemption options are personalized and relevant to each customer's unique profile and engagement history.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redemption configurations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "redemptionFactor": { "type": "number", "description": "This factor indicates the value of each loyalty point in terms of currency, defining how many currency units can be obtained by redeeming points. Example: If the redemptionFactor is set to 0.1, this means that a customer can redeem 10 points for 1 USD.", "example": 0.1 }, "redemptionRules": { "type": "array", "description": "A list of redemption rules that define how points can be redeemed for discounts and coupons. Defines the rules for redeeming points, including points required, value of points, applicable coupons, and eligibility criteria. Example: a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts.", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier for the redemption rule.", "example": 2138 }, "pointsToRedeem": { "type": "number", "description": "The specific number of points needed for redemption. If null, the rule applies to all points.", "example": 100 }, "valueOfPoint": { "type": "number", "description": "The value of a single point in terms of monetary value for redemption.", "example": 25.0 }, "ruleType": { "type": "string", "description": "The type of rule governing the redemption. Possible values include: free_shipping_settings, percentage_discount_settings, free_product_settings, fixed_rate_settings.", "example": "percentage_discount_settings" }, "coupon": { "type": "object", "description": "Defines the coupon associated with the redemption rule, if applicable.", "properties": { "couponType": { "type": "string", "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.", "example": "percentage_discount" }, "discountValue": { "type": "number", "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount.", "example": 25.0 }, "product": { "type": "object", "description": "Product information for free product coupons.", "properties": { "productId": { "type": "string", "description": "The unique identifier for the product." }, "productName": { "type": "string", "description": "The name of the product." }, "variantId": { "type": "string", "description": "The unique identifier for the product variant." }, "variantName": { "type": "string", "description": "The name of the product variant." }, "productDisplayName": { "type": "string", "description": "The display name associated with the product that configured on the dashboard based on required language." } } }, "collections": { "type": "array", "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "The unique identifier for the collection.", "example": "455218036961" }, "collectionName": { "type": "string", "description": "The name for the collection.", "example": "Automated Collection" } } } }, "group": { "type": "object", "description": "Coupon group information.", "properties": { "handle": { "type": "string", "description": "A unique identifier used to reference the coupon group in the system (only appears in the dashboard)." }, "title": { "type": "string", "description": "The title of the coupon group." }, "url": { "type": "string", "description": "The URL for the coupon group." }, "iconPath": { "type": "string", "description": "The path to the icon of the coupon group." }, "description": { "type": "string", "description": "A description of the coupon group." }, "maxPerCustomer": { "type": "number", "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": "string", "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": "string", "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": "boolean", "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": "boolean", "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": "object", "description": "Coupon options and settings.", "properties": { "name": { "type": "string", "description": "The name of the redemption rule configured on the dashboard based on required language.", "example": "Redemption Rule Name" }, "expiryAfter": { "type": "number", "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.", "example": 14 }, "usageLimit": { "type": "number", "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.", "example": 2 }, "capping": { "type": "number", "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.", "example": 50 }, "minOrderValue": { "type": "number", "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.", "example": 150.0 }, "codePrefix": { "type": "string", "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is 'SUMMER', the generated coupon codes might look like 'SUMMER12345' or 'SUMMERDISCOUNT'.", "example": "SUMMER" }, "redeemInstructions": { "type": "string", "description": "The instructions on how the customer can redeem the coupon. Example: 'Enter the coupon code at checkout to apply the discount.'", "example": "Enter the coupon code at checkout to apply the discount." } } } } }, "image": { "type": "string", "description": "A URL or file path for an image representing the redemption rule.", "example": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads%2fClient_2933%2f936f65d8-e06d-4e28-b423-b5282999801bgameball.webp" }, "creationDate": { "type": "string", "format": "date-time", "description": "The date when the redemption rule was created.", "example": "2025-02-10T10:12:16.783408" }, "isActive": { "type": "boolean", "description": "Indicates whether the redemption rule is currently active and can be used to generate new coupons or not. true → The rule is active, and new coupons can be created and redeemed. false → The rule is inactive, meaning no new coupons can be generated. However, previously created coupons will still be valid and can be redeemed. Example: If isActive is false, customers cannot create new coupons, but any coupons generated before the rule became inactive can still be used.", "example": true } } } } } } } } } } } }, "/api/v4.0/integrations/configurations/coupon": { "get": { "description": "This API call retrieves your coupon configurations, including details about how coupons are structured, authenticated, and mapped within Gameball.", "security": [{ "apiKey": [], "secretKey": [] }], "responses": { "200": { "description": "Coupon configurations retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL where the coupon configuration is applied.", "example": "https://api.mywebsite.com/coupons" }, "method": { "type": "string", "description": "The HTTP method used for the coupon configuration process (e.g., POST, PUT or GET).", "example": "POST" }, "queryParams": { "type": "array", "description": "List of query parameters used in the request.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The key used in the query parameter.", "example": "appId" }, "value": { "type": "string", "description": "The value of the query parameter.", "example": "12345" } } } }, "headers": { "type": "array", "description": "List of headers used in the request.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The header key.", "example": "Authorization" }, "value": { "type": "string", "description": "The header value.", "example": "Bearer token" } } } }, "payload": { "type": "string", "description": "The request payload format or template.", "example": "{ \"couponCode\": \"DISCOUNT10\" }" }, "couponMapping": { "type": "object", "description": "A dictionary mapping coupon types to specific keys in your system.", "properties": { "fixed": { "type": "string", "description": "The internal naming for the fixed discount codes in your system.", "example": "fixed_discount" }, "percentage": { "type": "string", "description": "The internal naming for the percentage discount codes in your system.", "example": "percentage_discount" }, "freeProduct": { "type": "string", "description": "The internal naming for the free product discount codes in your system.", "example": "free_product" }, "freeShipping": { "type": "string", "description": "The internal naming for the free shipping discount codes in your system.", "example": "free_delivery" } } }, "enableFreeProduct": { "type": "boolean", "description": "Indicates whether free product coupons are enabled.", "example": true }, "enableFixedRate": { "type": "boolean", "description": "Indicates whether fixed-rate discount coupons are enabled.", "example": true }, "enableFreeShipping": { "type": "boolean", "description": "Indicates whether free shipping coupons are enabled.", "example": true }, "enablePercentage": { "type": "boolean", "description": "Indicates whether percentage-based discount coupons are enabled.", "example": true }, "platforms": { "type": "array", "description": "List of platforms for which the coupon configurations are applied.", "items": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The display name of the platform." }, "value": { "type": "string", "description": "The internal value used for the platform." } } } } } } } } } } }, "put": { "description": "This API call updates your coupon configurations, allowing you to modify details about how coupons are structured, authenticated, and mapped within Gameball.", "security": [{ "apiKey": [], "secretKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "method"], "properties": { "url": { "type": "string", "description": "The URL of your API endpoint where coupons are created. Gameball will send requests to this endpoint whenever a coupon needs to be generated.", "example": "https://api.mywebsite.com/coupons" }, "method": { "type": "string", "description": "The HTTP method used to send requests to the coupon creation endpoint. Allowed values are POST, PUT or GET.", "example": "POST" }, "queryParams": { "type": "array", "description": "List of query parameters used in the request. Those that will be appended to the URL endpoint. These are used to pass specific parameters required by your coupon system as part of the URL itself, often for identification, filtering, or configuration purposes. Each query parameter is defined by a key-value pair, allowing you to tailor requests based on requirements in your API.", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "The key used in the query parameter.", "example": "appId" }, "value": { "type": "string", "description": "The value of the query parameter.", "example": "12345" } } } }, "headers": { "type": "array", "description": "List of headers used in the request.", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "The header key.", "example": "X-Client-Version" }, "value": { "type": "string", "description": "The header value.", "example": "1.0" } } } }, "payload": { "type": "string", "description": "This specifies the structure of the JSON body Gameball will send to your endpoint when creating a coupon. Since different systems may use varying parameter names and structures, you can customize this payload to align with your system's requirements. You should define the JSON payload with placeholders that Gameball will replace with actual data when sending the request. Example: { \"customerId\": \"{{playerUniqueId}}\", \"amount\": \"{{value}}\", \"code\": \"{{code}}\" }", "example": "{ \"couponCode\": \"DISCOUNT10\" }" }, "couponMapping": { "type": "object", "description": "A dictionary mapping coupon attributes to specific keys in your system.", "properties": { "fixed": { "type": "string", "description": "The internal naming for the fixed discount codes in your system.", "example": "fixed_discount" }, "percentage": { "type": "string", "description": "The internal naming for the percentage discount codes in your system.", "example": "percentage_discount" }, "freeProduct": { "type": "string", "description": "The internal naming for the free product discount codes in your system.", "example": "free_product" }, "freeShipping": { "type": "string", "description": "The internal naming for the free shipping discount codes in your system.", "example": "free_delivery" } } }, "enableFreeProduct": { "type": "boolean", "description": "Indicates whether free product coupons are enabled.", "example": true }, "enableFixedRate": { "type": "boolean", "description": "Indicates whether fixed-rate discount coupons are enabled.", "example": true }, "enableFreeShipping": { "type": "boolean", "description": "Indicates whether free shipping coupons are enabled.", "example": true }, "enablePercentage": { "type": "boolean", "description": "Indicates whether percentage-based discount coupons are enabled.", "example": true }, "platforms": { "type": "array", "description": "List of platforms for which the coupon configurations are applied in your system.", "items": { "type": "object", "required": ["displayName", "value"], "properties": { "displayName": { "type": "string", "description": "The display name of the platform." }, "value": { "type": "string", "description": "The internal value used for the platform." } } } } } } } } }, "responses": { "200": { "description": "Coupon configurations updated successfully" } } } }, "/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." }, "referrerCode": { "type": "string", "description": "The referral code of an existing customer who is referring the customer being created. This is required in the create customer request to process the referral." }, "guest": { "type": "boolean", "description": "A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default." }, "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", "description": "Display name for the customer." }, "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "email": { "type": "string", "description": "Customer's email address." }, "gender": { "type": "string", "description": "Customer's gender." }, "mobile": { "type": "string", "description": "Customer's mobile number." }, "dateOfBirth": { "type": "string", "description": "Customer's date of birth." }, "joinDate": { "type": "string", "description": "Date the customer joined." }, "country": { "type": "string", "description": "Customer's country." }, "city": { "type": "string", "description": "Customer's city." }, "zip": { "type": "string", "description": "Customer's postal code." }, "preferredLanguage": { "type": "string", "description": "The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference." }, "source": { "type": "string", "description": "Source of the customer registration." }, "utms": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "devices": { "type": "array", "description": "List of devices associated with the customer." }, "paymentMethods": { "type": "array", "description": "List of payment methods used by the customer. This array may include various forms of payment, such as credit cards, PayPal, or other payment providers. Each payment method is represented as a string." }, "totalSpent": { "type": "number", "description": "Total amount spent by the customer." }, "lastOrderDate": { "type": "string", "description": "Date of the last order placed by the customer." }, "totalOrders": { "type": "integer", "description": "Total number of orders placed by the customer." }, "avgOrderAmount": { "type": "number", "description": "Average amount spent per order by this customer." }, "channel": { "type": "string", "description": "Indicates the channel through which the customer was acquired or engaged. This is especially useful for systems that support multiple channels to track customer origin and interactions. Understanding the acquisition or engagement channel helps in tailoring marketing strategies, optimizing communication, and analyzing customer preferences.", "enum": ["mobile", "pos", "web", "callcenter"] }, "custom": { "type": "object", "additionalProperties": true, "description": "Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings." } } } } } } } } } } }, "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." } } } } } } } } }, "/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. Must be in UTC (ISO 8601 format), e.g. `2024-10-16T08:13:29.290Z`." }, "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." } } } } } } } } }, "/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." } } } } } } } } }, "/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." } } } } } } } } }, "/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. Must be in UTC (ISO 8601 format)." }, "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." } } } } } } } } }, "/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. Must be in UTC (ISO 8601 format)." }, "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." } } } } } } } } }, "/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." } } } } } } } } }, "/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" } } } } } } } } }, "/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" } } } } } } } } }, "/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. Must be in UTC (ISO 8601 format), e.g. `2024-10-16T08:13:29.290Z`.", "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 } } } } } } } } } } } }, "/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. **Payment** - Recorded when a customer makes a payment for an order. **Refund** - Captured when points redeemed from a refunded order are returned to the customer. **PartialRefund** - Captured when a partial refund is processed, returning a portion of redeemed points 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", "Payment", "Refund", "PartialRefund", "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": { } } }, "/api/v4.0/integrations/customers/{customerId}/balance": { "get": { "summary": "Get Customer Balance", "description": "This API retrieves a customer's current points balance within Gameball, including redeemable points and their monetary equivalent. It provides detailed balance information, such as total, available, and pending points, along with upcoming expirations.\n\n**Security:** Requires both `apikey` and `secretkey` headers.", "operationId": "getCustomerBalance", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "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.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" } ], "responses": { "200": { "description": "Customer balance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBalanceResponse" }, "example": { "totalPointsBalance": 1500, "totalPointsValue": 75.0, "availablePointsBalance": 1200, "availablePointsValue": 60.0, "pendingPoints": 300, "pendingPointsValue": 15.0, "currency": "USD", "pointsName": "Reward Points", "nextExpiringPointsAmount": 200, "nextExpiringPointsValue": 10.0, "nextExpiringPointsDate": "2024-12-01T00:00:00", "totalEarnedPoints": 2500 } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/tier-progress": { "get": { "summary": "Get Customer Tier Progress", "description": "This API provides an overview of a customer's current tier and progression within Gameball's loyalty program. By retrieving the customer's current tier, progress level, and next tier details, this endpoint offers a clear view of their advancement within the tier structure.", "operationId": "getCustomerTierProgress", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" }, { "name": "lang", "in": "header", "required": false, "schema": { "type": "string" }, "description": "If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language." } ], "responses": { "200": { "description": "Customer tier progress retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTierProgressResponse" }, "example": { "current": { "order": 1, "name": "Basic", "minProgress": 0, "icon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp" }, "next": { "order": 2, "name": "Gold", "minProgress": 190, "icon": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads/gb-library/levels-icons/level-a1.webp" }, "progress": 50 } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress": { "get": { "summary": "Get Customer Campaigns Progress", "description": "This API retrieves a customer's progress within Gameball's reward campaigns, providing insights into their achievements and current status in each campaign. By accessing completion percentages and unlock statuses, you can track how customers are engaging with various reward opportunities.", "operationId": "getCustomerCampaignsProgress", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "lang", "in": "header", "required": false, "schema": { "type": "string" }, "description": "If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language." }, { "name": "campaignType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["reward", "game"] }, "description": "Filter campaigns by type. Use `reward` to return only reward-type campaigns (points multipliers, missions, spending milestones, streaks, etc.), or `game` for game-type campaigns (Spin the Wheel, Slot Machine, Quiz, Scratch & Win, Match Cards, etc.). Omit to return all campaigns. Any other value results in a validation error." }, { "name": "campaignId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Filter the response to a single campaign by its ID. When provided, the response array contains at most one item: the matching campaign's progress, or an empty array if the campaign does not exist or is not available to this customer. Must be a positive integer. Use the campaign ID returned in rewardsCampaignId or rewardCampaignConfiguration.id. Can be combined with campaignType, in which case both filters apply." } ], "responses": { "200": { "description": "Customer campaigns progress retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCampaignsProgressResponse" } } } }, "400": { "description": "Bad request. Returned when campaignId is non-numeric, such as campaignId=abc." }, "422": { "description": "Unprocessable entity. Returned when campaignId is zero or negative.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 3003 }, "type": { "type": "string", "example": "PAYLOAD_ERROR" }, "message": { "type": "string", "example": "invalid campaignid value. the campaign id must be a positive integer." } } }, "example": { "code": 3003, "type": "PAYLOAD_ERROR", "message": "invalid campaignid value. the campaign id must be a positive integer." } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals": { "get": { "summary": "Get Customer Referrals", "description": "This API retrieves a list of customers referred by a specified customer in Gameball, including each referral's join date and current status within the referral program.", "operationId": "getCustomerReferrals", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which Gameball customer id. Defaults to 0." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Specifies the number of friends to return per page. Defaults to 50, with a maximum limit of 200 transactions per page." } ], "responses": { "200": { "description": "Customer referrals retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals/count": { "get": { "summary": "Get Customer Referrals Count", "description": "This API retrieves the total count of customers referred by a specified customer in Gameball, 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 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." } ], "responses": { "200": { "description": "Customer referrals count retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsCountResponse" }, "example": { "count": 15, "totalPending": 5, "totalActive": 10 } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/activities": { "get": { "summary": "Get Customer Activities", "description": "This API retrieves a log of customer activities within Gameball, identified by customerId. The logs detail various actions, such as tier changes, campaign rewards, referrals, redemptions, and more. Specific activity types can be filtered, including events like TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing comprehensive visibility into each customer's engagement history.", "operationId": "getCustomerActivities", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which activity id. Defaults to 0." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Specifies the number of activities to return per page. Defaults to 50, with a maximum limit of 200 transactions 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": "Filters activities by a specific type, such as: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer's tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign)." } ], "responses": { "200": { "description": "Customer activities retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/activities/count": { "get": { "summary": "Get Customer Activities Count", "description": "This API retrieves the total count of customer activities within Gameball, identified by customerId. It allows for filtering by specific activity types, such as TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing the number of activities matching the specified criteria without returning detailed activity logs.", "operationId": "getCustomerActivitiesCount", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "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": "Filters activities by a specific type, such as: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer's tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign)." } ], "responses": { "200": { "description": "Customer activities count retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesCountResponse" }, "example": { "count": 240 } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/automation": { "get": { "summary": "Get Customer Automation Campaigns", "description": "This API retrieves the available automation campaigns for the customer, identified by customerId. The response includes details of campaigns currently active and applicable to the customer, such as onboarding journeys, engagement triggers, or milestone-based campaigns. Specific campaign types can be filtered, including campaigns like Welcome Campaigns, Ramadan Campaign, and Custom Automations, offering a comprehensive view of personalized campaigns available for the customer.", "operationId": "getCustomerAutomationCampaigns", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "campaignType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mission", "all"], "default": "mission" }, "description": "Filters automation steps by a specific type, such as: mission (return steps for mission-based campaigns, default), all (return all automation steps and details)." } ], "responses": { "200": { "description": "Customer automation campaigns found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAutomationCampaignsResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/stamps/{challengeId}": { "get": { "summary": "Get Customer Stamps Progress", "description": "Retrieve the progress of a specific customer within a particular Stamps campaign in Gameball. It returns how many steps the customer has completed, how many times they've earned the campaign reward, and whether they are eligible to continue.", "operationId": "getCustomerStampsProgress", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "challengeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique identifier of the Stamps campaign to retrieve progress for." } ], "responses": { "200": { "description": "Customer stamps progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionStreakProgressResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/streaks/{campaignId}": { "get": { "summary": "Get Customer Daily Streak Progress", "description": "Retrieve the progress of a specific customer within a particular daily streak campaign in Gameball. It returns the current and highest streak counts, ongoing reward details, badge milestones, and the next milestone to unlock.", "operationId": "getCustomerDailyStreakProgress", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "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." }, { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique identifier of the daily streak campaign to retrieve progress for." } ], "responses": { "200": { "description": "Customer daily streak progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDailyStreakProgressResponse" } } } }, "401": { "description": "Unauthorized – apikey or secretkey is missing or invalid" }, "404": { "description": "Customer or campaign not found" } } } }, "/api/v4.0/integrations/customers/{customerId}/tags": { "post": { "summary": "Attach Customer Tags", "description": "This API allows you to add tags to a customer profile in Gameball, identified by `customerId`. Attaching tags enables categorization of customer profiles, supporting organized management and targeted engagement based on specific attributes.", "operationId": "attachCustomerTags", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTagsUpdateRequest" } } } }, "responses": { "200": { "description": "Tags attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } } } }, "delete": { "summary": "Remove Customer Tags", "description": "This API removes specified tags from a customer profile in Gameball, identified by `customerId`. Removing tags allows for updating customer categorization, ensuring profiles remain relevant to current engagement and marketing needs.", "operationId": "removeCustomerTags", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTagsUpdateRequest" } } } }, "responses": { "200": { "description": "Tags removed", "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" } } } } } } } } }, "/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" } } } } } } }, "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" } } } } } } }, "/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": { } } } }, "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", "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", "description": "Display name for the customer." }, "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "email": { "type": "string", "description": "Customer's email address." }, "gender": { "type": "string", "description": "Customer's gender." }, "mobile": { "type": "string", "description": "Customer's mobile number." }, "dateOfBirth": { "type": "string", "description": "Customer's date of birth." }, "joinDate": { "type": "string", "description": "Date the customer joined." }, "country": { "type": "string", "description": "Customer's country." }, "city": { "type": "string", "description": "Customer's city." }, "zip": { "type": "string", "description": "Customer's postal code." }, "preferredLanguage": { "type": "string", "description": "The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference." }, "source": { "type": "string", "description": "Source of the customer registration." }, "utms": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "devices": { "type": "array", "description": "List of devices associated with the customer." }, "paymentMethods": { "type": "array", "description": "List of payment methods used by the customer. This array may include various forms of payment, such as credit cards, PayPal, or other payment providers. Each payment method is represented as a string." }, "totalSpent": { "type": "number", "description": "Total amount spent by the customer." }, "lastOrderDate": { "type": "string", "description": "Date of the last order placed by the customer." }, "totalOrders": { "type": "integer", "description": "Total number of orders placed by the customer." }, "avgOrderAmount": { "type": "number", "description": "Average amount spent per order by this customer." }, "channel": { "type": "string", "description": "Indicates the channel through which the customer was acquired or engaged. This is especially useful for systems that support multiple channels to track customer origin and interactions. Understanding the acquisition or engagement channel helps in tailoring marketing strategies, optimizing communication, and analyzing customer preferences.", "enum": ["mobile", "pos", "web", "callcenter"] }, "custom": { "type": "object", "additionalProperties": true, "description": "Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings." } } }, "referrerCode": { "type": "string", "description": "The referral code of an existing customer who is referring the customer being created. This is required in the create customer request to process the referral." }, "guest": { "type": "boolean", "description": "A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default." } } }, "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": { "code": { "type": "string", "description": "The generated coupon code that the customer will use." }, "type": { "type": "string", "enum": ["shipping", "fixed", "percentage", "product", "percentage-fees", "fixed-cashback", "percentage-cashback"], "description": "Type of the coupon, such as fixed amount, percentage discount, free shipping, cashback or product-specific coupon." }, "value": { "type": "number", "description": "The monetary value or percentage value of the coupon, depending on its type." }, "usageLimit": { "type": "number", "description": "The total number of times the coupon can be used across all customers." }, "limitPerCustomer": { "type": "number", "description": "The number of times a single customer can use the coupon." }, "startDate": { "type": "string", "format": "date-time", "description": "The date and time when the coupon becomes valid and can be used." }, "expiryDate": { "type": "string", "format": "date-time", "description": "The date and time when the coupon will expire and no longer be valid." }, "capping": { "type": "number", "description": "The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value." }, "minReward": { "type": "number", "description": "Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon." }, "minOrderValue": { "type": "number", "description": "The minimum order value required for the coupon to be applied." }, "entitledProductIds": { "type": "array", "items": { "type": "string" }, "description": "A list of product IDs that are eligible for the coupon." }, "entitledVariantIds": { "type": "array", "items": { "type": "string" }, "description": "A list of product variant IDs that are eligible for the coupon." }, "entitledCollectionIds": { "type": "array", "items": { "type": "string" }, "description": "A list of collection IDs that are eligible for the coupon." }, "entitledMerchantIds": { "type": "array", "items": { "type": "string" }, "description": "A list of merchant external IDs that are eligible to redeem the coupon." }, "combinesWith": { "type": "object", "properties": { "orderDiscounts": { "type": "boolean", "description": "Indicates if the coupon can be combined with order-level discounts." }, "productDiscounts": { "type": "boolean", "description": "Indicates if the coupon can be combined with product-specific discounts." }, "shippingDiscounts": { "type": "boolean", "description": "Indicates if the coupon can be combined with shipping discounts." } } } } }, "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" } } } } }, "CustomerBalanceResponse": { "type": "object", "properties": { "totalPointsBalance": { "type": "number", "description": "The total number of points the customer has, including pending points." }, "totalPointsValue": { "type": "number", "description": "The total monetary value of the customer's points, including pending points." }, "availablePointsBalance": { "type": "number", "description": "The number of points that are currently active and available for use (excludes pending points)." }, "availablePointsValue": { "type": "number", "description": "The monetary value of the points that are currently active and available for use (excludes pending points)." }, "pendingPoints": { "type": "number", "description": "The points earned by the customer that are temporarily on hold during the return window configured for your account. These points will remain in a pending status until the return period expires, ensuring that the points are not used or redeemed until it is confirmed that the transaction is final and not subject to returns or cancellations. Example: If a customer places an order and earns 100 points, and your account is configured with a 14-day return window, these 100 points will remain pending for 14 days. During this time, the customer cannot use or redeem the points. After the 14-day window expires and the order is confirmed as final, the 100 points will become available for the customer to use." }, "pendingPointsValue": { "type": "number", "description": "The monetary value of the pending points." }, "currency": { "type": "string", "description": "The currency in which the points value is calculated." }, "pointsName": { "type": "string", "description": "The name of the points used in your loyalty program that appears to customers. This is the term your customers will see when they earn or redeem points. Example: If your loyalty program rewards customers with \"Stars\" instead of generic \"Points\", the value of pointsName could be \"Stars\"." }, "nextExpiringPointsAmount": { "type": "number", "description": "The amount of points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame." }, "nextExpiringPointsValue": { "type": "number", "description": "The monetary value of the points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame." }, "nextExpiringPointsDate": { "type": "string", "description": "The date when the next set of points will expire. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame." }, "totalEarnedPoints": { "type": "number", "description": "The total number of points that the customer has earned over their entire lifetime within the Gameball program. This includes all points accumulated from various activities like cashback rewards, referrals, or rewards campaigns." } } }, "TierState": { "type": "object", "properties": { "order": { "type": "number", "description": "This represents the numerical order of a tier. Higher numbers indicate higher tiers." }, "name": { "type": "string", "description": "The name of the tier." }, "minProgress": { "type": "number", "description": "The minimum amount of progress a customer needs to reach the next tier in the program. This represents the threshold that must be met for a customer to reach this tier. Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to advance to the next tier." }, "icon": { "type": "string", "description": "The URL for the icon associated with the tier. You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles. This offers a visual representation of the customer's tier status." } } }, "CustomerTierProgressResponse": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/TierState", "description": "The customer's current tier." }, "next": { "$ref": "#/components/schemas/TierState", "description": "The next tier the customer can reach." }, "progress": { "type": "number", "description": "The current progress of the customer toward the next tier, reflecting their activity and engagement within the program. This value is calculated based on the client's chosen tiering-up method, indicating how close the customer is to advancing to a higher tier. Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier. Possible Values: Total amount spent, Total points earned, Friends referred, Orders completed, Score." } } }, "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)", "properties": { "gender": { "type": "string", "description": "Customer's gender." }, "country": { "type": "string", "description": "Customer's country." }, "city": { "type": "string", "description": "Customer's city." }, "zip": { "type": "string", "description": "Customer's postal code." }, "custom": { "type": "object", "additionalProperties": true, "description": "Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the customer." }, "source": { "type": "string", "description": "Source of the customer registration." }, "utMs": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "utms": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "devices": { "type": "array", "description": "List of devices associated with the customer." }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "description": "List of payment methods used by the customer." }, "totalSpent": { "type": "number", "description": "Total amount spent by the customer." }, "lastOrderDate": { "type": "string", "description": "Date of the last order placed by the customer." }, "totalOrders": { "type": "number", "description": "Total number of orders placed by the customer." }, "manualDate": { "type": "string", "description": "Custom date for manual entries." } } }, "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", "properties": { "displayName": { "type": "string", "description": "Display name for the customer." }, "firstName": { "type": "string", "description": "Customer's first name." }, "lastName": { "type": "string", "description": "Customer's last name." }, "email": { "type": "string", "description": "Customer's email address." }, "gender": { "type": "string", "description": "Customer's gender." }, "mobile": { "type": "string", "description": "Customer's mobile number." }, "dateOfBirth": { "type": "string", "description": "Customer's date of birth." }, "joinDate": { "type": "string", "description": "Date the customer joined." }, "country": { "type": "string", "description": "Customer's country." }, "city": { "type": "string", "description": "Customer's city." }, "zip": { "type": "string", "description": "Customer's postal code." }, "preferredLanguage": { "type": "string", "description": "The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "A list of tags or labels associated with the customer. These tags are used to categorize customers for personalized marketing campaigns, rewards, and tailored communications." }, "source": { "type": "string", "description": "Source of the customer registration." }, "utms": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "utMs": { "type": "array", "description": "List of UTM attributes associated with the customer." }, "devices": { "type": "array", "description": "List of devices associated with the customer." }, "paymentMethods": { "type": "array", "items": { "type": "string" }, "description": "List of payment methods used by the customer. This array may include various forms of payment, such as credit cards, PayPal, or other payment providers. Each payment method is represented as a string." }, "totalSpent": { "type": "number", "description": "Total amount spent by the customer." }, "lastOrderDate": { "type": "string", "description": "Date of the last order placed by the customer." }, "totalOrders": { "type": "number", "description": "Total number of orders placed by the customer." }, "avgOrderAmount": { "type": "number", "description": "Average amount spent per order by this customer." }, "channel": { "type": "string", "description": "Indicates the channel through which the customer was acquired or engaged. This is especially useful for systems that support multiple channels to track customer origin and interactions. Understanding the acquisition or engagement channel helps in tailoring marketing strategies, optimizing communication, and analyzing customer preferences.", "enum": ["mobile", "pos", "web", "callcenter"] }, "custom": { "type": "object", "additionalProperties": true, "description": "Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings." }, "manualDate": { "type": "string", "description": "Custom date for manual entries." } } }, "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" }, "iconPath": { "type": "string", "description": "Path or URL to the icon image for the coupon" } } } } } }, "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." }, "highScoreAmount": { "type": ["number", "null"], "description": "The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign." }, "currentStreak": { "type": ["number", "null"], "description": "The current number of consecutive days the customer has visited the website. This value is applicable only in the context of a streak (daily visit) rewards campaign." }, "highestStreak": { "type": ["number", "null"], "description": "The maximum number of consecutive days the customer has visited the website. This value is also applicable only in the context of a streak (daily visit) rewards campaign." }, "completionPercentage": { "type": "number", "description": "The percentage of the campaign the customer has completed. For example, in a second-order campaign where the customer must make 2 orders, if they have only placed 1 order, the completion percentage will be 50%." }, "achievedCount": { "type": "number", "description": "The number of times the customer has achieved the campaign." }, "canAchieve": { "type": "boolean", "description": "A flag that determines whether the customer is currently eligible to participate in and achieve this reward campaign. It provides a quick indication of the customer's ability to meet the campaign's conditions based on their current status." }, "rewardCampaignConfiguration": { "type": "object", "description": "Comprehensive description of the reward campaign configuration.", "properties": { "id": { "type": "number", "description": "Unique identifier for the reward campaign." }, "name": { "type": "string", "description": "Name of the reward campaign." }, "description": { "type": ["string", "null"], "description": "A brief description of the reward campaign." }, "isRepeatable": { "type": "boolean", "description": "Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer." }, "maxAchievement": { "type": "number", "description": "Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true. If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available." }, "type": { "type": "string", "description": "The type of the campaign. Possible values: SignUp (Reward is given when a user signs up), SocialMedia (Reward is linked to social media activity), ScheduledChallenge (A time-based challenge that gives rewards), Spin The Wheel (Rewards are given based on a spin-the-wheel game), EventBased (Reward is given based on specific customer events), HighScore (Reward is given based on achieving high scores in a campaign), Birthday (Reward is given for birthday-related activity)." }, "visibility": { "type": "string", "description": "The visibility status of the campaign. Possible values: AlwaysVisible (The campaign is always visible on the widget), NotVisible (The campaign is not visible to the customer on the widget), VisibleIfEarned (The campaign becomes visible once the customer earns it on the widget)." }, "icon": { "type": ["string", "null"], "description": "The URL of the campaign's icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform." }, "redirectionButtonText": { "type": ["string", "null"], "description": "The text displayed on the redirection button within the reward campaign page on the widget. Example: \"Claim Your Reward\" would prompt customers to take action." }, "redirectionButtonLink": { "type": ["string", "null"], "description": "The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward redemption process. Example: \"https://yourwebsite.com/rewards\" directs customers to a page where they can view their rewards." }, "widgetDetailsParameter": { "type": ["string", "null"], "description": "This value is used with the openDetails parameter to open the widget for a specific campaign. The value is generated based on the campaign type and campaign ID. You could always use this parameter to trigger the widget on a specific page that you want. This parameter is only required if you are drawing your own UI but still want to display the UI of specific campaigns through the widget. In mobile apps, you can programmatically control the Gameball widget using our SDKs by passing the openDetails parameter with the appropriate value to navigate to different sections. Examples: details_reward_campaign_{reward_campaign_id} (Opens a standard reward campaign), details_wheel_{reward_campaign_id} (Opens a specific wheel campaign), details_scratch_{reward_campaign_id} (Opens a scratch card campaign), details_match_{reward_campaign_id} (Opens a match game campaign)." }, "activation": { "type": ["object", "null"], "properties": { "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: \"2024-11-01T00:00:00\" indicates that the campaign starts on November 1, 2024." }, "endDate": { "type": ["string", "null"], "format": "date-time", "description": "The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign. Example: \"2024-11-30T23:59:59\" indicates that the campaign ends on November 30, 2024, at 11:59 PM." } } }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "rankReward": { "type": "number", "description": "The score rewarded for achieving this reward campaign." }, "walletReward": { "type": "number", "description": "The number of points the customer will earn upon achieving this reward campaign. Example: If you have set up a \"First Order\" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200." }, "walletRewardFactor": { "type": ["number", "null"], "description": "The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers. Example: In a \"Double Points\" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign." }, "couponReward": { "type": ["object", "null"], "properties": { "couponType": { "type": ["string", "null"], "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom." }, "discountValue": { "type": ["number", "null"], "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount." }, "product": { "type": ["object", "null"], "properties": { "productId": { "type": ["string", "null"] }, "productName": { "type": ["string", "null"] }, "variantId": { "type": ["string", "null"] }, "variantName": { "type": ["string", "null"] }, "productDisplayName": { "type": ["string", "null"] } } }, "collections": { "type": ["array", "null"], "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"], "description": "The unique identifier for the collection." }, "collectionName": { "type": ["string", "null"], "description": "The name for the collection." } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"], "description": "A unique identifier used to reference the coupon group in the system." }, "title": { "type": ["string", "null"], "description": "The title of the coupon group." }, "url": { "type": ["string", "null"], "description": "The URL for the coupon group." }, "iconPath": { "type": ["string", "null"], "description": "The path to the icon of the coupon group." }, "description": { "type": ["string", "null"], "description": "A description of the coupon group." }, "maxPerCustomer": { "type": ["number", "null"], "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "description": "The name of the reward rule configured on the dashboard based on required language." }, "expiryAfter": { "type": ["number", "null"], "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount." }, "usageLimit": { "type": ["number", "null"], "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid." }, "capping": { "type": ["number", "null"], "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher." }, "minOrderValue": { "type": ["number", "null"], "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount." }, "codePrefix": { "type": ["string", "null"], "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is \"SUMMER\", the generated coupon codes might look like \"SUMMER12345\" or \"SUMMERDISCOUNT\"." }, "redeemInstructions": { "type": ["string", "null"], "description": "The instructions on how the customer can redeem the coupon. Example: \"Enter the coupon code at checkout to apply the discount.\"" } } } } } } } } } } } } }, "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: Active (The referral was successfully completed. The referred friend has completed the required action (e.g., placing an order), and the referral is counted for the customer), Pending (The referred friend has used the customer's referral link but has not yet completed the required action (e.g., signing up or making a purchase) for the referral to be considered complete)." } } } }, "count": { "type": "number", "description": "The total number of friends on the current page." }, "hasMore": { "type": "boolean", "description": "Indicating whether there are additional friends to be fetched beyond the current page." } } }, "CustomerReferralsCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of friends referred by the customer available in Gameball system." }, "totalPending": { "type": "number", "description": "The total number of referred friends who have joined but not yet completed the referral criteria in the Gameball system." }, "totalActive": { "type": "number", "description": "The total number of referred friends who have successfully completed the referral criteria in the Gameball system." } } }, "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 (e.g., \"Balance Adjustment\", \"Referral\"). Available Activity Types: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer's tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), BalanceAdjustment (Indicates that points were either rewarded or deducted manually from the customer's balance), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign)." }, "activityDay": { "type": "string", "description": "The day of the week when the activity took place (e.g., \"Sunday\")." }, "activityDate": { "type": "string", "description": "The date of the activity (e.g., \"October 20, 2024\")." }, "activityTime": { "type": "string", "description": "The time when the activity occurred (e.g., \"19:27:33\")." }, "customerId": { "type": "string", "description": "The unique identifier of the customer associated with the activity." }, "email": { "type": ["string", "null"], "description": "The email address of the customer." }, "phoneNumber": { "type": ["string", "null"], "description": "The customer's phone number." }, "displayName": { "type": ["string", "null"], "description": "The customer's display name." }, "transactionId": { "type": ["string", "null"], "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. It represents the transaction ID related to this activity, if applicable, such as in cases of cashback rewards, points redemption, or balance adjustments." }, "isManualActivity": { "type": ["boolean", "null"], "description": "Indicates whether the activity was manually triggered (true) or not (false). Example: This will be true if the activity is a BalanceAdjustment, when you manually decide to reward the customer with points." }, "points": { "type": ["number", "null"], "description": "The number of points involved in the activity, such as points earned, redeemed, or adjusted." }, "score": { "type": ["number", "null"], "description": "The score involved in the activity, applicable in reward campaigns where the customer earns score. Example: If the customer participates in a campaign and earns 100 score points, the activity will include the score value." }, "reason": { "type": ["string", "null"], "description": "This is the reason manually entered for the activity, if provided. It is typically used when performing a manual activity, such as rewarding points or rewarding a manual reward campaign for a customer. Example: If you manually reward a customer with 100 points for their birthday, you might enter \"Birthday reward\" as the reason." }, "calculatedRedemption": { "type": ["number", "null"], "description": "The estimated monetary value based on the redemption factor configured by the client and the points involved in this activity. It reflects the potential worth of the points, even if no actual redemption was made." }, "actualRedemption": { "type": ["number", "null"], "description": "The actual monetary value of the redemption, if applicable. This represents the redeemed amount when the activity type is points redemption." }, "familyRedemptionAmount": { "type": ["number", "null"], "description": "The redemption monetary value related to the customer's family wallet, if applicable." }, "familyRedemptionPoints": { "type": ["number", "null"], "description": "The redemption points related to the customer's family wallet, if applicable." }, "paymentRewardAmount": { "type": ["number", "null"], "description": "The amount rewarded in currency from the payment reward. This value reflects the cashback reward provided to the customer. Example: If a customer receives a cashback reward of $10, the paymentRewardAmount will be 10." }, "outstandingPoints": { "type": ["number", "null"], "description": "The number of points currently available from the transaction related to this activity. Example: If a customer earned 100 points from a transaction and 20 points have since expired, the outstandingPoints would be 80, representing the points still available for the customer to use." }, "rewardThreshold": { "type": ["number", "null"], "description": "This represents the minimum monetary amount (X value) a customer needs to spend to receive a specific number of reward points (Y points) as cashback reward, based on the configured points settings. It defines the threshold of spending required to earn points in your loyalty program. Example: If rewardThreshold is set to 50.0, it means for every 50 currency units (e.g., 50 USD) spent by the customer, they will earn the configured number of reward points." }, "currency": { "type": ["string", "null"], "description": "The currency used in the transaction (e.g., \"EGP\")." }, "redemptionRewardFactor": { "type": ["number", "null"], "description": "The factor used to calculate how many points are required for a redemption. This value determines the conversion rate between points and monetary value during a redemption process. Example: If the redemptionRewardFactor is 0.1, then for every 10 points, the customer can redeem 1 unit of currency." }, "campaignName": { "type": ["string", "null"], "description": "The name of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded." }, "campaignStartDate": { "type": ["string", "null"], "description": "The start date of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded." }, "campaignEndDate": { "type": ["string", "null"], "description": "The end date of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded." }, "campaignEnabled": { "type": ["boolean", "null"], "description": "Indicates if the associated campaign was enabled during the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded." }, "tierName": { "type": ["string", "null"], "description": "The tier name of the customer during the activity. The name of the tier associated with the activity. This is relevant when the activity involves a tier-related event, such as: TierUpgraded, TierDowngraded, TierMigration. Example: if a customer moves from \"Silver\" to \"Gold\" in the TierUpgraded activity, \"Gold\" will be displayed as the associated tier name." }, "rewardPoints": { "type": ["number", "null"], "description": "The number of points rewarded from the activity." }, "rewardFactor": { "type": ["number", "null"], "description": "The reward factor used in the calculation of reward points." }, "isGuest": { "type": ["boolean", "null"], "description": "A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default." }, "couponUsed": { "type": ["boolean", "null"], "description": "Indicates whether the coupon associated with this activity was used or not. This is a boolean value, where true means the coupon was used during the activity, and false means it was not. Example: true if the coupon was successfully applied, false if the coupon was associated with the event but was not used." }, "couponType": { "type": ["string", "null"], "description": "Represents the type of coupon associated with the activity. Example: \"percentage_discount\", \"free_shipping\", \"fixed_rate_discount\"." }, "couponCode": { "type": ["string", "null"], "description": "The code of the coupon that was associated with this activity. This is the actual coupon code that was available for use during the activity. Example: \"SUMMER20\"." }, "couponGroup": { "type": ["string", "null"], "description": "Represents the group or campaign to which the coupon is linked. This could be a marketing campaign, product category, or customer segment. Example: \"Holiday Campaign\", \"VIP Customer Group\", \"Black Friday Sale\"." }, "couponProduct": { "type": ["string", "null"], "description": "The name of the product associated with the coupon, if the coupon was tied to a specific product. Example: \"Wireless Earbuds\"." }, "couponProductId": { "type": ["number", "null"], "description": "The unique ID of the product associated with the coupon. This ID helps track which specific product was related to the coupon. Example: 123456 for \"Wireless Earbuds\"." }, "productVariantName": { "type": ["string", "null"], "description": "The name of the product variant involved in the event. This would apply if the coupon or activity was specific to a certain variant of a product, such as size or color. Example: \"Wireless Earbuds - Black\", \"T-shirt - Large\"." } } } }, "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" }, "steps": { "type": ["array", "null"], "description": "List of steps involved in completing the automation.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of step, for example rewarding a badge or adding points." }, "order": { "type": "number", "description": "The order of this step within the automation sequence." }, "completed": { "type": "boolean", "description": "Whether this step has been completed or not." }, "configuration": { "type": ["object", "null"], "description": "Configuration details for the step, such as badge name & icon.", "additionalProperties": true } } } }, "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" } } }, "CustomerDailyStreakProgressResponse": { "type": "object", "properties": { "currentStreakCount": { "type": "number", "description": "Number of consecutive periods completed in the current active streak" }, "highestStreakCount": { "type": "number", "description": "Highest streak count ever reached by this customer for this campaign" }, "totalRewardsEarned": { "type": "number", "description": "Total streak rewards earned across all time" }, "ongoingReward": { "type": "object", "description": "Details of the currently active reward tier", "properties": { "name": { "type": "string", "description": "Reward name as configured in the client language settings" }, "type": { "type": "string", "description": "Reward type: points or coupon" }, "value": { "type": "string", "description": "Reward value (points amount or coupon description)" } } }, "nextMilestone": { "type": "number", "nullable": true, "description": "Streak count at which the next reward unlocks, or null if at the last tier" }, "lastActivityDate": { "type": "string", "format": "date-time", "description": "Date/time of the last qualifying action in the client's local timezone" }, "campaignEndDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Campaign end date in the client's local timezone, or null if open-ended" }, "badges": { "type": "array", "description": "Badge milestones ordered by milestoneDay ascending", "items": { "type": "object", "properties": { "milestoneDay": { "type": "number", "description": "Streak day at which this badge is awarded" }, "name": { "type": "string", "description": "Badge name" }, "imageUrl": { "type": "string", "description": "Badge image URL" }, "earned": { "type": "boolean", "description": "Whether this customer has earned this badge" }, "earnedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Date earned, or null if not yet earned" } } } } } }, "CustomerTagsUpdateRequest": { "type": "object", "required": ["tags"], "properties": { "tags": { "type": "string", "description": "A comma-separated list of tags to apply or remove (e.g., 'gamer, highSpender')." } } }, "CustomerNotificationsCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of notifications available for the customer in Gameball system" } } }, "RewardCampaignConfiguration": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier for the reward campaign." }, "name": { "type": "string", "description": "Name of the reward campaign." }, "description": { "type": ["string", "null"], "description": "A brief description of the reward campaign." }, "isRepeatable": { "type": "boolean", "description": "Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer." }, "maxAchievement": { "type": "number", "description": "Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true. If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available." }, "type": { "type": "string", "description": "The type of the campaign. Possible values: SignUp (Reward is given when a user signs up), SocialMedia (Reward is linked to social media activity), ScheduledChallenge (A time-based challenge that gives rewards), Spin The Wheel (Rewards are given based on a spin-the-wheel game), EventBased (Reward is given based on specific customer events), HighScore (Reward is given based on achieving high scores in a campaign), Birthday (Reward is given for birthday-related activity)." }, "visibility": { "type": "string", "description": "The visibility status of the campaign. Possible values: AlwaysVisible (The campaign is always visible on the widget), NotVisible (The campaign is not visible to the customer on the widget), VisibleIfEarned (The campaign becomes visible once the customer earns it on the widget)." }, "icon": { "type": ["string", "null"], "description": "The URL of the campaign's icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform." }, "availability": { "type": "object", "description": "Defines the criteria determining which customers are eligible to earn this reward campaign.", "properties": { "minTier": { "type": "number", "description": "The minimum customer tier order required to achieve in the campaign. Customers must meet or exceed this tier to be eligible. Example: A value of 2 indicates that only customers in the tier with order 2 or higher can earn this campaign." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "A list of tags that identify the target customers eligible for the campaign. Tags can be used to group customers based on specific attributes or behaviors. Example: [\"loyal\", \"new_customer\"] indicates that only customers tagged as \"loyal\" or \"new_customer\" are eligible for the campaign." } } }, "redirectionButtonText": { "type": ["string", "null"], "description": "The text displayed on the redirection button within the reward campaign page on the widget. Example: \"Claim Your Reward\" would prompt customers to take action." }, "redirectionButtonLink": { "type": ["string", "null"], "description": "The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward campaign achievement. Example: \"https://yourwebsite.com/rewards\" directs customers to a page where they can view their rewards." }, "activation": { "type": ["object", "null"], "description": "Defines the activation criteria for the campaign, which may include specific start and end dates.", "properties": { "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: \"2024-11-01T00:00:00\" indicates that the campaign starts on November 1, 2024." }, "endDate": { "type": ["string", "null"], "format": "date-time", "description": "The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign. Example: \"2024-11-30T23:59:59\" indicates that the campaign ends on November 30, 2024, at 11:59 PM." } } }, "rewards": { "type": "array", "description": "Details of the rewards that the customer will earn once achieving this reward campaign.", "items": { "type": "object", "properties": { "rankReward": { "type": "number", "description": "The score rewarded for achieving this reward campaign." }, "walletReward": { "type": "number", "description": "The number of points the customer will earn upon achieving this reward campaign. Example: If you have set up a \"First Order\" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200." }, "walletRewardFactor": { "type": ["number", "null"], "description": "The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers. Example: In a \"Double Points\" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign." }, "couponReward": { "type": ["object", "null"], "description": "A coupon object that is awarded to the customer for this reward campaign.", "properties": { "couponType": { "type": ["string", "null"], "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom." }, "discountValue": { "type": ["number", "null"], "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount." }, "product": { "type": ["object", "null"], "properties": { "productId": { "type": ["string", "null"], "description": "The unique identifier for the product." }, "productName": { "type": ["string", "null"], "description": "The name of the product." }, "variantId": { "type": ["string", "null"], "description": "The unique identifier for the product variant." }, "variantName": { "type": ["string", "null"], "description": "The name of the product variant." }, "productDisplayName": { "type": ["string", "null"], "description": "The display name associated with the product that configured on the dashboard based on required language." } } }, "collections": { "type": ["array", "null"], "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"], "description": "The unique identifier for the collection." }, "collectionName": { "type": ["string", "null"], "description": "The name for the collection." } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"], "description": "A unique identifier used to reference the coupon group in the system." }, "title": { "type": ["string", "null"], "description": "The title of the coupon group." }, "url": { "type": ["string", "null"], "description": "The URL for the coupon group." }, "iconPath": { "type": ["string", "null"], "description": "The path to the icon of the coupon group." }, "description": { "type": ["string", "null"], "description": "A description of the coupon group." }, "maxPerCustomer": { "type": ["number", "null"], "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "description": "The name of the reward rule configured on the dashboard based on required language." }, "expiryAfter": { "type": ["number", "null"], "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount." }, "usageLimit": { "type": ["number", "null"], "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid." }, "capping": { "type": ["number", "null"], "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher." }, "minOrderValue": { "type": ["number", "null"], "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount." }, "codePrefix": { "type": ["string", "null"], "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is \"SUMMER\", the generated coupon codes might look like \"SUMMER12345\" or \"SUMMERDISCOUNT\"." }, "redeemInstructions": { "type": ["string", "null"], "description": "The instructions on how the customer can redeem the coupon. Example: \"Enter the coupon code at checkout to apply the discount.\"" } } } } } } } } } }, "TierConfiguration": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tier." }, "minProgress": { "type": "number", "description": "The minimum amount of progress a customer needs to reach this tier in the program. This represents the threshold that must be met for a customer to reach this tier. Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to reach this tier. Possible Values: Total amount spent, Total points earned, Friends referred, Orders completed, Score. Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier." }, "order": { "type": "number", "description": "This represents the numerical order of a tier. Higher numbers indicate higher tiers." }, "icon": { "type": "string", "description": "The URL for the icon associated with the tier. You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles." }, "benefits": { "type": "array", "description": "It contains a list of rewards associated with the tier, each offering specific advantages to the customer. This array includes various types of benefits.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Indicates the type of benefit the customer will receive. The possible values are: Custom Benefits (Offers tailored and custom rewards to offer customization for specific customer preferences or behaviors), Lifetime Reward (A benefit that can be used once at any time during the customer's lifetime with Gameball, as long as they remain in this tier), Loyalty Points Earning Custom Configuration (Enables customized settings for how customers earn loyalty points based on their spending amount), Entry Reward (A one-time reward granted to customers upon joining this tier)." }, "description": { "type": ["string", "null"], "description": "Description of the custom benefit." }, "hyperLink": { "type": ["string", "null"], "description": "Hyperlink associated with the custom benefit." }, "rankReward": { "type": "number", "description": "The score rewarded for the customer as a reward." }, "walletReward": { "type": "number", "description": "The number of points the customer will earn for this reward." }, "walletRewardFactor": { "type": ["number", "null"], "description": "This is a multiplier factor that indicates how the customer on their tier will be rewarded for each unit of currency they spend. This is returned for the benefits of type Loyalty Points Earning Custom Configuration. Example: If a tier has a walletRewardFactor of 2, it means any customer on this tier will earn 2 loyalty points for every $1 they spend. Therefore, if the customer spends $100, they would receive 200 loyalty points as a reward." }, "couponReward": { "type": ["object", "null"], "description": "A coupon object that is awarded to the customer.", "properties": { "couponType": { "type": ["string", "null"], "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom." }, "discountValue": { "type": ["number", "null"], "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount." }, "product": { "type": ["object", "null"], "properties": { "productId": { "type": ["string", "null"], "description": "The unique identifier for the product." }, "productName": { "type": ["string", "null"], "description": "The name of the product." }, "variantId": { "type": ["string", "null"], "description": "The unique identifier for the product variant." }, "variantName": { "type": ["string", "null"], "description": "The name of the product variant." }, "productDisplayName": { "type": ["string", "null"], "description": "The display name associated with the product that configured on the dashboard based on required language." } } }, "collections": { "type": ["array", "null"], "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"], "description": "The unique identifier for the collection." }, "collectionName": { "type": ["string", "null"], "description": "The name for the collection." } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"], "description": "A unique identifier used to reference the coupon group in the system." }, "title": { "type": ["string", "null"], "description": "The title of the coupon group." }, "url": { "type": ["string", "null"], "description": "The URL for the coupon group." }, "iconPath": { "type": ["string", "null"], "description": "The path to the icon of the coupon group." }, "description": { "type": ["string", "null"], "description": "A description of the coupon group." }, "maxPerCustomer": { "type": ["number", "null"], "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "description": "The name of the reward rule configured on the dashboard based on required language." }, "expiryAfter": { "type": ["number", "null"], "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount." }, "usageLimit": { "type": ["number", "null"], "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid." }, "capping": { "type": ["number", "null"], "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher." }, "minOrderValue": { "type": ["number", "null"], "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount." }, "codePrefix": { "type": ["string", "null"], "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is \"SUMMER\", the generated coupon codes might look like \"SUMMER12345\" or \"SUMMERDISCOUNT\"." }, "redeemInstructions": { "type": ["string", "null"], "description": "The instructions on how the customer can redeem the coupon. Example: \"Enter the coupon code at checkout to apply the discount.\"" } } } } } } } } } }, "ReferralConfiguration": { "type": "object", "properties": { "referralMethod": { "type": "string", "description": "This specifies who will receive the referral reward when a successful referral is made. Possible values: CustomerOnly (Only the customer making the referral will receive the reward. The referred friend will not receive any reward), CustomerAndFriend (Both the customer making the referral and the referred friend will receive rewards, encouraging mutual benefit)." }, "eventName": { "type": "string", "description": "This describes the event that will trigger the referral reward. Example: if the eventName is set to place_order, the referral reward will be granted when the referred friend completes an order after using the referral link. Other events can also be configured to trigger the reward, depending on your system's setup." }, "eventMetaData": { "type": ["object", "null"], "description": "Contains additional metadata about the event that triggers the referral.", "properties": { "name": { "type": ["string", "null"], "description": "The name of the event metadata." }, "operator": { "type": ["string", "null"], "description": "The operator used for event metadata (e.g., equals, greater_than)." }, "value": { "type": ["string", "null"], "description": "The value associated with the event metadata." } } }, "friendReward": { "type": ["object", "null"], "description": "The reward details given to the referred friend as part of the referral program.", "properties": { "score": { "type": ["number", "null"], "description": "The score awarded to the referred friend." }, "point": { "type": ["number", "null"], "description": "The points awarded to the referred friend." }, "coupon": { "type": ["object", "null"], "description": "A coupon object that is awarded to the referred friend.", "properties": { "couponType": { "type": ["string", "null"], "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom." }, "discountValue": { "type": ["number", "null"], "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount." }, "product": { "type": ["object", "null"], "properties": { "productId": { "type": ["string", "null"], "description": "The unique identifier for the product." }, "productName": { "type": ["string", "null"], "description": "The name of the product." }, "variantId": { "type": ["string", "null"], "description": "The unique identifier for the product variant." }, "variantName": { "type": ["string", "null"], "description": "The name of the product variant." }, "productDisplayName": { "type": ["string", "null"], "description": "The display name associated with the product that configured on the dashboard based on required language." } } }, "collections": { "type": ["array", "null"], "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"], "description": "The unique identifier for the collection." }, "collectionName": { "type": ["string", "null"], "description": "The name for the collection." } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"], "description": "A unique identifier used to reference the coupon group in the system." }, "title": { "type": ["string", "null"], "description": "The title of the coupon group." }, "url": { "type": ["string", "null"], "description": "The URL for the coupon group." }, "iconPath": { "type": ["string", "null"], "description": "The path to the icon of the coupon group." }, "description": { "type": ["string", "null"], "description": "A description of the coupon group." }, "maxPerCustomer": { "type": ["number", "null"], "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "description": "The name of the reward rule configured on the dashboard based on required language." }, "expiryAfter": { "type": ["number", "null"], "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount." }, "usageLimit": { "type": ["number", "null"], "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid." }, "capping": { "type": ["number", "null"], "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher." }, "minOrderValue": { "type": ["number", "null"], "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount." }, "codePrefix": { "type": ["string", "null"], "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is \"SUMMER\", the generated coupon codes might look like \"SUMMER12345\" or \"SUMMERDISCOUNT\"." }, "redeemInstructions": { "type": ["string", "null"], "description": "The instructions on how the customer can redeem the coupon. Example: \"Enter the coupon code at checkout to apply the discount.\"" } } } } } } }, "customerReward": { "type": ["object", "null"], "description": "The reward details given to the customer as part of the referral program.", "properties": { "score": { "type": ["number", "null"], "description": "The score awarded to the customer." }, "point": { "type": ["number", "null"], "description": "The points awarded to the customer." }, "coupon": { "type": ["object", "null"], "description": "A coupon object that is awarded to the customer.", "properties": { "couponType": { "type": ["string", "null"], "description": "The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom." }, "discountValue": { "type": ["number", "null"], "description": "The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount." }, "product": { "type": ["object", "null"], "properties": { "productId": { "type": ["string", "null"], "description": "The unique identifier for the product." }, "productName": { "type": ["string", "null"], "description": "The name of the product." }, "variantId": { "type": ["string", "null"], "description": "The unique identifier for the product variant." }, "variantName": { "type": ["string", "null"], "description": "The name of the product variant." }, "productDisplayName": { "type": ["string", "null"], "description": "The display name associated with the product that configured on the dashboard based on required language." } } }, "collections": { "type": ["array", "null"], "description": "A list of collection IDs that the coupon can be applied to.", "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"], "description": "The unique identifier for the collection." }, "collectionName": { "type": ["string", "null"], "description": "The name for the collection." } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"], "description": "A unique identifier used to reference the coupon group in the system." }, "title": { "type": ["string", "null"], "description": "The title of the coupon group." }, "url": { "type": ["string", "null"], "description": "The URL for the coupon group." }, "iconPath": { "type": ["string", "null"], "description": "The path to the icon of the coupon group." }, "description": { "type": ["string", "null"], "description": "A description of the coupon group." }, "maxPerCustomer": { "type": ["number", "null"], "description": "The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times." }, "startDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will become active and valid for redemption." }, "expiryDate": { "type": ["string", "null"], "format": "date-time", "description": "The date when the coupons within this coupon group will expire and no longer be valid for redemption." }, "isAvailable": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently available." }, "isActive": { "type": ["boolean", "null"], "description": "Indicates whether the coupon group is currently active." } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "description": "The name of the reward rule configured on the dashboard based on required language." }, "expiryAfter": { "type": ["number", "null"], "description": "The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount." }, "usageLimit": { "type": ["number", "null"], "description": "The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid." }, "capping": { "type": ["number", "null"], "description": "The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher." }, "minOrderValue": { "type": ["number", "null"], "description": "The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount." }, "codePrefix": { "type": ["string", "null"], "description": "The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is \"SUMMER\", the generated coupon codes might look like \"SUMMER12345\" or \"SUMMERDISCOUNT\"." }, "redeemInstructions": { "type": ["string", "null"], "description": "The instructions on how the customer can redeem the coupon. Example: \"Enter the coupon code at checkout to apply the discount.\"" } } } } }, "extraReward": { "type": ["object", "null"], "description": "It contains all the details of the reward (like the friendReward Object) that will be awarded to the customer as a bonus on top of the regular reward for every X friend referred.", "properties": { "forEvery": { "type": ["number", "null"], "description": "This defines the number of friends a customer needs to refer in order to earn the extraReward. For example, if the value of forEvery is set to 5, the customer will receive the extra reward for every 5 friends they successfully refer. This acts as a bonus on top of the regular reward, incentivizing more referrals." }, "score": { "type": ["number", "null"], "description": "The score awarded as part of the extra reward." }, "point": { "type": ["number", "null"], "description": "The points awarded as part of the extra reward." }, "coupon": { "type": ["object", "null"], "description": "A coupon object that is awarded as part of the extra reward." } } } } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "apikey" }, "secretKey": { "type": "apiKey", "in": "header", "name": "secretkey" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }