Batch Management

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.

PreviousBatch CreationNextOverview

Last updated