{ "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/{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/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).", "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 } } } } } }, "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 } } } } } } } } }, "/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).", "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).", "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).", "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).", "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", "transactionTime", "username", "reason", "points"], "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).", "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 (should be positive for rewards and negative for deductions).", "example": 50 }, "amount": { "type": "number", "description": "The monetary value (in system currency) associated with the transaction.", "example": 0 } } } } } }, "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 } } } } } } } } }, "/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).", "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": { "post": { "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": "Validate a single coupon and optionally lock it for exclusive use.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "lock": { "type": "boolean" }, "pin": { "type": "string" } } } } } }, "responses": { "200": { "description": "Coupon validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "isValid": { "type": "boolean" }, "lockReference": { "type": "string" }, "discountAmount": { "type": "number" }, "discountType": { "type": "string" } } } } } } } } }, "/api/v4.0/integrations/coupons/validate": { "post": { "description": "Validate multiple coupons at once and optionally lock them for exclusive use.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId", "coupons"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "coupons": { "type": "array", "items": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" }, "pin": { "type": "string" } } } }, "lock": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Coupons validated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "validCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "lockReference": { "type": "string" }, "discountAmount": { "type": "number" }, "discountType": { "type": "string" } } } }, "invalidCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" } } } } } } } } } } } }, "/api/v4.0/integrations/coupons/{code}/burn": { "post": { "description": "Mark a coupon as used/consumed to prevent further usage.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["customerId"], "properties": { "customerId": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "lockReference": { "type": "string" }, "pin": { "type": "string" } } } } } }, "responses": { "200": { "description": "Coupon burned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "burnedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/v4.0/integrations/coupons/{lockReference}": { "get": { "description": "Retrieve details of locked coupons using the lock reference.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "lockReference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lock details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "lockReference": { "type": "string" }, "customerId": { "type": "string" }, "lockedCoupons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "lockedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "delete": { "description": "Release locked coupons to make them available for use again.", "security": [ { "apiKey": [], "secretKey": [] } ], "parameters": [ { "name": "lockReference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coupons released successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "releasedAt": { "type": "string", "format": "date-time" }, "releasedCoupons": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/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": { "description": "Retrieve active campaigns configuration for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Campaigns retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "isActive": { "type": "boolean" }, "rewardType": { "type": "string" } } } } } } } } } } } }, "/api/v4.0/integrations/configurations/tiers": { "get": { "description": "Retrieve VIP tier configurations for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "VIP tiers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "minimumPoints": { "type": "number" }, "benefits": { "type": "array", "items": { "type": "string" } }, "color": { "type": "string" }, "isActive": { "type": "boolean" } } } } } } } } } } } }, "/api/v4.0/integrations/configurations/referrals": { "get": { "description": "Retrieve referral program configuration for the loyalty program.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Referral settings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "referrerReward": { "type": "number" }, "refereeReward": { "type": "number" }, "minimumReferrals": { "type": "number" }, "referralCodeLength": { "type": "number" }, "expirationDays": { "type": "number" } } } } } } } } }, "/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." }, "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." }, "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." }, "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.", "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. **Refund** - Captured when points redeemed from a refunded order are returned to the customer. **Redemption** - Recorded whenever a customer redeems their points for rewards. **Expiry** - Captured when a customer's points expire, indicating a reduction in their total points. **Cancel** - Recorded when a customer cancels an order, leading to the deduction of rewarded points. **Migration** - Captured during updates or migrations of customer data via a CSV file, reflecting added or deducted points. **ManualAccumulation** - Recorded for points that are manually added to a customer's balance. **DiscountCode** - Captured when a customer creates a coupon code. **ManualDeduction** - Recorded for points manually removed from a customer's balance. **ManualReward** - Similar to AchievementReward, but specifically for manually awarding achievements to a customer.", "enum": ["AchievementReward", "PaymentReward", "Refund", "Redemption", "Expiry", "Cancel", "Migration", "ManualAccumulation", "DiscountCode", "ManualDeduction", "ManualReward"], "example": "PaymentReward" }, "amount": { "type": "number", "description": "The monetary value involved in the transaction.", "example": 250.75 }, "transactionId": { "type": "string", "description": "A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.", "example": "ORD12345" }, "equivalentPoints": { "type": "number", "description": "The points equivalent to the monetary value of the transaction.", "example": 192.0 } } } }, "count": { "type": "integer", "description": "Total number of transactions associated with the order.", "example": 1 } } } } } } } }, "delete": { "description": "Delete a customer by customerId.", "security": [ { "apiKey": [], "secretKey": [] } ], "x-codeSamples": [ { "lang": "C#", "label": "C#", "source": "using System.Net.Http;\nusing System.Threading.Tasks;\n\nvar client = new HttpClient();\nclient.BaseAddress = new System.Uri(\"https://api.gameball.co\");\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar request = new HttpRequestMessage(HttpMethod.Delete, \"/api/v4.0/integrations/customers/12345\");\nvar response = await client.SendAsync(request);\nresponse.EnsureSuccessStatusCode();" } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique customer identifier" } ], "responses": { } } }, "/api/v4.0/integrations/customers/{customerId}/balance": { "get": { "summary": "Get Customer Balance", "description": "Retrieve customer loyalty progress including tier, points balance, and referrals.", "operationId": "getCustomerBalance", "security": [ { "apiKey": [] }, { "secretKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Unique identifier for the customer", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" } ], "responses": { "200": { "description": "Customer progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBalanceResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/tier-progress": { "get": { "description": "Retrieve customer loyalty progress including tier, points balance, and referrals.", "security": [ { "apiKey": [], "secretKey": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://api.gameball.co/api/v4.0/integrations/customers/12345/progress' -H 'apikey: YOUR_API_KEY' -H 'secretkey: YOUR_SECRET_KEY'" }, { "lang": "javascript", "label": "JavaScript", "source": "const res = await fetch('https://api.gameball.co/api/v4.0/integrations/customers/12345/progress', { headers: { apikey: 'YOUR_API_KEY', secretkey: 'YOUR_SECRET_KEY' } }); const data = await res.json();" }, { "lang": "python", "label": "Python", "source": "import requests\nresp = requests.get('https://api.gameball.co/api/v4.0/integrations/customers/12345/progress', headers={'apikey':'YOUR_API_KEY','secretkey':'YOUR_SECRET_KEY'})\nprint(resp.json())" }, { "lang": "csharp", "label": "C#", "source": "using System.Net.Http;\nvar client = new HttpClient();\nclient.DefaultRequestHeaders.Add(\"apikey\", \"YOUR_API_KEY\");\nclient.DefaultRequestHeaders.Add(\"secretkey\", \"YOUR_SECRET_KEY\");\nvar response = await client.GetAsync(\"https://api.gameball.co/api/v4.0/integrations/customers/12345/progress\");\nresponse.EnsureSuccessStatusCode();" }, { "lang": "php", "label": "PHP", "source": " ['apikey: YOUR_API_KEY','secretkey: YOUR_SECRET_KEY'], CURLOPT_RETURNTRANSFER => true]);\\n$resp = curl_exec($ch);\\n?>" } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique customer identifier" }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated expansions: tier,referrals" } ], "responses": { "200": { "description": "Customer tier progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerTierProgressResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress": { "get": { "summary": "Get Customer Campaigns Progress", "description": "Retrieve customer's progress within Gameball's reward campaigns, providing insights into achievements and current status in each campaign.", "operationId": "getCustomerCampaignsProgress", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer campaigns progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCampaignsProgressResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals": { "get": { "summary": "Get Customer Referrals", "description": "Retrieve a list of customers referred by a specified customer, including each referral's join date and current status.", "operationId": "getCustomerReferrals", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which Gameball customer id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Number of referrals to return per page" } ], "responses": { "200": { "description": "Customer referrals found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/referrals/count": { "get": { "summary": "Get Customer Referrals Count", "description": "Retrieve the total count of customers referred by a specified customer, providing the number of completed and pending referrals.", "operationId": "getCustomerReferralsCount", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" } ], "responses": { "200": { "description": "Customer referrals count found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferralsCountResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/activities": { "get": { "summary": "Get Customer Activities", "description": "Retrieve a log of customer activities within Gameball, including tier changes, campaign rewards, referrals, redemptions, and more.", "operationId": "getCustomerActivities", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "startAfter", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "description": "Specifies the page will start after which activity id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Number of activities to return per page" }, { "name": "activityType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["TierUpgraded", "TierDowngraded", "TierMigration", "CampaignRewarded", "SuccessfulAction", "Referral", "Referred", "ReferralBonusReward", "PaymentReward", "Refund", "Redemption", "Cancel", "Expiry", "Migration", "Lifetime", "Automation"] }, "description": "Filter activities by specific type" } ], "responses": { "200": { "description": "Customer activities found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/activities/count": { "get": { "summary": "Get Customer Activities Count", "description": "Retrieve the total count of customer activities within Gameball, with optional filtering by activity type.", "operationId": "getCustomerActivitiesCount", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "activityType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["TierUpgraded", "TierDowngraded", "TierMigration", "CampaignRewarded", "SuccessfulAction", "Referral", "Referred", "ReferralBonusReward", "PaymentReward", "Refund", "Redemption", "Cancel", "Expiry", "Migration", "Lifetime", "Automation"] }, "description": "Filter activities by specific type" } ], "responses": { "200": { "description": "Customer activities count found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActivitiesCountResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/automation": { "get": { "summary": "Get Customer Automation Campaigns", "description": "Retrieve available automation campaigns for the customer, including onboarding journeys, engagement triggers, or milestone-based campaigns.", "operationId": "getCustomerAutomationCampaigns", "security": [{ "apiKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "campaignType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mission", "all"], "default": "mission" }, "description": "Filter automation steps by specific type" } ], "responses": { "200": { "description": "Customer automation campaigns found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAutomationCampaignsResponse" } } } } } } }, "/api/v4.0/integrations/customers/{customerId}/action-streak/{challengeId}": { "get": { "summary": "Get Customer Action Streak Progress", "description": "Retrieve the progress of a specific customer within a particular Action Streak challenge.", "operationId": "getCustomerActionStreakProgress", "security": [{ "apiKey": [], "secretKey": [] }], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the customer" }, { "name": "challengeId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Unique identifier of the Action Streak challenge" } ], "responses": { "200": { "description": "Customer action streak progress found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionStreakProgressResponse" } } } } } } }, "/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": { "name": { "type": "string" }, "code": { "type": "string" }, "value": { "type": "number" }, "type": { "type": "string" }, "target": { "type": "string" }, "currency": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "expiryDate": { "type": "string", "format": "date-time" }, "isExpired": { "type": "boolean" }, "isActive": { "type": "boolean" } } }, "CustomerCoupons": { "type": "object", "properties": { "coupons": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } } } }, "CustomerHash": { "type": "object", "properties": { "hash": { "type": "string" } } }, "ReferralValidation": { "type": "object", "properties": { "isValid": { "type": "boolean" } } }, "CustomerProgress": { "type": "object", "properties": { "customerId": { "type": "string" }, "pointsBalance": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "rank": { "type": "integer" } } }, "referrals": { "type": "object", "properties": { "total": { "type": "integer" }, "successful": { "type": "integer" } } } } }, "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": "Points currently active and available for use (excludes pending)." }, "availablePointsValue": { "type": "number", "description": "Monetary value of currently available points (excludes pending)." }, "pendingPoints": { "type": "number", "description": "Points earned but on hold during the return window." }, "pendingPointsValue": { "type": "number", "description": "Monetary value of the pending points." }, "currency": { "type": "string", "description": "Currency code used for point value calculations." }, "pointsName": { "type": "string", "description": "Display name of points in the loyalty program (e.g., 'Stars')." }, "nextExpiringPointsAmount": { "type": "number", "description": "Amount of points that will expire next." }, "nextExpiringPointsValue": { "type": "number", "description": "Monetary value of the points that will expire next." }, "nextExpiringPointsDate": { "type": "string", "description": "Date when the next set of points will expire." }, "totalEarnedPoints": { "type": "number", "description": "Total number of points earned over the customer's lifetime." } } }, "TierState": { "type": "object", "properties": { "order": { "type": "number", "description": "Numerical order of the tier. Higher is higher tier." }, "name": { "type": "string", "description": "Name of the tier." }, "minProgress": { "type": "number", "description": "Minimum progress required to reach this tier." }, "icon": { "type": "string", "description": "URL of the tier icon." } } }, "CustomerTierProgressResponse": { "type": "object", "properties": { "current": { "$ref": "#/components/schemas/TierState" }, "next": { "$ref": "#/components/schemas/TierState" }, "progress": { "type": "number", "description": "Current progress toward the next tier based on the configured method." } } }, "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" } } } } } }, "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": "Highest score achieved (High Score campaigns only)." }, "currentStreak": { "type": ["number", "null"], "description": "Current consecutive daily visits (Streak campaigns only)." }, "highestStreak": { "type": ["number", "null"], "description": "Max consecutive daily visits (Streak campaigns only)." }, "completionPercentage": { "type": "number", "description": "Percentage of the campaign completed by the customer." }, "achievedCount": { "type": "number", "description": "Number of times the customer has achieved the campaign." }, "canAchieve": { "type": "boolean", "description": "Whether the customer is currently eligible to participate in the campaign." }, "rewardCampaignConfiguration": { "type": "object", "description": "Comprehensive description of the reward campaign configuration.", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "isRepeatable": { "type": "boolean" }, "maxAchievement": { "type": "number", "description": "-1 means unlimited." }, "type": { "type": "string", "description": "Campaign type (e.g., SignUp, SocialMedia, ScheduledChallenge, Spin The Wheel, EventBased, HighScore, Birthday)." }, "visibility": { "type": "string", "description": "Visibility on widget (AlwaysVisible, NotVisible, VisibleIfEarned)." }, "icon": { "type": ["string", "null"] }, "redirectionButtonText": { "type": ["string", "null"] }, "redirectionButtonLink": { "type": ["string", "null"] }, "widgetDetailsParameter": { "type": ["string", "null"], "description": "Use with openDetails to open widget on specific campaign." }, "activation": { "type": ["object", "null"], "properties": { "startDate": { "type": ["string", "null"], "format": "date-time" }, "endDate": { "type": ["string", "null"], "format": "date-time" } } }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "rankReward": { "type": "number" }, "walletReward": { "type": "number" }, "walletRewardFactor": { "type": ["number", "null"] }, "couponReward": { "type": ["object", "null"], "properties": { "couponType": { "type": ["string", "null"], "description": "free_shipping | percentage_discount | fixed_discount | fixed_rate_discount | free_product | custom" }, "discountValue": { "type": ["number", "null"] }, "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"], "items": { "type": "object", "properties": { "collectionId": { "type": ["string", "null"] }, "collectionName": { "type": ["string", "null"] } } } }, "group": { "type": ["object", "null"], "properties": { "handle": { "type": ["string", "null"] }, "title": { "type": ["string", "null"] }, "url": { "type": ["string", "null"] }, "iconPath": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "maxPerCustomer": { "type": ["number", "null"] }, "startDate": { "type": ["string", "null"], "format": "date-time" }, "expiryDate": { "type": ["string", "null"], "format": "date-time" }, "isAvailable": { "type": ["boolean", "null"] }, "isActive": { "type": ["boolean", "null"] } } }, "options": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"] }, "expiryAfter": { "type": ["number", "null"] }, "usageLimit": { "type": ["number", "null"] }, "capping": { "type": ["number", "null"] }, "minOrderValue": { "type": ["number", "null"] }, "codePrefix": { "type": ["string", "null"] }, "redeemInstructions": { "type": ["string", "null"] } } } } } } } } } } } } }, "CustomerReferralsResponse": { "type": "object", "properties": { "referredFriends": { "type": "array", "description": "A list of friends referred by the customer", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Unique identifier for the referred friend" }, "displayName": { "type": "string", "description": "Display name of the referred friend" }, "email": { "type": "string", "description": "Email address of the referred friend" }, "mobileNumber": { "type": "string", "description": "Mobile number of the referred friend" }, "joinDate": { "type": "string", "description": "The date when the referred friend joined" }, "status": { "type": "string", "enum": ["Active", "Pending"], "description": "The current status of the referral" } } } }, "count": { "type": "number", "description": "The total number of friends on the current page" }, "hasMore": { "type": "boolean", "description": "Whether there are additional friends to be fetched" } } }, "CustomerReferralsCountResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "The total number of friends referred by the customer" }, "totalPending": { "type": "number", "description": "The total number of referred friends who have joined but not yet completed the referral criteria" }, "totalActive": { "type": "number", "description": "The total number of referred friends who have successfully completed the referral criteria" } } }, "CustomerActivitiesResponse": { "type": "object", "properties": { "activities": { "type": "array", "description": "An array of activity records for the customer", "items": { "type": "object", "properties": { "activityId": { "type": "number", "description": "Unique identifier for the activity" }, "activityType": { "type": "string", "description": "The type of activity that occurred" }, "activityDay": { "type": "string", "description": "The day of the week when the activity took place" }, "activityDate": { "type": "string", "description": "The date of the activity" }, "activityTime": { "type": "string", "description": "The time when the activity occurred" }, "customerId": { "type": "string", "description": "The unique identifier of the customer" }, "email": { "type": ["string", "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" }, "isManualActivity": { "type": ["boolean", "null"], "description": "Whether the activity was manually triggered" }, "points": { "type": ["number", "null"], "description": "The number of points involved in the activity" }, "score": { "type": ["number", "null"], "description": "The score involved in the activity" }, "reason": { "type": ["string", "null"], "description": "Reason entered for manual activities, if provided." }, "calculatedRedemption": { "type": ["number", "null"], "description": "Estimated monetary value based on redemption factor and involved points." }, "actualRedemption": { "type": ["number", "null"], "description": "Actual monetary value of redemption, if applicable." }, "familyRedemptionAmount": { "type": ["number", "null"], "description": "Redemption monetary value related to family wallet, if applicable." }, "familyRedemptionPoints": { "type": ["number", "null"], "description": "Redemption points related to family wallet, if applicable." }, "paymentRewardAmount": { "type": ["number", "null"], "description": "Cashback amount rewarded in currency." }, "outstandingPoints": { "type": ["number", "null"], "description": "Points currently available from the related transaction." }, "rewardThreshold": { "type": ["number", "null"], "description": "Minimum spend to receive configured reward points." }, "currency": { "type": ["string", "null"], "description": "Currency used in the transaction." }, "redemptionRewardFactor": { "type": ["number", "null"], "description": "Conversion rate between points and monetary value during redemption." }, "campaignName": { "type": ["string", "null"], "description": "Name of the associated rewards campaign, if any." }, "campaignStartDate": { "type": ["string", "null"], "description": "Start date of the associated campaign." }, "campaignEndDate": { "type": ["string", "null"], "description": "End date of the associated campaign." }, "campaignEnabled": { "type": ["boolean", "null"], "description": "Whether the associated campaign was enabled during the activity." }, "tierName": { "type": ["string", "null"], "description": "Tier name associated with tier-related activities." }, "rewardPoints": { "type": ["number", "null"], "description": "Number of points rewarded from the activity." }, "rewardFactor": { "type": ["number", "null"], "description": "Reward factor used to calculate reward points." }, "isGuest": { "type": ["boolean", "null"], "description": "Whether the actor is a guest (not signed up)." }, "couponUsed": { "type": ["boolean", "null"], "description": "Whether the coupon associated with this activity was used." }, "couponType": { "type": ["string", "null"], "description": "Type of coupon associated with the activity." }, "couponCode": { "type": ["string", "null"], "description": "Coupon code associated with this activity." }, "couponGroup": { "type": ["string", "null"], "description": "Group or campaign to which the coupon is linked." }, "couponProduct": { "type": ["string", "null"], "description": "Name of the product associated with the coupon, if any." }, "couponProductId": { "type": ["number", "null"], "description": "ID of the product associated with the coupon." }, "productVariantName": { "type": ["string", "null"], "description": "Name of the product variant involved in the event." } } } }, "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" } } }, "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" } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "apikey" }, "secretKey": { "type": "apiKey", "in": "header", "name": "secretkey" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }