Batch Creation

The Batch Creation API Endpoints enable efficient bulk processing of multiple operations in a single request, optimizing performance and reducing network overhead. These APIs support large-scale transactions, data synchronization, and automated workflows within Gameball. With batch processing, you can create or update multiple customer profiles, register multiple orders for single or multiple customers, retrieve and adjust customer loyalty balances, award cashback as loyalty points, allow customers to redeem points as a payment method, and track multiple user actions or multiple actions for a single user.

Each creation request supports up to 1,000 objects per request.

Available APIs

• Create Customers Batch Job

• Track Orders Batch Job

• Balance Inquiry Batch Job

• Balance Adjustment Batch Job

• Send Events Batch Job

• Reward Cashback Batch Job

• Redeem Batch Job

POST - Create Customers Batch Job

https://api.gameball.co/api/v4/integrations/batch/customers

The Batch Customer API allows clients to create or update multiple customer profiles in a single API call. This is useful for bulk user imports, mass profile updates, and large-scale customer data synchronization while reducing network overhead and improving efficiency.

Security: Requires apiKey and secretKey headers.

Request

Body

application/json

customerId string Required 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.

Its recommended not to use sequence for customerId

---

email string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number.

Note: This is required if your account uses mobile-based channel merging.

---

deviceToken string Optional Token used to identify the device.

---

osType string Optional Operating system type of the device.

---

customerAttributes Object Optional Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.

customerAttributes object

displayName string Optional Display name for the customer.

---

firstName string Optional Customer's first name.

---

lastName string Optional Customer's last name.

---

email string Optional Customer's email address.

---

gender string Optional Customer's gender.

---

mobile string Optional Customer's mobile number.

---

dateOfBirth string Optional Customer's date of birth.

---

joinDate string Optional Date the customer joined.

---

country string Optional Customer's country.

---

city string Optional Customer's city.

---

zip string Optional Customer's postal code.

---

preferredLanguage string Optional 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 string Optional 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. Tags can represent customer preferences, behaviors, or any other custom categories relevant to your business.

Example: A customer could have tags like "VIP", "High Spender", or "Frequent Shopper" to indicate their status or behavior patterns, allowing for more targeted engagement.

---

source string Optional Source of the customer registration.

---

utms array Optional List of UTM attributes associated with the customer.

---

devices array Optional List of devices associated with the customer.

---

paymentMethods array Optional 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.

Example:[ "Credit Card", "PayPal", "Apple Pay" ]

---

totalSpent float Optional Total amount spent by the customer.

---

lastOrderDate string Optional Date of the last order placed by the customer.

---

totalOrders integer Optional Total number of orders placed by the customer.

---

avgOrderAmount float Optional Average amount spent per order by this customer.

---

channel string Optional 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.

Possible values:

• mobile: The customer was acquired or engaged through your mobile application.

• pos: The customer was acquired or interacted in person using a Point of Sale (POS) system, such as at a physical store or outlet.

• web: The customer was acquired or engaged through your website.

• callcenter: The customer was acquired or engaged over the phone by contacting a customer service representative or a call center.

---

Custom Object Optional 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.

---

For complete details and list of properties check Create or Update Customer API

Sample request

