Gameball Developers Guide
v4.0
v4.0
  • Introduction
  • Installing Gameball
    • Web
      • Initialize Gameball Customer Widget
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • iOS
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Push Notifications
      • Track Referrals
      • Go-Live Checklist
    • Android
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Push Notifications
      • Go-Live Checklist
    • React Native
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
      • Go-Live Checklist
    • Flutter
      • Getting Started
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Go-Live Checklist
    • Generic Mobile App
      • Initialize Gameball Customer Profile
      • Track Customer Events
      • Track Orders & Cashback Reward
      • Integrate Redemption
      • Track Referrals
      • Push Notifications
  • REST API
    • Overview
      • What's New in V4.0
      • Authentication
      • Rate Limiting
      • Status and Error Codes
    • Customers
      • Customer Management
      • Customer Progress
      • Customer Tags
      • Customer Notifications
    • Events
    • Order
      • Order Tracking
      • Order Rewards & History
    • Payment
      • Payment Tracking
    • Transactions
      • Cashback & Redemptions
      • Hold Management
      • Transaction Management
      • Transaction Validation
    • Coupons
    • Configurations
      • Reward Configurations
      • Program Configurations
      • Widget Configuration
    • Leaderboard
    • Batches
      • Batch Creation
      • Batch Management
  • Webhooks
    • Overview
    • Subscribing to Webhooks
    • Webhook Topics
      • Customer's Notifications
      • Customer's Profile Updates
  • Tutorials
    • Tracking Customer Events
    • Redemption Integration
      • Direct debit redemption
      • Coupons Redemption
        • Use Your Own Couponing Engine
        • Gameball Couponing Engine
    • Checkout Integration
    • Build Custom UI Elements
      • Reward Campaigns
      • VIP Tiers
      • Customer Balance
      • Widget Configurations
      • Coupons Customer Experience
      • Customer Notifications
      • Customer Leaderboard
    • Build your Own Notification System
    • Channel Merging Guide
    • Previewing Potential Points Before Purchase
    • Refund
    • Retail & POS Integration with Gameball Loyalty Program
    • Referrals
    • Widget Deep Links
    • Batch APIs usage example
  • Branch.io Integration
  • Adjust Integration
Powered by GitBook
On this page
  • GET - Check Batch Operation Status
  • Request
  • Response
  • DELETE - Stop Batch Operation
  • Request
  • Response
  1. REST API
  2. Batches

Batch Management

PreviousBatch CreationNextOverview

Last updated 1 month ago

The Batch Management API offers endpoints to monitor and control batch operations in Gameball, ensuring seamless tracking and execution. It allows you to check the status and retrieve the results of a batch job, providing transparency and insight into processed requests. Additionally, it enables you to cancel an ongoing batch execution when needed, giving you greater control over bulk processing workflows.

Available APIs

GET - Check Batch Operation Status

https://api.gameball.co/api/v4/integrations/batch/{jobId}

Security: Requires apiKey and secretKey headers.

Request

Path Parameters

jobId string Required The unique identifier for the job, generated by the creation endpoint. which is used to cancel the operation when needed.


Response

application/json

operation string

The type of batch operation being processed (e.g., customer creation, order processing, balance adjustment).


finishedCount number

The number of successfully processed requests in the batch job.


errorCount number

The number of failed requests within the batch job.


totalCount number

The total number of requests included in the batch job.


startedAt DateTime

The timestamp indicating when the batch job started processing.


createdAt DateTime

The timestamp indicating when the batch job was created.


status string

The current status of the batch job (e.g., pending, in progress, completed, failed).

Status types

Status

Description

Queued

The batch job has been created and is waiting to be processed.

Running

The batch job is currently being processed.

Completed

The batch job has finished processing successfully.

Failed

The batch job encountered errors and was unable to complete successfully.

Stopped

The batch job was manually stopped before completion.


response Object

An object containing additional details or results related to the batch job execution. The object may have one or both cases; an array of succeeded results and/or array of failed results.

Succeeded Response Object Sample Results
{
    "customerId": "cust_abc12345xyz67890",
    "customerAttributes": {
        "country": "USA",
        "city": "Los Angeles",
        "zip": "90001",
        "dateOfBirth": "1985-10-25",
        "joinDate": "2023-05-01",
        "custom": {
        "membershipLevel": "Gold",
        },
        "tags": [
            "loyal",
            "VIP"
        ],
        "source": "website",
        "utMs": [],
        "devices": [],
        "paymentMethods": [],
        "totalSpent": 1500,
        "lastOrderDate": "2024-09-15T00:00:00",
        "totalOrders": 25
    }
}
{
    "customerId": "cust_123456789",
    "redeemedPoints": 1000,
    "rewardedPoints": 101,
    "lineItems": [
        {
            "productId": "PROD98765",
            "quantity": 2,
            "decimalPoints": 91.25,
            "points": 91,
            "score": 0
        },
        {
            "productId": "Shipping",
            "quantity": 1,
            "decimalPoints": 10.0,
            "points": 10,
            "score": 0
        }
    ]
}
  • Balance Inquiry API

{
    "customerId": "12345",
    "pointsBalance": 500,
    "pointsValue": 50.0,
    "currency": "USD",
    "pointsName": "Loyalty Points"
  }
  • Balance Adjustment API

{
    "customerId": "12345",
    "points": 100
}
{
    "customerId": "cust_12345abc",
    "gameballTransactionId": 11034733,
    "rewardAmount": 150.75,
    "rewardEquivalentPoints": "0"
}
{
    "customerId": "cust_12345abc",
    "gameballTransactionId": "11034734",
    "transactionId": "txn98765",
    "redeemAmount": 10,
    "redeemEquivalentPoints": 100
}

No Response body in case of success for events

Failed Response Object Sample Results
"failed": [
    {
      "customerId": "12345",
      "message": "Invalid email format"
    },
    {
      "customerId": "67890",
      "message": "Missing required fields"
    },
    {
      "customerId": "11223",
      "message": "User not found"
    }
  ]

Sample Response

{
  "operation": "Customer Creation Batch Job",
  "errorCount": 2,
  "totalCount": 10,
  "finishedCount": 8,
  "startedAt": "2025-03-14T10:30:00Z",
  "createdAt": "2025-03-14T10:00:00Z",
  "status": "completed",
  "response": {
    "successful": [
      {
        "customerId": "12345",
        "message": "Customer created successfully"
      },
      {
        "customerId": "67890",
        "message": "Customer created successfully"
      }
    ],
    "failed": [
      {
        "customerId": "11111",
        "error": "Invalid email format"
      },
      {
        "customerId": "22222",
        "error": "Missing required fields"
      }
    ]
  }
}

DELETE - Stop Batch Operation

https://api.gameball.co/api/v4/integrations/batch/{jobId}

The Stop Batch Operation API allows you to cancel an ongoing batch job before it completes. This ensures greater control over bulk processing workflows, enabling you to halt jobs that are no longer needed, incorrectly configured, or consuming excessive resources.

Security: Requires apiKey and secretKey headers.

Request

Path Parameters

jobId string Required The unique identifier for the job, generated by the creation endpoint. which is used to cancel the operation when needed.


Response

application/json

204 - No Content: Successfully stopped the batch job, confirming that the operation has been terminated.

s

Track Order API response details
Check Batch Operation Status
Stop Batch Operation
Reward Cashback API response details
Redeem API response detail
Send Events API response details
Create or Update Customer API response details