Skip to main content
POST
/
api
/
v4.0
/
integrations
/
transactions
/
manual
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/transactions/manual \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>' \
  --data '
{
  "customerId": "cust_abc12345xyz67890",
  "transactionId": "txn543211",
  "username": "admin_user",
  "reason": "Referral bonus",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "transactionTime": "2024-10-11T15:54:10.944Z",
  "points": 50,
  "amount": 0,
  "expiryAfter": 30
}
'
{
  "customerId": "cust_abc12345xyz67890",
  "gameballTransactionId": 11035201,
  "transactionId": "txn54321221",
  "points": 50,
  "amount": 5
}

​
Add Manual Transaction

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. This endpoint is also available on v4.1.
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.
Security: Provide both apikey and secretkey headers.

​
Custom Points Expiry

Use expiryAfter to set a custom expiry period for points added through a manual transaction. The value is the number of days after which the added points expire, counted from the time the points are credited. For example, 30 means the awarded points expire 30 days from the time of the addition. When expiryAfter is omitted, sent as null, or sent as 0, the points follow the client’s default points-expiry setting configured in the dashboard. This matches the custom expiry option available when manually adding points from the Gameball dashboard.
expiryAfter applies only to point additions. Do not send it with a deduction, such as a negative points or amount value.

​
Validation

ConditionResult
expiryAfter is negative400 - Expiry cannot be negative
expiryAfter is provided on a deduction, such as negative points or amount400 - Deduction cannot have expiry
Both points and amount are provided400 - Only one rewarding method may be specified
Neither points nor amount is provided400 - A rewarding criteria is required

​
Example: Add Points With Custom Expiry

curl -X POST "https://api.gameball.co/api/v4.0/integrations/transactions/manual" \
  -H "Content-Type: application/json" \
  -H "APIKey: <YOUR_API_KEY>" \
  -H "secretkey: <YOUR_SECRET_KEY>" \
  -d '{
    "customerId": "player-123",
    "transactionId": "manual-0001",
    "transactionTime": "2026-06-01T12:00:00Z",
    "username": "ops.admin",
    "reason": "Goodwill credit",
    "points": 500,
    "expiryAfter": 30
  }'
In this example, the customer is credited 500 points that expire 30 days from the time of the addition.

​
Example: Use the Client Default Expiry

{
  "customerId": "player-123",
  "transactionId": "manual-0002",
  "username": "ops.admin",
  "reason": "Goodwill credit",
  "points": 500
}
In this example, expiryAfter is omitted, so the credited points follow the client’s default points-expiry configuration.

Authorizations

​
apikey
string
header
required
​
secretkey
string
header
required

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.

Example:

"cust_abc12345xyz67890"

​
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.

Example:

"txn543211"

​
username
string
required

The username of the admin performing the manual transaction.

Example:

"admin_user"

​
reason
string
required

Reason for manually rewarding or deducting points (e.g., 'Referral bonus').

Example:

"Referral bonus"

​
email
string

Customer's email address. This is required if your account uses email-based channel merging.

Example:

"john.doe@example.com"

​
mobile
string

Customer's mobile number. This is required if your account uses mobile-based channel merging.

Example:

"+1234567890"

​
transactionTime
string<date-time>

The time of the transaction in your system (e.g., order datetime, invoice datetime). Defaults to the current time in UTC when omitted.

Example:

"2024-10-11T15:54:10.944Z"

​
points
integer

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
number

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
integer | null

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.

Required range: x >= 0
Example:

30

Response

Manual transaction added successfully

​
customerId
string

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
number

The unique identifier for the transaction within Gameball.

Example:

11035201

​
transactionId
string

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
number

The number of points rewarded or deducted in the transaction.

Example:

50

​
amount
number

The monetary value processed in the transaction.

Example:

5