{
    "body": [
        {
            "customerId": "cust_abc",
            "email": "[e-mail]",
            "mobile": "1234567890",
            "customerAttributes": {
                "city": "Los Angeles",
                "zip": "90001",
                "custom": {
                    "membershipLevel": "Gold"
                },
                "tags": [
                    "loyal"
                ],
                "source": "mobile",
                "totalSpent": 1500,
                "lastOrderDate": "2024-09-15T00:00:00",
                "totalOrders": 25
            }
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Track Orders Batch Job

https://api.gameball.co/api/v4/integrations/batch/orders

The Batch Order API enables merchants to create multiple orders in a single request. This is useful for bulk order processing, syncing transaction data, integrating customer purchases, and rewarding them for completing their purchases. The API supports orders for single or multiple customers, allowing efficient order registration and reward calculations.

Security: Requires apiKey and secretKey headers.

Request

Body

application/json

customerId string Required 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 string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number.

Note: This is required if your account uses mobile-based channel merging.

---

orderId string Required Unique identifier for the order on your system.This ID is case-sensitive.

---

totalPaid float Required The actual amount paid by the customer for the order, accounting for any discounts or coupons applied. Unlike totalPrice, which reflects the original cost of the order, totalPaid represents the final amount the customer paid at checkout after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the order.

Example: A customer purchases items worth $120, including taxes and shipping. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid. This is the value used to calculate any points or rewards earned from the order.

---

orderDate datetime Required Timestamp of when the order was placed.

---

For complete details and list of properties check Track Order API

Sample Request

{
    "body": [
        {
            "customerId": "cust_123456789",
            "email": "[e-mail]",
            "mobile": "[phone]",
            "orderId": "ORD12345",
            "totalPaid": 250.75,        
            "orderDate": "2024-09-15T00:00:00"
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Balance Inquiry Batch Job

https://api.gameball.co/api/v4/integrations/batch/balance/inquiry

The Balance Inquiry Batch API allows merchants to retrieve the balance of multiple customers in a single request. This is useful for bulk processing, account reconciliation, and large-scale customer engagement operations.

Security: Requires apiKey and secretKey headers.

Request

Body

application/json

body array Required A string array of the unique identifiers for the customers for whom the balance inquiry is being made.

---

Sample Request

{
    "body": [
        "cust_123",
        "cust_abc",
        "cust_123abc"
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Balance Adjustment Batch Job

https://api.gameball.co/api/v4/integrations/batch/balance/adjust

The Balance Adjustment Batch API allows merchants to adjust the loyalty balances of multiple customers in a single request. This is useful for bulk reward allocations, refunds, corrections, and large-scale promotional campaigns.

Security: Requires apiKey and secretKey headers.

Channel Merging Available

If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

Request

Body

customerId string Required 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 string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number.

Note: This is required if your account uses mobile-based channel merging.

---

points number Required Token used to identify the device.

---

Sample Request

{
    "body": [
        {
            "customerId": "123456",
            "points": 500,
            "email": "[e-mail]",
            "mobile": "[phone]"
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Send Events Batch Job

https://api.gameball.co/api/v4/integrations/batch/events

The Batch Events API allows you to record multiple user actions or multiple actions for a single user in a single request. Each event has a name (e.g., place_order, signup, referral) and can include properties such as amount, source, or other relevant metadata. Tracking these events helps monitor user behavior, automate rewards, and optimize engagement strategies.

Security: Requires apiKey and secretKey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

Request

Body

application/json

customerId string Required 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.

---

events object Required

An object containing one or more events, each represented by its event name as the key, and an associated object containing metadata related to the event. The structure of the event object can vary depending on the specific event being recorded. Events can be any significant action a customer performs, such as making a purchase, writing a review, adding to cart, etc.

The events object holds one or more events as keys (e.g., write_review, place_order, etc.), where each key is the event name, and its value is an object that can include metadata, providing additional details about the event. The metadata inside each event can vary depending on the nature of the event, but it usually contains properties that help describe the specifics of that event, such as product IDs, order amounts, or timestamps.

How the Event Object Works:

• Each event key corresponds to a specific customer action.

• Inside each event, the metadata can contain relevant attributes, such as item or transaction identifiers, descriptions, or other properties that describe the action in more detail.

This allows you to track and monitor important actions that a customer takes within your platform. These events can later be used for analysis, rewarding customers, or triggering automation.

Event Object

EventName : This is the name of the event that represents the action taken by the customer. Common event names include actions such as write_review or place_order. Each event name is unique and corresponds to a specific type of activity. The event name is used as the key in the events object.

EventMetadata: These are optional but recommended fields that give additional context to the event. They can include information such as product details, transaction amounts, or other relevant data. Metadata can be a string, number, or an array of values.

Examples :

• Product Review: If a customer writes a review on a product they purchased, you can track this as an event (write_review) with metadata that includes the product_id, the content of the review, and the rating the customer provided.

{ "write_review": {
      "product_id": "1653503260",
      "review": "Great product, highly recommend!",
      "rating": 5
    }}

• Order Placement: If a customer places an order, the place_order event can be recorded with metadata like the order_id, order_amount, and possibly a list of products or payment details.

{
  "place_order": {
      "order_id": "ORD12345",
      "order_amount": 150.75,
      "currency": "USD",
      "payment_method": "Credit Card"
    }
 }

---

For complete details and list of properties check Send Events API

Sample Request

{
    "body": [
        {
            "customerId": "1848877205",
            "events": {
                "write_review": {
                    "product_id": "1653503260",
                    "review": "5 Stars Product"
                }
            }
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Reward Cashback Batch Job

https://api.gameball.co/api/v4/integrations/batch/cashback

The Reward Cashback Batch API awards loyalty points to customers in Gameball through a cashback program based on the transaction amount.

Security: Requires apiKey and secretKey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

Request

Body

application/json

customerId string Required 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 string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number .

Note: This is required if your account uses mobile-based channel merging.

---

transactionId string Required 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.

---

transactionTime dateTime Required The time of the transaction in your system (e.g., order datetime, invoice datetime).

---

amount number Required Monetary value of the transaction for which the customer will be rewarded, based on the Cashback program configuration.

---

For complete details and list of properties check Reward Cashback API

Sample Request

{
    "body": [
        {
            "customerId": "cust_12345abc",
            "transactionId": "TXN987654321",
            "transactionTime": "2024-10-11T10:48:56.719Z",
            "amount": 150.75
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.

POST - Redeem Batch Job

https://api.gameball.co/api/v4/integrations/batch/redeem

The Batch Redeem API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points instead of monetary value during transactions. This API supports bulk redemptions, making it efficient for handling multiple customer transactions in a single request.

Security: Requires apiKey and secretKey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

Request

Body

application/json

customerId string Required 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 string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number .

Note: This is required if your account uses mobile-based channel merging.

---

transactionId string Required 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.

---

transactionTime string Required The time of the transaction in your system (e.g., order datetime, invoice datetime).

---

amount float Optional 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.

---

points integer Optional 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.

---

holdReference string Optional 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.

---

For complete details and list of properties check Redeem API

Sample Request

{
    "body": [
        {
            "customerId": "cust_12345abc",
            "transactionId": "txn98765",
            "transactionTime": "2024-10-11T10:57:43.382Z",
            "amount": 10,
            "points": 0,
            "holdReference": null
        }
    ]
}

---

Response

application/json

jobIdnumber The assigned job ID, which is later used for status verification and response retrieval.

---

Sample Response

{
    "jobId": 123456
}

For batch job status or response, use the Check Batch Operation Status API to retrieve processing details and results, or the Stop Batch Operation API to cancel an ongoing job.