openapi: 3.2.0 info: title: Gameball Integrations 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: [] tags: - name: Integrations 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' tags: - Integrations /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' tags: - Integrations 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 tags: - Integrations /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' tags: - Integrations /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' tags: - Integrations /api/v4.0/integrations/customers/social-challenges: post: summary: Achieve Social Campaign description: Mark a social campaign as achieved for a customer and grant the configured reward from your backend. This is the server-to-server equivalent of the in-widget social action for Social Activities campaigns. operationId: achieveSocialChallenge security: - apiKey: [] secretKey: [] requestBody: description: Social challenge achievement payload. required: true content: application/json: schema: type: object required: - customerId - challengeId properties: customerId: type: string maxLength: 100 description: The customer's unique ID in your system. The customer must already exist in Gameball. example: customer_123 challengeId: type: integer minimum: 1 description: The ID of the Social Activities campaign to award. example: 11664 email: type: string description: Customer's email address. Helps identify the customer when channel merging is enabled. example: john.doe@example.com mobile: type: string description: Customer's mobile number. Helps identify the customer when channel merging is enabled. example: '+1234567890' examples: sample: summary: Sample request value: customerId: customer_123 challengeId: 11664 responses: '202': description: Social challenge achievement accepted for processing content: application/json: schema: type: object properties: customerId: type: string description: The customer ID from the request. example: customer_123 challengeId: type: integer description: The social campaign ID from the request. example: 11664 gameballStatus: type: string description: Present when the Gameball program is disabled. Omitted while Gameball is enabled. message: type: string description: Informational message when the Gameball program is disabled. learnMore: type: string description: Link to learn more when the Gameball program is disabled. examples: accepted: value: customerId: customer_123 challengeId: 11664 '400': description: Invalid request (missing fields, duplicate submission, etc.) '401': description: Missing or invalid secret key '404': description: Customer does not exist '500': description: Unexpected server error x-codeSamples: - lang: curl label: cURL source: "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges' \\\n -H 'Content-Type: application/json' \\\n -H 'apikey: YOUR_API_KEY' \\\n -H 'secretkey: YOUR_SECRET_KEY' \\\n -d '{\"customerId\":\"customer_123\",\"challengeId\":11664}'" - lang: javascript label: JavaScript source: "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/social-challenges', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n apikey: 'YOUR_API_KEY',\n secretkey: 'YOUR_SECRET_KEY'\n },\n body: JSON.stringify({ customerId: 'customer_123', challengeId: 11664 })\n});" - lang: python label: Python source: "import requests\n\nrequests.post(\n 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',\n json={'customerId': 'customer_123', 'challengeId': 11664},\n headers={'apikey': 'YOUR_API_KEY', 'secretkey': 'YOUR_SECRET_KEY', 'Content-Type': 'application/json'}\n)" - lang: csharp label: C# source: 'using System.Net.Http; using System.Text; var client = new HttpClient(); client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY"); client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY"); var content = new StringContent("{\"customerId\":\"customer_123\",\"challengeId\":11664}", Encoding.UTF8, "application/json"); var response = await client.PostAsync("https://api.gameball.co/api/v4.0/integrations/customers/social-challenges", content); response.EnsureSuccessStatusCode();' tags: - Integrations /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' tags: - Integrations /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' tags: - Integrations /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. This API triggers the **"Payment Processed"** event, allowing you to automate follow-up actions such as initiating workflows, sending notifications, or rewarding customers with badges. The 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 tags: - Integrations /api/v4.0/integrations/transactions/redeem: post: description: This API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points in place of monetary value during transactions. By providing details such as customerId and amount, this endpoint facilitates point-based redemptions within the purchase process. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - transactionId - transactionTime properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc email: type: string description: Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn98765 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). example: '2024-10-11T10:57:43.382Z' amount: type: number description: 'The actual monetary value the customer wants to redeem. This will be deducted from their points balance based on the redemption factor. For instance, if the customer wants to redeem $10 and the redemption factor is 0.1, then 100 points will be deducted from their balance to cover this amount. Note: Only one of amount, points, or holdReference must be provided for the redemption.' example: 10 points: type: integer description: 'The number of points the customer wants to redeem from their balance. This allows the customer to specify exactly how many points they wish to use. Note: Only one of amount, points, or holdReference must be provided for the redemption.' example: 0 holdReference: type: string description: 'A unique reference obtained from the Hold Points API. If provided, the points in the hold will be used. It is used when points have been reserved previously, allowing the system to redeem the points that are on hold. Example: If you previously used the Hold Points API to hold 100 points, you would provide the holdReference obtained from that hold transaction to redeem the 100 points that were held. Note: Only one of amount, points, or holdReference must be provided for the redemption.' example: null merchant: type: object description: This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place. properties: uniqueId: type: string description: Unique identifier for the merchant. name: type: string description: Name of the merchant. branch: type: object required: - uniqueId properties: uniqueId: type: string description: Unique identifier for the branch where the transaction took place. name: type: string description: Name of the branch where the transaction took place. hash: type: string description: A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. For more details on how the hash is generated and validated, refer to the Customer's Hash section. example: HASH1234 otp: type: string description: One-time password (OTP) required if OTP is enabled for the customer. This OTP serves as an additional layer of security for verifying the redemption request. For more details on how OTP works and when it is required, refer to the Transaction Validation section. example: '123456' ignoreOTP: type: boolean description: This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP. example: false reason: type: string maxLength: 255 description: An optional reason for the redemption. This can be used to provide context about why the customer is redeeming points (e.g., 'Discount on order', 'Loyalty reward'). The reason will be stored with the transaction and displayed in the dashboard transaction details. example: 'Discount on order #12345' responses: '200': description: Points redeemed successfully content: application/json: schema: type: object properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc gameballTransactionId: type: string description: Unique identifier for the transaction in the Gameball system. example: '11034734' transactionId: type: string description: A unique identifier for the transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn98765 redeemAmount: type: number description: 'The amount of money redeemed in the transaction, based on the points redeemed. Example: If a customer redeems points equivalent to $10 off their purchase, the redeemAmount will be 10.0.' example: 10 redeemEquivalentPoints: type: number description: 'The number of points used to redeem the specified monetary value in the transaction. Example: If a customer uses 100 points to redeem $10, the redeemEquivalentPoints will be 100.' example: 100 reason: type: string description: The reason provided for the redemption, if one was included in the request. example: 'Discount on order #12345' tags: - Integrations /api/v4.0/integrations/transactions/cashback: post: description: This API awards loyalty points to customers in Gameball through a cashback program based on the amount. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - amount - transactionId - transactionTime properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. example: cust_12345abc email: type: string description: Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID is critical for managing transaction lifecycle events such as reversals, cancellations, or refunds in Gameball. example: TXN987654321 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). example: '2024-10-11T10:48:56.719Z' amount: type: number description: Monetary value of the transaction for which the customer will be rewarded, based on the Cashback program configuration. example: 150.75 merchant: type: object description: This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place. properties: uniqueId: type: string description: Unique identifier for the merchant. name: type: string description: Name of the merchant. branch: type: object required: - uniqueId properties: uniqueId: type: string description: Unique identifier for the branch where the transaction took place. name: type: string description: Name of the branch where the transaction took place. configurations: type: object description: This object contains configurations related to the cashback settings. properties: returnWindow: type: integer description: The number of days the cashback will stay in a pending state, typically aligning with the return window in e-commerce to account for potential order cancellations or refunds. The value should be between 0 and 7,300 days (20 years). example: 7 responses: '200': description: Cashback issued successfully content: application/json: schema: type: object properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc gameballTransactionId: type: number description: Unique identifier for the transaction in the Gameball system. example: 11034733 rewardAmount: type: number description: 'The monetary value equivalent of the points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase and each point is worth $0.10, the rewardAmount will be $5.' example: 150.75 rewardEquivalentPoints: type: number description: 'The number of points rewarded to the customer for the transaction. Example: If the customer earns 50 points for their purchase, the rewardEquivalentPoints will be 50.' example: 0 tags: - Integrations /api/v4.0/integrations/transactions/refund: post: description: This API processes refunds or cancellations of cashback and points redemption transactions in Gameball. By providing a reverseTransactionId, Gameball identifies the related cashback or redemption transaction and adjusts the customer's points balance accordingly to reflect the refunded or canceled transaction. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - refundTransactionId - reverseTransactionId - transactionTime properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_12345abc email: type: string description: Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' refundTransactionId: type: string description: 'A unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If a refund is processed for an item, the refundTransactionId could be REFUND-98765, which refers to the specific new refund transaction.' example: txn987657111 reverseTransactionId: type: string description: 'The unique transaction ID representing the original order being refunded, reversed, or canceled. This ID is sent as reverseTransactionId in the payload and links to the previous transaction. Example: If a customer requests a refund for an order previously made with transaction ID ORDER-12345, the reverseTransactionId will be ORDER-12345 to indicate which order is being refunded.' example: txn6342347194477 transactionTime: type: string format: date-time description: The timestamp of the original transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). example: '2024-10-13T17:11:00.249Z' refundAmount: type: number description: 'The amount to be refunded from the original transaction. The entire transaction is refunded if this field is not provided. Note: For a full refund, you can use any of the following approaches: Send the refund request without the refundAmount field, Send the refund request with refundAmount set to null, Send the refund request with refundAmount equal to the total paid in the original order.' example: 15.0 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.0 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 tags: - Integrations /api/v4.0/integrations/transactions/hold: post: description: This API holds loyalty points for a specified duration, reserving them until a redemption request is made through Order or Redeem. If no redemption occurs within the hold period, the points are released. The default hold time is 10 minutes, adjustable in the Gameball dashboard, with a maximum of 15 days and a minimum of 1 minute. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - transactionTime properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_abc12345xyz67890 email: type: string description: Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). example: '2024-10-11T16:15:15.071Z' otp: type: string description: A one-time password (OTP) sent to the customer for authentication purposes. This is used only if your account has OTP configuration enabled. For more details on how the OTP is generated and validated, refer to the OTP Generation and Validation section. example: '654321' ignoreOTP: type: boolean description: This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP. example: false amountToHold: type: number description: 'The monetary value (in the system''s currency) that will be held from the customer''s points balance. This allows you to reserve a specific monetary amount using the customer''s points. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.' example: null pointsToHold: type: integer description: 'The number of points to be held from the customer''s points balance. This allows you to reserve a certain number of points for later use. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.' example: 50 ruleId: type: string description: 'The ID of a redemption rule configured within Gameball''s system. Clients can create custom redemption rules through the Gameball dashboard to specify different redemption options. For example, a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts. You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API. Note: Only one of ruleId, amountToHold, or pointsToHold must be provided for the hold request to proceed.' example: null hash: type: string description: A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. This number changes with each transaction to ensure secure validation. For more details on how the hash is generated and validated, refer to the Customer's Hash section. example: '123456' responses: '200': description: Points placed on hold successfully content: application/json: schema: type: object properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_abc12345xyz67890 holdAmount: type: number description: The monetary value that has been held from the customer's points balance. This value represents the amount reserved based on the customer's available points. example: '5' holdEquivalentPoints: type: number description: The number of points that have been held from the customer's points balance. These points are reserved for future use or specific transactions. example: 50 holdReference: type: string description: A unique identifier for the hold transaction. This reference is used to track and manage the held points for future actions, such as redeeming the held points or canceling the hold. This hold reference can also be used in Order API to redeem the held points. example: a2a199ad-86f3-45c4-8253-7aaee50e4798 tags: - Integrations /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' tags: - Integrations 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 tags: - Integrations /api/v4.0/integrations/transactions: get: description: This API retrieves a paged list of transactions from Gameball, allowing for optional filtering. Each transaction record includes details such as type, direction, points, amount, transaction time, and balance changes, providing a comprehensive view of customer activity. security: - apiKey: [] secretKey: [] parameters: - name: direction in: query schema: type: string description: 'Direction of the transaction: + (Accumulation - points or rewards added to the customer), - (Deduction - points or rewards removed from the customer).' - name: status in: query schema: type: string description: 'Represents the current status of the transaction. Possible values are: Active (The transaction is fully completed, and any points or rewards have been successfully added or redeemed), Pending (Points or rewards from the transaction are pending during the return window period), Blocked (The transaction has been flagged and blocked due to suspected fraud or other security concerns), Expired (The points or rewards earned in this transaction have expired and are no longer available for redemption or use).' - name: startAfter in: query schema: type: integer description: Specifies the page will start after which transaction id. Defaults to 0. - name: limit in: query schema: type: integer default: 50 description: Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page. - name: customerId in: query schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. This is used to filter the transactions of the specified customer. responses: '200': description: Transactions retrieved successfully content: application/json: schema: type: object properties: transactions: type: array items: type: object properties: transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn123456 gameballTransactionId: type: string description: Unique identifier for the transaction in the Gameball system. example: '11034736' type: type: string description: 'Type of the transaction. Possible values: AchievementReward, PaymentReward, Refund, Redemption, Expiry, Cancel, Migration, ManualAccumulation, DiscountCode, ManualDeduction, ManualReward.' example: Cancel direction: type: string description: 'Direction of the transaction: + (Accumulation), - (Deduction).' example: '-' customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. example: cust_12345abc points: type: number description: Number of points involved in the transaction. example: 10 amount: type: number description: Monetary value associated with the transaction. example: 10.0 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime), in UTC. example: '2024-10-13T17:11:00.249' status: type: string description: 'Status of the transaction: Active (The transaction is completed, and any rewards or points have been applied successfully), Pending (The points or rewards from the transaction are temporarily on hold during the return window or any other pending period), Blocked (The transaction was flagged for potential fraud or another issue and is currently blocked from processing), Expired (Points or rewards from the transaction have expired and are no longer available for use).' example: Active couponCode: type: string description: The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer. example: null isCouponUsed: type: boolean description: Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again. example: false couponType: type: string description: 'The type of the coupon code that the customer has redeemed during the redemption transaction. Possible values: free_shipping, percentage_discount, fixed_discount, free_product, fixed_rate_discount, custom.' example: null merchantName: type: string description: Name of the merchant involved in the transaction, if any. example: MERCH1234 branchName: type: string description: Name of the branch involved in the transaction, if any. example: BRANCH123 reason: type: string description: Reason for the transaction, if applicable. example: trx reason achievementName: type: string description: The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable. example: null expiryDate: type: string format: date-time description: Date when the points or rewards from the transaction will expire, if applicable. example: '2025-10-13T17:11:00.249' pointsBalanceBefore: type: number description: The customer's points balance before the transaction occurred. example: 1164 pointsBalanceAfter: type: number description: The customer's points balance after the transaction is completed. example: 1154 achievementType: type: string description: Type of achievement earned during the transaction, if applicable. example: null achievedRewardCampaignId: type: string description: The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign. example: null achievedTierId: type: number description: The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier. example: null count: type: number description: The total number of transactions on the current page. example: 2 hasMore: type: boolean description: Indicating whether there are additional transactions to be fetched beyond the current page. example: true tags: - Integrations /api/v4.0/integrations/transactions/manual: post: description: This API allows for the manual addition or deduction of points for a customer in Gameball. It provides flexibility in managing loyalty points, enabling adjustments based on specific needs or circumstances. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - transactionId - username - reason properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_abc12345xyz67890 email: type: string description: Customer's email address. This is required if your account uses email-based channel merging. example: john.doe@example.com mobile: type: string description: Customer's mobile number. This is required if your account uses mobile-based channel merging. example: '+1234567890' transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn543211 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). Defaults to the current time in UTC when omitted. example: '2024-10-11T15:54:10.944Z' username: type: string description: The username of the admin performing the manual transaction. example: admin_user reason: type: string description: Reason for manually rewarding or deducting points (e.g., 'Referral bonus'). example: Referral bonus points: type: integer description: The number of points to be rewarded or deducted. Provide either points or amount. Positive values add points, and negative values deduct points. example: 50 amount: type: number description: The monetary value, in system currency, associated with the transaction. Provide either points or amount. Positive values add points, and negative values deduct points. example: 0 expiryAfter: type: integer minimum: 0 nullable: true description: The number of days after which the points added in this transaction will expire, counted from the time of the addition. For example, 30 means the awarded points expire 30 days from now. When omitted, null, or 0, the points follow the client's default points-expiry setting configured in the dashboard. This replicates the custom-expiry option available when manually adding points from the Gameball dashboard. expiryAfter applies only to point additions; it cannot be used when deducting points. example: 30 responses: '200': description: Manual transaction added successfully content: application/json: schema: type: object properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. example: cust_abc12345xyz67890 gameballTransactionId: type: number description: The unique identifier for the transaction within Gameball. example: 11035201 transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn54321221 points: type: number description: The number of points rewarded or deducted in the transaction. example: 50 amount: type: number description: The monetary value processed in the transaction. example: 5.0 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' examples: negativeExpiry: summary: Negative expiryAfter value: error: 400 message: Expiry cannot be negative deductionWithExpiry: summary: expiryAfter on a deduction value: error: 400 message: Deduction cannot have expiry multipleRewardingMethods: summary: Both points and amount provided value: error: 400 message: Only one rewarding method may be specified missingRewardingCriteria: summary: Neither points nor amount provided value: error: 400 message: A rewarding criteria is required tags: - Integrations /api/v4.0/integrations/transactions/customer-view: get: description: 'This API retrieves a paged list of transactions from Gameball, with support for optional filtering. It provides the same comprehensive transaction data as the previous version — including type, direction, points, amount, transaction time, and balance changes — but with an important enhancement: Each transaction now includes associated customer details, such as: Customer Name, Customer Email, Customer Deletion Status. This allows for better traceability and visibility into who performed each transaction, even if the customer has since been deleted.' security: - apiKey: [] secretKey: [] parameters: - name: direction in: query schema: type: string description: 'Direction of the transaction: + (Accumulation - points or rewards added to the customer), - (Deduction - points or rewards removed from the customer).' - name: status in: query schema: type: string description: 'Represents the current status of the transaction. Possible values are: Active (The transaction is fully completed, and any points or rewards have been successfully added or redeemed), Pending (Points or rewards from the transaction are pending during the return window period), Blocked (The transaction has been flagged and blocked due to suspected fraud or other security concerns), Expired (The points or rewards earned in this transaction have expired and are no longer available for redemption or use).' - name: startAfter in: query schema: type: integer description: Specifies the page will start after which transaction id. Defaults to 0. - name: limit in: query schema: type: integer default: 50 description: Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page. - name: customerId in: query schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. This is used to filter the transactions of the specified customer. responses: '200': description: Transactions with customer data retrieved successfully content: application/json: schema: type: object properties: transactions: type: array items: type: object properties: transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. example: txn123456 gameballTransactionId: type: string description: Unique identifier for the transaction in the Gameball system. example: '11034736' type: type: string description: 'Type of the transaction. Possible values: AchievementReward, PaymentReward, Refund, Redemption, Expiry, Cancel, Migration, ManualAccumulation, DiscountCode, ManualDeduction, ManualReward.' example: Cancel direction: type: string description: 'Direction of the transaction: + (Accumulation), - (Deduction).' example: '-' customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. example: cust_12345abc customerName: type: string description: The display name of the customer associated with this transaction. example: John Doe customerEmail: type: string description: The email address of the customer associated with this transaction. example: john.doe@example.com isCustomerDeleted: type: boolean description: Indicates whether the customer has been marked as deleted in our system and is an existing customer or not. example: false points: type: number description: Number of points involved in the transaction. example: 10 amount: type: number description: Monetary value associated with the transaction. example: 10.0 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime), in UTC. example: '2024-10-13T17:11:00.249' status: type: string description: 'Status of the transaction: Active (The transaction is completed, and any rewards or points have been applied successfully), Pending (The points or rewards from the transaction are temporarily on hold during the return window or any other pending period), Blocked (The transaction was flagged for potential fraud or another issue and is currently blocked from processing), Expired (Points or rewards from the transaction have expired and are no longer available for use).' example: Active couponCode: type: string description: The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer. example: null isCouponUsed: type: boolean description: Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again. example: false couponType: type: string description: 'The type of the coupon code that the customer has redeemed during the redemption transaction. Possible values: free_shipping, percentage_discount, fixed_discount, free_product, fixed_rate_discount, custom.' example: null merchantName: type: string description: Name of the merchant involved in the transaction, if any. example: MERCH1234 branchName: type: string description: Name of the branch involved in the transaction, if any. example: BRANCH123 reason: type: string description: Reason for the transaction, if applicable. example: trx reason achievementName: type: string description: The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable. example: null expiryDate: type: string format: date-time description: Date when the points or rewards from the transaction will expire, if applicable. example: '2025-10-13T17:11:00.249' pointsBalanceBefore: type: number description: The customer's points balance before the transaction occurred. example: 1164 pointsBalanceAfter: type: number description: The customer's points balance after the transaction is completed. example: 1154 achievementType: type: string description: Type of achievement earned during the transaction, if applicable. example: null achievedRewardCampaignId: type: string description: The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign. example: null achievedTierId: type: number description: The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier. example: null count: type: number description: The total number of transactions on the current page. example: 2 hasMore: type: boolean description: Indicating whether there are additional transactions to be fetched beyond the current page. example: true tags: - Integrations /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 tags: - Integrations /api/v4.0/integrations/transactions/{transactionId}/activate: put: description: 'This API is used to immediately activate loyalty points that are currently in a pending state, bypassing the configured return window duration. This endpoint overrides that duration and activates the points immediately, making them available for use by the customer without waiting for the pending return window duration to elapse. This API is especially useful for scenarios where the client determines that the order is confirmed and the points can be safely activated ahead of schedule. Note: Once points are activated, the action cannot be reversed via this API.' security: - apiKey: [] secretKey: [] parameters: - name: transactionId in: path required: true schema: type: string description: The transaction id on your system which you want to activate. responses: '200': description: Transaction activated successfully content: application/json: schema: type: object properties: pointsActivated: type: number description: Number of points that has been successfully activated by the transaction example: 50 gameballTransactionId: type: number description: The unique identifier for the transaction within Gameball. example: 11035201 clientTransactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). example: txn54321221 tags: - Integrations /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.0 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 tags: - Integrations /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 tags: - Integrations /api/v4.0/integrations/coupons/{code}/validate: post: description: This API validates a single coupon identified by {code} and checks its eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves the coupon by creating a lock reference. This ensures the coupon cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupon. security: - apiKey: [] secretKey: [] parameters: - name: code in: path required: true schema: type: string description: The coupon code you want to validate. requestBody: required: true content: application/json: schema: type: object required: - customerId properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. email: type: string description: Customer's email address. Required if your account uses email-based channel merging. mobile: type: string description: Customer's mobile number. Required if your account uses mobile-based channel merging. lock: type: boolean description: Indicates whether the request is intended to validate the coupon or to lock it for a future redemption. lockReference: type: string description: Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session. lockDuration: type: integer description: Represents the number of minutes for which a coupon will be locked if the lock flag is set to True. merchantId: type: string description: This parameter is required only if the coupon is designed to apply to specific merchants. collectionId: type: string description: This parameter is required only if the coupon is configured to apply to specific collections. collectionsIds: type: array items: type: string description: This parameter is required only when the coupon is configured to apply to specific collections. totalPurchaseAmount: type: number description: This parameter represents the total value of the purchase where the coupon will be applied. responses: '200': description: Coupon validated successfully content: application/json: schema: type: object properties: valid: type: boolean description: Indicates whether the coupon is valid to be used by the customer or not. coupon: $ref: '#/components/schemas/Coupon' lockReference: type: string description: The unique reference code associated with the coupon lock session. dateToExpire: type: string format: date-time description: The exact date and time when the coupon lock will expire. tags: - Integrations /api/v4.0/integrations/coupons/validate: post: description: This API validates a list of coupons and checks their eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves eligible coupons by creating hold references. This ensures that locked coupons cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupons. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId - coupons properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. email: type: string description: Customer's email address. Required if your account uses email-based channel merging. mobile: type: string description: Customer's mobile number. Required if your account uses mobile-based channel merging. coupons: type: array items: type: string description: A list of coupon codes to validate. lock: type: boolean description: Indicates whether the request is intended to validate the coupon or to lock it for a future redemption. lockReference: type: string description: Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session. lockDuration: type: integer description: Represents the number of minutes for which a coupon will be locked if the lock flag is set to True. merchantId: type: string description: This parameter is required only if the coupon is designed to apply to specific merchants. collectionId: type: string description: This parameter is required only if the coupon is configured to apply to specific collections. collectionsIds: type: array items: type: string description: This parameter is required only when the coupon is configured to apply to specific collections. totalPurchaseAmount: type: number description: This parameter represents the total value of the purchase where the coupon will be applied. responses: '200': description: Coupons validated successfully content: application/json: schema: type: object properties: valid: type: boolean description: Indicates whether the coupons are valid. coupons: type: array items: $ref: '#/components/schemas/Coupon' description: An array containing the details of the coupons that need to be locked or validated in the request. lockReference: type: string description: The unique reference code associated with the coupon lock session. dateToExpire: type: string format: date-time description: The exact date and time when the coupon lock will expire. tags: - Integrations /api/v4.0/integrations/coupons/burn: post: description: This API processes the use of one or more coupons associated with a customer in Gameball. By providing customer details and a list of coupons, this endpoint marks the coupons as redeemed, completing the transaction. Optionally, a lockReference can be included to burn previously locked coupons. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object required: - customerId properties: customerId: type: string email: type: string mobile: type: string transactionId: type: string description: A unique identifier for the transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any coupon burn transactions in Gameball. example: txn98765 transactionTime: type: string format: date-time description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format). example: '2024-10-11T10:57:43.382Z' coupons: type: array items: type: string description: List of coupons that need to be burned. Only one of coupons or lockReference must be provided. lockReference: type: string description: Reference used to burn the locked coupons from the validation step. Only one of coupons or lockReference must be provided. responses: '200': description: Coupon burned successfully content: application/json: schema: type: object properties: success: type: boolean burnedAt: type: string format: date-time tags: - Integrations /api/v4.0/integrations/coupons/{lockReference}: delete: description: This API releases the lock on coupons identified by the provided {lockReference} in Gameball. Once released, the coupons become available for use again, offering flexibility in managing coupon availability and redemption. security: - apiKey: [] secretKey: [] parameters: - name: lockReference in: path required: true schema: type: string description: Unique identifier for the previously locked coupons to be available for others to use again or for another session. responses: '200': description: Coupons released successfully content: application/json: schema: type: object properties: success: type: boolean releasedAt: type: string format: date-time releasedCoupons: type: array items: type: string tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations 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 tags: - Integrations /api/v4.0/integrations/configurations/reward-campaigns: get: summary: Campaigns Configurations description: The API retrieves your reward campaign configurations, including both event-based and transactional campaigns. If the customerId, productSku, or collectionId query parameters are provided, the response will include the reward campaigns that are applicable for the specified customer or product. operationId: getCampaignsConfigurations security: - apiKey: [] parameters: - name: customerId in: query description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. If provided, the API filters and returns only the campaigns that can be achieved by this customer. required: false schema: type: string - name: collectionId in: query description: Unique identifier for a product collection. If provided, the API returns the transactional campaigns applicable to the specified collection. required: false schema: type: string - name: productSku in: query description: The SKU (Stock Keeping Unit) of a product. If provided, the API returns the transactional campaigns applicable to the specified product. required: false schema: type: string - name: lang in: header description: If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. required: false schema: type: string responses: '200': description: Campaigns retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/RewardCampaignConfiguration' tags: - Integrations /api/v4.0/integrations/configurations/tiers: get: summary: Tiers Configurations description: This API call retrieves the tiers configuration, including the benefits and rewards associated with each tier. operationId: getTiersConfigurations security: - apiKey: [] parameters: - name: lang in: header description: If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. required: false schema: type: string responses: '200': description: VIP tiers retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/TierConfiguration' tags: - Integrations /api/v4.0/integrations/configurations/referrals: get: summary: Referrals Configurations description: This API retrieves the referral configuration, including customer and friend rewards, as well as metadata related to the events that trigger referral rewards. operationId: getReferralsConfigurations security: - apiKey: [] parameters: - name: lang in: header description: If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. required: false schema: type: string responses: '200': description: Referral settings retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ReferralConfiguration' tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /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. tags: - Integrations 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 tags: - Integrations /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. tags: - Integrations /api/v4.0/integrations/batch/orders: post: description: Register multiple orders for single or multiple customers in a single API call for efficient order management and tracking. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object properties: body: type: array items: type: object required: - customerId - orderId - orderDate - totalPaid properties: customerId: type: string description: Unique identifier for the customer. orderId: type: string description: Unique identifier for the order. orderDate: type: string format: date-time description: Date and time of the order. Must be in UTC (ISO 8601 format), e.g. `2024-10-16T08:13:29.290Z`. totalPaid: type: number description: Total amount paid for the order. responses: '200': description: Batch order processing initiated successfully content: application/json: schema: type: object properties: jobId: type: number description: The assigned job ID, which is later used for status verification and response retrieval. tags: - Integrations /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. tags: - Integrations /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. tags: - Integrations /api/v4.0/integrations/batch/cashback: post: description: Award loyalty points to customers through cashback program for multiple customers in a single API call. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object properties: body: type: array items: type: object required: - customerId - transactionId - transactionTime - amount properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. email: type: string description: Customer's email address. Required if your account uses email-based channel merging. mobile: type: string description: Customer's mobile number. Required if your account uses mobile-based channel merging. transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). transactionTime: type: string format: date-time description: The time of the transaction in your system. Must be in UTC (ISO 8601 format). amount: type: number description: Monetary value of the transaction for which the customer will be rewarded. responses: '200': description: Batch cashback reward processing initiated successfully content: application/json: schema: type: object properties: jobId: type: number description: The assigned job ID, which is later used for status verification and response retrieval. tags: - Integrations /api/v4.0/integrations/batch/redeem: post: description: Enable customers to redeem loyalty points as a payment method for multiple customers in a single API call. security: - apiKey: [] secretKey: [] requestBody: required: true content: application/json: schema: type: object properties: body: type: array items: type: object required: - customerId - transactionId - transactionTime properties: customerId: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. email: type: string description: Customer's email address. Required if your account uses email-based channel merging. mobile: type: string description: Customer's mobile number. Required if your account uses mobile-based channel merging. transactionId: type: string description: A unique identifier for a transaction in your system (e.g., order number or invoice number). transactionTime: type: string format: date-time description: The time of the transaction in your system. Must be in UTC (ISO 8601 format). amount: type: number description: The actual monetary value the customer wants to redeem. points: type: integer description: The number of points the customer wants to redeem from their balance. holdReference: type: string description: A unique reference obtained from the Hold Points API. responses: '200': description: Batch redemption processing initiated successfully content: application/json: schema: type: object properties: jobId: type: number description: The assigned job ID, which is later used for status verification and response retrieval. tags: - Integrations /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. tags: - Integrations /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 tags: - Integrations /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 tags: - Integrations /api/v4.0/integrations/orders/{orderId}/transactions: delete: description: Delete a customer by customerId. security: - apiKey: [] secretKey: [] x-codeSamples: - lang: C# label: C# source: 'using System.Net.Http; using System.Threading.Tasks; var client = new HttpClient(); client.BaseAddress = new System.Uri("https://api.gameball.co"); client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY"); client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY"); var request = new HttpRequestMessage(HttpMethod.Delete, "/api/v4.0/integrations/customers/12345"); var response = await client.SendAsync(request); response.EnsureSuccessStatusCode();' parameters: - name: customerId in: path required: true schema: type: string description: Unique customer identifier responses: {} tags: - Integrations /api/v4.0/integrations/customers/{customerId}/balance: get: summary: Get Customer Balance description: 'This API retrieves a customer''s current points balance within Gameball, including redeemable points and their monetary equivalent. It provides detailed balance information, such as total, available, and pending points, along with upcoming expirations. **Security:** Requires both `apikey` and `secretkey` headers.' operationId: getCustomerBalance security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. schema: type: string - name: expand in: query required: false schema: type: string description: 'Comma-separated expansions: tier,referrals' responses: '200': description: Customer balance retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerBalanceResponse' example: totalPointsBalance: 1500 totalPointsValue: 75.0 availablePointsBalance: 1200 availablePointsValue: 60.0 pendingPoints: 300 pendingPointsValue: 15.0 currency: USD pointsName: Reward Points nextExpiringPointsAmount: 200 nextExpiringPointsValue: 10.0 nextExpiringPointsDate: '2024-12-01T00:00:00' totalEarnedPoints: 2500 tags: - Integrations /api/v4.0/integrations/customers/{customerId}/tier-progress: get: summary: Get Customer Tier Progress description: This API provides an overview of a customer's current tier and progression within Gameball's loyalty program. By retrieving the customer's current tier, progress level, and next tier details, this endpoint offers a clear view of their advancement within the tier structure. operationId: getCustomerTierProgress security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: expand in: query required: false schema: type: string description: 'Comma-separated expansions: tier,referrals' - name: lang in: header required: false schema: type: string description: If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. responses: '200': description: Customer tier progress retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerTierProgressResponse' example: current: order: 1 name: Basic minProgress: 0 icon: https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp next: order: 2 name: Gold minProgress: 190 icon: https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads/gb-library/levels-icons/level-a1.webp progress: 50 tags: - Integrations /api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress: get: summary: Get Customer Campaigns Progress description: This API retrieves a customer's progress within Gameball's reward campaigns, providing insights into their achievements and current status in each campaign. By accessing completion percentages and unlock statuses, you can track how customers are engaging with various reward opportunities. operationId: getCustomerCampaignsProgress security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: lang in: header required: false schema: type: string description: If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. - name: campaignType in: query required: false schema: type: string enum: - reward - game description: Filter campaigns by type. Use `reward` to return only reward-type campaigns (points multipliers, missions, spending milestones, streaks, etc.), or `game` for game-type campaigns (Spin the Wheel, Slot Machine, Quiz, Scratch & Win, Match Cards, etc.). Omit to return all campaigns. Any other value results in a validation error. - name: campaignId in: query required: false schema: type: integer minimum: 1 description: 'Filter the response to a single campaign by its ID. When provided, the response array contains at most one item: the matching campaign''s progress, or an empty array if the campaign does not exist or is not available to this customer. Must be a positive integer. Use the campaign ID returned in rewardsCampaignId or rewardCampaignConfiguration.id. Can be combined with campaignType, in which case both filters apply.' responses: '200': description: Customer campaigns progress retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerCampaignsProgressResponse' '400': description: Bad request. Returned when campaignId is non-numeric, such as campaignId=abc. '422': description: Unprocessable entity. Returned when campaignId is zero or negative. content: application/json: schema: type: object properties: code: type: integer example: 3003 type: type: string example: PAYLOAD_ERROR message: type: string example: invalid campaignid value. the campaign id must be a positive integer. example: code: 3003 type: PAYLOAD_ERROR message: invalid campaignid value. the campaign id must be a positive integer. tags: - Integrations /api/v4.0/integrations/customers/{customerId}/referrals: get: summary: Get Customer Referrals description: This API retrieves a list of customers referred by a specified customer in Gameball, including each referral's join date and current status within the referral program. operationId: getCustomerReferrals security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: startAfter in: query required: false schema: type: integer format: int64 default: 0 description: Specifies the page will start after which Gameball customer id. Defaults to 0. - name: limit in: query required: false schema: type: integer default: 50 maximum: 200 description: Specifies the number of friends to return per page. Defaults to 50, with a maximum limit of 200 transactions per page. responses: '200': description: Customer referrals retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerReferralsResponse' tags: - Integrations /api/v4.0/integrations/customers/{customerId}/referrals/count: get: summary: Get Customer Referrals Count description: This API retrieves the total count of customers referred by a specified customer in Gameball, providing the number of completed and pending referrals. operationId: getCustomerReferralsCount security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. responses: '200': description: Customer referrals count retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerReferralsCountResponse' example: count: 15 totalPending: 5 totalActive: 10 tags: - Integrations /api/v4.0/integrations/customers/{customerId}/activities: get: summary: Get Customer Activities description: This API retrieves a log of customer activities within Gameball, identified by customerId. The logs detail various actions, such as tier changes, campaign rewards, referrals, redemptions, and more. Specific activity types can be filtered, including events like TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing comprehensive visibility into each customer's engagement history. operationId: getCustomerActivities security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: startAfter in: query required: false schema: type: integer format: int64 default: 0 description: Specifies the page will start after which activity id. Defaults to 0. - name: limit in: query required: false schema: type: integer default: 50 maximum: 200 description: Specifies the number of activities to return per page. Defaults to 50, with a maximum limit of 200 transactions per page. - name: activityType in: query required: false schema: type: string enum: - TierUpgraded - TierDowngraded - TierMigration - CampaignRewarded - SuccessfulAction - Referral - Referred - ReferralBonusReward - PaymentReward - Refund - Redemption - Cancel - Expiry - Migration - Lifetime - Automation description: 'Filters activities by a specific type, such as: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer''s tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign).' responses: '200': description: Customer activities retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerActivitiesResponse' tags: - Integrations /api/v4.0/integrations/customers/{customerId}/activities/count: get: summary: Get Customer Activities Count description: This API retrieves the total count of customer activities within Gameball, identified by customerId. It allows for filtering by specific activity types, such as TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing the number of activities matching the specified criteria without returning detailed activity logs. operationId: getCustomerActivitiesCount security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: activityType in: query required: false schema: type: string enum: - TierUpgraded - TierDowngraded - TierMigration - CampaignRewarded - SuccessfulAction - Referral - Referred - ReferralBonusReward - PaymentReward - Refund - Redemption - Cancel - Expiry - Migration - Lifetime - Automation description: 'Filters activities by a specific type, such as: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer''s tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign).' responses: '200': description: Customer activities count retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerActivitiesCountResponse' example: count: 240 tags: - Integrations /api/v4.0/integrations/customers/{customerId}/automation: get: summary: Get Customer Automation Campaigns description: This API retrieves the available automation campaigns for the customer, identified by customerId. The response includes details of campaigns currently active and applicable to the customer, such as onboarding journeys, engagement triggers, or milestone-based campaigns. Specific campaign types can be filtered, including campaigns like Welcome Campaigns, Ramadan Campaign, and Custom Automations, offering a comprehensive view of personalized campaigns available for the customer. operationId: getCustomerAutomationCampaigns security: - apiKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: campaignType in: query required: false schema: type: string enum: - mission - all default: mission description: 'Filters automation steps by a specific type, such as: mission (return steps for mission-based campaigns, default), all (return all automation steps and details).' responses: '200': description: Customer automation campaigns found content: application/json: schema: $ref: '#/components/schemas/CustomerAutomationCampaignsResponse' tags: - Integrations /api/v4.0/integrations/customers/{customerId}/stamps/{challengeId}: get: summary: Get Customer Stamps Progress description: Retrieve the progress of a specific customer within a particular Stamps campaign in Gameball. It returns how many steps the customer has completed, how many times they've earned the campaign reward, and whether they are eligible to continue. operationId: getCustomerStampsProgress security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: challengeId in: path required: true schema: type: integer description: Unique identifier of the Stamps campaign to retrieve progress for. responses: '200': description: Customer stamps progress found content: application/json: schema: $ref: '#/components/schemas/CustomerActionStreakProgressResponse' tags: - Integrations /api/v4.0/integrations/customers/{customerId}/streaks/{campaignId}: get: summary: Get Customer Daily Streak Progress description: Retrieve the progress of a specific customer within a particular daily streak campaign in Gameball. It returns the current and highest streak counts, ongoing reward details, badge milestones, and the next milestone to unlock. operationId: getCustomerDailyStreakProgress security: - apiKey: [] secretKey: [] parameters: - name: customerId in: path required: true schema: type: string description: Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer. - name: campaignId in: path required: true schema: type: integer description: Unique identifier of the daily streak campaign to retrieve progress for. responses: '200': description: Customer daily streak progress found content: application/json: schema: $ref: '#/components/schemas/CustomerDailyStreakProgressResponse' '401': description: Unauthorized – apikey or secretkey is missing or invalid '404': description: Customer or campaign not found tags: - Integrations /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' tags: - Integrations 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' tags: - Integrations /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 requests.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; var client = new HttpClient(); client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY"); client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY"); var res = await client.DeleteAsync("https://api.gameball.co/api/v4.0/integrations/customers/12345/tags/vip"); res.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' tags: - Integrations /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 resp = requests.get(''https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications'', headers={''apikey'':''YOUR_API_KEY'',''secretkey'':''YOUR_SECRET_KEY''}) print(resp.json())' - lang: csharp label: C# source: 'using System.Net.Http; var client = new HttpClient(); client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY"); client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY"); var res = await client.GetAsync("https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications"); res.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' tags: - Integrations /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' tags: - Integrations /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 requests.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; var client = new HttpClient(); client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY"); client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY"); var content = new StringContent("{\"notificationIds\":[\"n_01\",\"n_02\"]}", Encoding.UTF8, "application/json"); var res = await client.PostAsync("https://api.gameball.co/api/v4.0/integrations/customers/12345/notifications/read", content); res.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' tags: - Integrations /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 tags: - Integrations components: schemas: CustomerCouponsResponse: type: object properties: coupons: type: array description: List of coupon objects associated with the customer items: type: object properties: name: type: string description: Name of the coupon code: type: string description: The coupon code that the customer will use value: type: number description: The monetary value or percentage value of the coupon type: type: string description: Type of the coupon enum: - Free Shipping - Fixed Rate Discount - Percentage - Free Product - Custom - Percentage-based Fees Discount - Percentage-based Cashback target: type: string description: How the coupon is associated with the customer enum: - Online - POS - Permanent - Reward - Automation currency: type: string description: Currency code if the coupon has a fixed monetary value startDate: type: string format: date-time description: The date and time when the coupon becomes valid expiryDate: type: string format: date-time description: The date and time when the coupon will expire isExpired: type: boolean description: Indicates if the coupon has expired isActive: type: boolean description: Status of the coupon, whether it is active or not usageLimit: type: number description: The total number of times the coupon can be used limitPerCustomer: type: number description: The number of times a single customer can use the coupon usedCount: type: number description: Number of times the coupon has been used customerUsedCount: type: number description: Number of times the coupon has been used by this customer isAvailableToUse: type: boolean description: Flag determining whether coupon can be used by customer at given time iconPath: type: string description: Path or URL to the icon image for the coupon Success: type: object properties: success: type: boolean message: type: string 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. Coupon: type: object properties: code: type: string description: The generated coupon code that the customer will use. type: type: string enum: - shipping - fixed - percentage - product - percentage-fees - fixed-cashback - percentage-cashback description: Type of the coupon, such as fixed amount, percentage discount, free shipping, cashback or product-specific coupon. value: type: number description: The monetary value or percentage value of the coupon, depending on its type. usageLimit: type: number description: The total number of times the coupon can be used across all customers. limitPerCustomer: type: number description: The number of times a single customer can use the coupon. startDate: type: string format: date-time description: The date and time when the coupon becomes valid and can be used. expiryDate: type: string format: date-time description: The date and time when the coupon will expire and no longer be valid. capping: type: number description: The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value. minReward: type: number description: Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon. minOrderValue: type: number description: The minimum order value required for the coupon to be applied. entitledProductIds: type: array items: type: string description: A list of product IDs that are eligible for the coupon. entitledVariantIds: type: array items: type: string description: A list of product variant IDs that are eligible for the coupon. entitledCollectionIds: type: array items: type: string description: A list of collection IDs that are eligible for the coupon. entitledMerchantIds: type: array items: type: string description: A list of merchant external IDs that are eligible to redeem the coupon. combinesWith: type: object properties: orderDiscounts: type: boolean description: Indicates if the coupon can be combined with order-level discounts. productDiscounts: type: boolean description: Indicates if the coupon can be combined with product-specific discounts. shippingDiscounts: type: boolean description: Indicates if the coupon can be combined with shipping discounts. TierState: type: object properties: order: type: number description: This represents the numerical order of a tier. Higher numbers indicate higher tiers. name: type: string description: The name of the tier. minProgress: type: number description: 'The minimum amount of progress a customer needs to reach the next tier in the program. This represents the threshold that must be met for a customer to reach this tier. Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to advance to the next tier.' icon: type: string description: The URL for the icon associated with the tier. You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles. This offers a visual representation of the customer's tier status. 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 CustomerNotificationsCountResponse: type: object properties: count: type: number description: The total number of notifications available for the customer in Gameball system 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 ReferralConfiguration: type: object properties: referralMethod: type: string description: 'This specifies who will receive the referral reward when a successful referral is made. Possible values: CustomerOnly (Only the customer making the referral will receive the reward. The referred friend will not receive any reward), CustomerAndFriend (Both the customer making the referral and the referred friend will receive rewards, encouraging mutual benefit).' eventName: type: string description: 'This describes the event that will trigger the referral reward. Example: if the eventName is set to place_order, the referral reward will be granted when the referred friend completes an order after using the referral link. Other events can also be configured to trigger the reward, depending on your system''s setup.' eventMetaData: type: - object - 'null' description: Contains additional metadata about the event that triggers the referral. properties: name: type: - string - 'null' description: The name of the event metadata. operator: type: - string - 'null' description: The operator used for event metadata (e.g., equals, greater_than). value: type: - string - 'null' description: The value associated with the event metadata. friendReward: type: - object - 'null' description: The reward details given to the referred friend as part of the referral program. properties: score: type: - number - 'null' description: The score awarded to the referred friend. point: type: - number - 'null' description: The points awarded to the referred friend. coupon: type: - object - 'null' description: A coupon object that is awarded to the referred friend. properties: couponType: type: - string - 'null' description: 'The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.' discountValue: type: - number - 'null' description: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' description: The unique identifier for the product. productName: type: - string - 'null' description: The name of the product. variantId: type: - string - 'null' description: The unique identifier for the product variant. variantName: type: - string - 'null' description: The name of the product variant. productDisplayName: type: - string - 'null' description: The display name associated with the product that configured on the dashboard based on required language. collections: type: - array - 'null' description: A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: 'The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.' startDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: 'The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.' usageLimit: type: - number - 'null' description: 'The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.' capping: type: - number - 'null' description: 'The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.' minOrderValue: type: - number - 'null' description: 'The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.' codePrefix: type: - string - 'null' description: 'The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".' redeemInstructions: type: - string - 'null' description: 'The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."' customerReward: type: - object - 'null' description: The reward details given to the customer as part of the referral program. properties: score: type: - number - 'null' description: The score awarded to the customer. point: type: - number - 'null' description: The points awarded to the customer. coupon: type: - object - 'null' description: A coupon object that is awarded to the customer. properties: couponType: type: - string - 'null' description: 'The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.' discountValue: type: - number - 'null' description: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' description: The unique identifier for the product. productName: type: - string - 'null' description: The name of the product. variantId: type: - string - 'null' description: The unique identifier for the product variant. variantName: type: - string - 'null' description: The name of the product variant. productDisplayName: type: - string - 'null' description: The display name associated with the product that configured on the dashboard based on required language. collections: type: - array - 'null' description: A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: 'The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.' startDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: 'The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.' usageLimit: type: - number - 'null' description: 'The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.' capping: type: - number - 'null' description: 'The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.' minOrderValue: type: - number - 'null' description: 'The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.' codePrefix: type: - string - 'null' description: 'The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".' redeemInstructions: type: - string - 'null' description: 'The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."' extraReward: type: - object - 'null' description: It contains all the details of the reward (like the friendReward Object) that will be awarded to the customer as a bonus on top of the regular reward for every X friend referred. properties: forEvery: type: - number - 'null' description: This defines the number of friends a customer needs to refer in order to earn the extraReward. For example, if the value of forEvery is set to 5, the customer will receive the extra reward for every 5 friends they successfully refer. This acts as a bonus on top of the regular reward, incentivizing more referrals. score: type: - number - 'null' description: The score awarded as part of the extra reward. point: type: - number - 'null' description: The points awarded as part of the extra reward. coupon: type: - object - 'null' description: A coupon object that is awarded as part of the extra reward. CustomerTierProgressResponse: type: object properties: current: $ref: '#/components/schemas/TierState' description: The customer's current tier. next: $ref: '#/components/schemas/TierState' description: The next tier the customer can reach. progress: type: number description: 'The current progress of the customer toward the next tier, reflecting their activity and engagement within the program. This value is calculated based on the client''s chosen tiering-up method, indicating how close the customer is to advancing to a higher tier. Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier. Possible Values: Total amount spent, Total points earned, Friends referred, Orders completed, Score.' CustomerActivitiesCountResponse: type: object properties: count: type: number description: The total number of activities available in Gameball system. MarkNotificationsReadRequest: type: object required: - notificationIds properties: notificationIds: type: array items: type: string CustomerReferralsResponse: type: object properties: referredFriends: type: array description: A list of friends referred by the customer. items: type: object properties: customerId: type: string description: Unique identifier for the referred friend. displayName: type: string description: Display name of the referred friend. email: type: string description: Email address of the referred friend. mobileNumber: type: string description: Mobile number of the referred friend. joinDate: type: string description: The date when the referred friend joined. status: type: string enum: - Active - Pending description: 'The current status of the referral: Active (The referral was successfully completed. The referred friend has completed the required action (e.g., placing an order), and the referral is counted for the customer), Pending (The referred friend has used the customer''s referral link but has not yet completed the required action (e.g., signing up or making a purchase) for the referral to be considered complete).' count: type: number description: The total number of friends on the current page. hasMore: type: boolean description: Indicating whether there are additional friends to be fetched beyond the current page. CustomerCampaignsProgressResponse: type: array items: type: object properties: rewardsCampaignName: type: string description: The name of the rewards campaign. rewardsCampaignId: type: number description: The unique ID of the rewards campaign. isUnlocked: type: boolean description: Indicates if the customer has unlocked the campaign. highScoreAmount: type: - number - 'null' description: The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign. currentStreak: type: - number - 'null' description: The current number of consecutive days the customer has visited the website. This value is applicable only in the context of a streak (daily visit) rewards campaign. highestStreak: type: - number - 'null' description: The maximum number of consecutive days the customer has visited the website. This value is also applicable only in the context of a streak (daily visit) rewards campaign. completionPercentage: type: number description: The percentage of the campaign the customer has completed. For example, in a second-order campaign where the customer must make 2 orders, if they have only placed 1 order, the completion percentage will be 50%. achievedCount: type: number description: The number of times the customer has achieved the campaign. canAchieve: type: boolean description: A flag that determines whether the customer is currently eligible to participate in and achieve this reward campaign. It provides a quick indication of the customer's ability to meet the campaign's conditions based on their current status. rewardCampaignConfiguration: type: object description: Comprehensive description of the reward campaign configuration. properties: id: type: number description: Unique identifier for the reward campaign. name: type: string description: Name of the reward campaign. description: type: - string - 'null' description: A brief description of the reward campaign. isRepeatable: type: boolean description: 'Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer.' maxAchievement: type: number description: 'Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true. If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available.' type: type: string description: 'The type of the campaign. Possible values: SignUp (Reward is given when a user signs up), SocialMedia (Reward is linked to social media activity), ScheduledChallenge (A time-based challenge that gives rewards), Spin The Wheel (Rewards are given based on a spin-the-wheel game), EventBased (Reward is given based on specific customer events), HighScore (Reward is given based on achieving high scores in a campaign), Birthday (Reward is given for birthday-related activity).' visibility: type: string description: 'The visibility status of the campaign. Possible values: AlwaysVisible (The campaign is always visible on the widget), NotVisible (The campaign is not visible to the customer on the widget), VisibleIfEarned (The campaign becomes visible once the customer earns it on the widget).' icon: type: - string - 'null' description: The URL of the campaign's icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform. redirectionButtonText: type: - string - 'null' description: 'The text displayed on the redirection button within the reward campaign page on the widget. Example: "Claim Your Reward" would prompt customers to take action.' redirectionButtonLink: type: - string - 'null' description: 'The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward redemption process. Example: "https://yourwebsite.com/rewards" directs customers to a page where they can view their rewards.' widgetDetailsParameter: type: - string - 'null' description: 'This value is used with the openDetails parameter to open the widget for a specific campaign. The value is generated based on the campaign type and campaign ID. You could always use this parameter to trigger the widget on a specific page that you want. This parameter is only required if you are drawing your own UI but still want to display the UI of specific campaigns through the widget. In mobile apps, you can programmatically control the Gameball widget using our SDKs by passing the openDetails parameter with the appropriate value to navigate to different sections. Examples: details_reward_campaign_{reward_campaign_id} (Opens a standard reward campaign), details_wheel_{reward_campaign_id} (Opens a specific wheel campaign), details_scratch_{reward_campaign_id} (Opens a scratch card campaign), details_match_{reward_campaign_id} (Opens a match game campaign).' activation: type: - object - 'null' properties: startDate: type: - string - 'null' format: date-time description: 'The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: "2024-11-01T00:00:00" indicates that the campaign starts on November 1, 2024.' endDate: type: - string - 'null' format: date-time description: 'The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign. Example: "2024-11-30T23:59:59" indicates that the campaign ends on November 30, 2024, at 11:59 PM.' rewards: type: array items: type: object properties: rankReward: type: number description: The score rewarded for achieving this reward campaign. walletReward: type: number description: 'The number of points the customer will earn upon achieving this reward campaign. Example: If you have set up a "First Order" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200.' walletRewardFactor: type: - number - 'null' description: 'The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers. Example: In a "Double Points" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign.' couponReward: type: - object - 'null' properties: couponType: type: - string - 'null' description: 'The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.' discountValue: type: - number - 'null' description: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' productName: type: - string - 'null' variantId: type: - string - 'null' variantName: type: - string - 'null' productDisplayName: type: - string - 'null' collections: type: - array - 'null' description: A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: 'The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.' startDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: 'The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.' usageLimit: type: - number - 'null' description: 'The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.' capping: type: - number - 'null' description: 'The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.' minOrderValue: type: - number - 'null' description: 'The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.' codePrefix: type: - string - 'null' description: 'The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".' redeemInstructions: type: - string - 'null' description: 'The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."' CustomerDailyStreakProgressResponse: type: object properties: currentStreakCount: type: number description: Number of consecutive periods completed in the current active streak highestStreakCount: type: number description: Highest streak count ever reached by this customer for this campaign totalRewardsEarned: type: number description: Total streak rewards earned across all time ongoingReward: type: object description: Details of the currently active reward tier properties: name: type: string description: Reward name as configured in the client language settings type: type: string description: 'Reward type: points or coupon' value: type: string description: Reward value (points amount or coupon description) nextMilestone: type: number nullable: true description: Streak count at which the next reward unlocks, or null if at the last tier lastActivityDate: type: string format: date-time description: Date/time of the last qualifying action in the client's local timezone campaignEndDate: type: string format: date-time nullable: true description: Campaign end date in the client's local timezone, or null if open-ended badges: type: array description: Badge milestones ordered by milestoneDay ascending items: type: object properties: milestoneDay: type: number description: Streak day at which this badge is awarded name: type: string description: Badge name imageUrl: type: string description: Badge image URL earned: type: boolean description: Whether this customer has earned this badge earnedDate: type: string format: date-time nullable: true description: Date earned, or null if not yet earned CustomerActivitiesResponse: type: object properties: activities: type: array description: An array of activity records for the customer items: type: object properties: activityId: type: number description: Unique identifier for the activity activityType: type: string description: 'The type of activity that occurred (e.g., "Balance Adjustment", "Referral"). Available Activity Types: TierUpgraded (Indicates that the customer has been upgraded to a new tier), TierDowngraded (Indicates that the customer has been downgraded to a lower tier), TierMigration (Represents the migration of the customer''s tier), CampaignRewarded (Signifies that the customer received a reward from a campaign), BalanceAdjustment (Indicates that points were either rewarded or deducted manually from the customer''s balance), SuccessfulAction (Denotes successful progress by the customer in a campaign), Referral (Indicates that the customer referred a friend), Referred (The referee received a reward for being referred by the customer), ReferralBonusReward (Represents a bonus reward given for a referral), PaymentReward (Signifies that the customer received a cashback reward), Refund (Points were refunded back to the customer), Redemption (Points were redeemed by the customer), Cancel (A cashback transaction was canceled), Expiry (Indicates that points have expired), Migration (Represents a migration activity that occurred), Lifetime (Refers to activities related to lifetime coupons), Automation (Activity performed by an automation campaign).' activityDay: type: string description: The day of the week when the activity took place (e.g., "Sunday"). activityDate: type: string description: The date of the activity (e.g., "October 20, 2024"). activityTime: type: string description: The time when the activity occurred (e.g., "19:27:33"). customerId: type: string description: The unique identifier of the customer associated with the activity. email: type: - string - 'null' description: The email address of the customer. phoneNumber: type: - string - 'null' description: The customer's phone number. displayName: type: - string - 'null' description: The customer's display name. transactionId: type: - string - 'null' description: A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball. It represents the transaction ID related to this activity, if applicable, such as in cases of cashback rewards, points redemption, or balance adjustments. isManualActivity: type: - boolean - 'null' description: 'Indicates whether the activity was manually triggered (true) or not (false). Example: This will be true if the activity is a BalanceAdjustment, when you manually decide to reward the customer with points.' points: type: - number - 'null' description: The number of points involved in the activity, such as points earned, redeemed, or adjusted. score: type: - number - 'null' description: 'The score involved in the activity, applicable in reward campaigns where the customer earns score. Example: If the customer participates in a campaign and earns 100 score points, the activity will include the score value.' reason: type: - string - 'null' description: 'This is the reason manually entered for the activity, if provided. It is typically used when performing a manual activity, such as rewarding points or rewarding a manual reward campaign for a customer. Example: If you manually reward a customer with 100 points for their birthday, you might enter "Birthday reward" as the reason.' calculatedRedemption: type: - number - 'null' description: The estimated monetary value based on the redemption factor configured by the client and the points involved in this activity. It reflects the potential worth of the points, even if no actual redemption was made. actualRedemption: type: - number - 'null' description: The actual monetary value of the redemption, if applicable. This represents the redeemed amount when the activity type is points redemption. familyRedemptionAmount: type: - number - 'null' description: The redemption monetary value related to the customer's family wallet, if applicable. familyRedemptionPoints: type: - number - 'null' description: The redemption points related to the customer's family wallet, if applicable. paymentRewardAmount: type: - number - 'null' description: 'The amount rewarded in currency from the payment reward. This value reflects the cashback reward provided to the customer. Example: If a customer receives a cashback reward of $10, the paymentRewardAmount will be 10.' outstandingPoints: type: - number - 'null' description: 'The number of points currently available from the transaction related to this activity. Example: If a customer earned 100 points from a transaction and 20 points have since expired, the outstandingPoints would be 80, representing the points still available for the customer to use.' rewardThreshold: type: - number - 'null' description: 'This represents the minimum monetary amount (X value) a customer needs to spend to receive a specific number of reward points (Y points) as cashback reward, based on the configured points settings. It defines the threshold of spending required to earn points in your loyalty program. Example: If rewardThreshold is set to 50.0, it means for every 50 currency units (e.g., 50 USD) spent by the customer, they will earn the configured number of reward points.' currency: type: - string - 'null' description: The currency used in the transaction (e.g., "EGP"). redemptionRewardFactor: type: - number - 'null' description: 'The factor used to calculate how many points are required for a redemption. This value determines the conversion rate between points and monetary value during a redemption process. Example: If the redemptionRewardFactor is 0.1, then for every 10 points, the customer can redeem 1 unit of currency.' campaignName: type: - string - 'null' description: The name of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded. campaignStartDate: type: - string - 'null' description: The start date of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded. campaignEndDate: type: - string - 'null' description: The end date of the rewards campaign associated with the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded. campaignEnabled: type: - boolean - 'null' description: Indicates if the associated campaign was enabled during the activity. This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded. tierName: type: - string - 'null' description: 'The tier name of the customer during the activity. The name of the tier associated with the activity. This is relevant when the activity involves a tier-related event, such as: TierUpgraded, TierDowngraded, TierMigration. Example: if a customer moves from "Silver" to "Gold" in the TierUpgraded activity, "Gold" will be displayed as the associated tier name.' rewardPoints: type: - number - 'null' description: The number of points rewarded from the activity. rewardFactor: type: - number - 'null' description: The reward factor used in the calculation of reward points. isGuest: type: - boolean - 'null' description: A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default. couponUsed: type: - boolean - 'null' description: 'Indicates whether the coupon associated with this activity was used or not. This is a boolean value, where true means the coupon was used during the activity, and false means it was not. Example: true if the coupon was successfully applied, false if the coupon was associated with the event but was not used.' couponType: type: - string - 'null' description: 'Represents the type of coupon associated with the activity. Example: "percentage_discount", "free_shipping", "fixed_rate_discount".' couponCode: type: - string - 'null' description: 'The code of the coupon that was associated with this activity. This is the actual coupon code that was available for use during the activity. Example: "SUMMER20".' couponGroup: type: - string - 'null' description: 'Represents the group or campaign to which the coupon is linked. This could be a marketing campaign, product category, or customer segment. Example: "Holiday Campaign", "VIP Customer Group", "Black Friday Sale".' couponProduct: type: - string - 'null' description: 'The name of the product associated with the coupon, if the coupon was tied to a specific product. Example: "Wireless Earbuds".' couponProductId: type: - number - 'null' description: 'The unique ID of the product associated with the coupon. This ID helps track which specific product was related to the coupon. Example: 123456 for "Wireless Earbuds".' productVariantName: type: - string - 'null' description: 'The name of the product variant involved in the event. This would apply if the coupon or activity was specific to a certain variant of a product, such as size or color. Example: "Wireless Earbuds - Black", "T-shirt - Large".' count: type: number description: The total number of activities on the current page hasMore: type: boolean description: Whether there are additional logs to be fetched 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 RewardCampaignConfiguration: type: object properties: id: type: number description: Unique identifier for the reward campaign. name: type: string description: Name of the reward campaign. description: type: - string - 'null' description: A brief description of the reward campaign. isRepeatable: type: boolean description: 'Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer.' maxAchievement: type: number description: 'Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true. If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available.' type: type: string description: 'The type of the campaign. Possible values: SignUp (Reward is given when a user signs up), SocialMedia (Reward is linked to social media activity), ScheduledChallenge (A time-based challenge that gives rewards), Spin The Wheel (Rewards are given based on a spin-the-wheel game), EventBased (Reward is given based on specific customer events), HighScore (Reward is given based on achieving high scores in a campaign), Birthday (Reward is given for birthday-related activity).' visibility: type: string description: 'The visibility status of the campaign. Possible values: AlwaysVisible (The campaign is always visible on the widget), NotVisible (The campaign is not visible to the customer on the widget), VisibleIfEarned (The campaign becomes visible once the customer earns it on the widget).' icon: type: - string - 'null' description: The URL of the campaign's icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform. availability: type: object description: Defines the criteria determining which customers are eligible to earn this reward campaign. properties: minTier: type: number description: 'The minimum customer tier order required to achieve in the campaign. Customers must meet or exceed this tier to be eligible. Example: A value of 2 indicates that only customers in the tier with order 2 or higher can earn this campaign.' tags: type: array items: type: string description: 'A list of tags that identify the target customers eligible for the campaign. Tags can be used to group customers based on specific attributes or behaviors. Example: ["loyal", "new_customer"] indicates that only customers tagged as "loyal" or "new_customer" are eligible for the campaign.' redirectionButtonText: type: - string - 'null' description: 'The text displayed on the redirection button within the reward campaign page on the widget. Example: "Claim Your Reward" would prompt customers to take action.' redirectionButtonLink: type: - string - 'null' description: 'The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward campaign achievement. Example: "https://yourwebsite.com/rewards" directs customers to a page where they can view their rewards.' activation: type: - object - 'null' description: Defines the activation criteria for the campaign, which may include specific start and end dates. properties: startDate: type: - string - 'null' format: date-time description: 'The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: "2024-11-01T00:00:00" indicates that the campaign starts on November 1, 2024.' endDate: type: - string - 'null' format: date-time description: 'The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign. Example: "2024-11-30T23:59:59" indicates that the campaign ends on November 30, 2024, at 11:59 PM.' rewards: type: array description: Details of the rewards that the customer will earn once achieving this reward campaign. items: type: object properties: rankReward: type: number description: The score rewarded for achieving this reward campaign. walletReward: type: number description: 'The number of points the customer will earn upon achieving this reward campaign. Example: If you have set up a "First Order" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200.' walletRewardFactor: type: - number - 'null' description: 'The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers. Example: In a "Double Points" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign.' couponReward: type: - object - 'null' description: A coupon object that is awarded to the customer for this reward campaign. properties: couponType: type: - string - 'null' description: 'The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.' discountValue: type: - number - 'null' description: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' description: The unique identifier for the product. productName: type: - string - 'null' description: The name of the product. variantId: type: - string - 'null' description: The unique identifier for the product variant. variantName: type: - string - 'null' description: The name of the product variant. productDisplayName: type: - string - 'null' description: The display name associated with the product that configured on the dashboard based on required language. collections: type: - array - 'null' description: A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: 'The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.' startDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: 'The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.' usageLimit: type: - number - 'null' description: 'The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.' capping: type: - number - 'null' description: 'The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.' minOrderValue: type: - number - 'null' description: 'The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.' codePrefix: type: - string - 'null' description: 'The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".' redeemInstructions: type: - string - 'null' description: 'The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."' 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' CustomerHashResponse: type: object properties: hash: type: string description: A unique, rotating identifier generated for each customer for secure verification CustomerTagsUpdateRequest: type: object required: - tags properties: tags: type: string description: A comma-separated list of tags to apply or remove (e.g., 'gamer, highSpender'). CustomerReferralsCountResponse: type: object properties: count: type: number description: The total number of friends referred by the customer available in Gameball system. totalPending: type: number description: The total number of referred friends who have joined but not yet completed the referral criteria in the Gameball system. totalActive: type: number description: The total number of referred friends who have successfully completed the referral criteria in the Gameball system. ReferralValidationResponse: type: object properties: isValid: type: boolean description: Indicates whether the provided referral code is valid and eligible for use TierConfiguration: type: object properties: name: type: string description: The name of the tier. minProgress: type: number description: 'The minimum amount of progress a customer needs to reach this tier in the program. This represents the threshold that must be met for a customer to reach this tier. Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to reach this tier. Possible Values: Total amount spent, Total points earned, Friends referred, Orders completed, Score. Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier.' order: type: number description: This represents the numerical order of a tier. Higher numbers indicate higher tiers. icon: type: string description: The URL for the icon associated with the tier. You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles. benefits: type: array description: It contains a list of rewards associated with the tier, each offering specific advantages to the customer. This array includes various types of benefits. items: type: object properties: type: type: string description: 'Indicates the type of benefit the customer will receive. The possible values are: Custom Benefits (Offers tailored and custom rewards to offer customization for specific customer preferences or behaviors), Lifetime Reward (A benefit that can be used once at any time during the customer''s lifetime with Gameball, as long as they remain in this tier), Loyalty Points Earning Custom Configuration (Enables customized settings for how customers earn loyalty points based on their spending amount), Entry Reward (A one-time reward granted to customers upon joining this tier).' description: type: - string - 'null' description: Description of the custom benefit. hyperLink: type: - string - 'null' description: Hyperlink associated with the custom benefit. rankReward: type: number description: The score rewarded for the customer as a reward. walletReward: type: number description: The number of points the customer will earn for this reward. walletRewardFactor: type: - number - 'null' description: 'This is a multiplier factor that indicates how the customer on their tier will be rewarded for each unit of currency they spend. This is returned for the benefits of type Loyalty Points Earning Custom Configuration. Example: If a tier has a walletRewardFactor of 2, it means any customer on this tier will earn 2 loyalty points for every $1 they spend. Therefore, if the customer spends $100, they would receive 200 loyalty points as a reward.' couponReward: type: - object - 'null' description: A coupon object that is awarded to the customer. properties: couponType: type: - string - 'null' description: 'The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom.' discountValue: type: - number - 'null' description: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' description: The unique identifier for the product. productName: type: - string - 'null' description: The name of the product. variantId: type: - string - 'null' description: The unique identifier for the product variant. variantName: type: - string - 'null' description: The name of the product variant. productDisplayName: type: - string - 'null' description: The display name associated with the product that configured on the dashboard based on required language. collections: type: - array - 'null' description: A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: 'The maximum number of times a customer can use the coupon. Example: 5 indicates that each customer can redeem this coupon up to 5 times.' startDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: 'The number of days after creation that the coupon will expire. Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.' usageLimit: type: - number - 'null' description: 'The maximum number of times a single coupon can be used. Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.' capping: type: - number - 'null' description: 'The maximum discount value a coupon can provide, regardless of the order amount. Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.' minOrderValue: type: - number - 'null' description: 'The minimum order amount required to apply the coupon. Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.' codePrefix: type: - string - 'null' description: 'The prefix that will be added to the beginning of the generated coupon code. Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".' redeemInstructions: type: - string - 'null' description: 'The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount."' 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. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string CustomerBalanceResponse: type: object properties: totalPointsBalance: type: number description: The total number of points the customer has, including pending points. totalPointsValue: type: number description: The total monetary value of the customer's points, including pending points. availablePointsBalance: type: number description: The number of points that are currently active and available for use (excludes pending points). availablePointsValue: type: number description: The monetary value of the points that are currently active and available for use (excludes pending points). pendingPoints: type: number description: 'The points earned by the customer that are temporarily on hold during the return window configured for your account. These points will remain in a pending status until the return period expires, ensuring that the points are not used or redeemed until it is confirmed that the transaction is final and not subject to returns or cancellations. Example: If a customer places an order and earns 100 points, and your account is configured with a 14-day return window, these 100 points will remain pending for 14 days. During this time, the customer cannot use or redeem the points. After the 14-day window expires and the order is confirmed as final, the 100 points will become available for the customer to use.' pendingPointsValue: type: number description: The monetary value of the pending points. currency: type: string description: The currency in which the points value is calculated. pointsName: type: string description: 'The name of the points used in your loyalty program that appears to customers. This is the term your customers will see when they earn or redeem points. Example: If your loyalty program rewards customers with "Stars" instead of generic "Points", the value of pointsName could be "Stars".' nextExpiringPointsAmount: type: number description: The amount of points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame. nextExpiringPointsValue: type: number description: The monetary value of the points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame. nextExpiringPointsDate: type: string description: The date when the next set of points will expire. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame. totalEarnedPoints: type: number description: The total number of points that the customer has earned over their entire lifetime within the Gameball program. This includes all points accumulated from various activities like cashback rewards, referrals, or rewards campaigns. 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 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 securitySchemes: apiKey: type: apiKey in: header name: apikey secretKey: type: apiKey in: header name: secretkey bearerAuth: type: http scheme: bearer