POST /api/v4.0/integrations/transactions/manual

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.

post/api/v4.0/integrations/transactions/manual

Request body

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

emailstring

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

mobilestring

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

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

transactionTimestring date-time

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.

usernamestring required

The username of the admin performing the manual transaction.

reasonstring required

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

pointsinteger

The number of points to be rewarded or deducted. Provide either points or amount. Positive values add points, and negative values deduct points.

amountnumber

The monetary value, in system currency, associated with the transaction. Provide either points or amount. Positive values add points, and negative values deduct points.

expiryAfterinteger nullable

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 request

{
  "customerId": "cust_abc12345xyz67890",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "transactionId": "txn543211",
  "transactionTime": "2024-10-11T15:54:10.944Z",
  "username": "admin_user",
  "reason": "Referral bonus",
  "points": 50,
  "expiryAfter": 30
}

Response

Manual transaction added successfully

customerIdstring

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.

gameballTransactionIdnumber

The unique identifier for the transaction within Gameball.

transactionIdstring

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.

pointsnumber

The number of points rewarded or deducted in the transaction.

amountnumber

The monetary value processed in the transaction.

Example response

{
  "customerId": "cust_abc12345xyz67890",
  "gameballTransactionId": 11035201,
  "transactionId": "txn54321221",
  "points": 50,
  "amount": 5
}

Changes

Changed in 5 of the 38 revisions of this API.5217

Jun 3, 20267e222ea679944See the full diff
- ○
  added the new optional request property expiryAfter
  new-optional-request-property
- ○
  the request property points became optional
  request-property-became-optional
- ○
  the request property transactionTime became optional
  request-property-became-optional
- ○
  added the non-success response with the status 400
  response-non-success-status-added
Dec 17, 2025262228c134293See the full diff
- ○
  the endpoint scheme security apiKey AND secretKey was added to the API
  api-security-added
- ○
  the endpoint scheme security apiKey was removed from the API
  api-security-removed
- ○
  the endpoint scheme security secretKey was removed from the API
  api-security-removed
Sep 30, 2025788718651767429See the full diff
- ▲
  added the new required request property transactionId
  new-required-request-property
- ▲
  added the new required request property transactionTime
  new-required-request-property
- ▲
  added the new required request property username
  new-required-request-property
- ▲
  the points request property type/format changed from number/ to integer/
  request-property-type-changed
- ●
  removed the optional property newBalance from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 200 status
  response-optional-property-removed
- ○
  added the new optional request property amount
  new-optional-request-property
- ○
  added the new optional request property email
  new-optional-request-property
- ○
  added the new optional request property mobile
  new-optional-request-property
- ○
  removed the non-success response with the status 400
  response-non-success-status-removed
- ○
  added the optional property amount to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property customerId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property gameballTransactionId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property points to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property transactionId to the response with the 200 status
  response-optional-property-added
Sep 10, 202595e7f65e5afd1See the full diff
- ○
  endpoint added
  endpoint-added
Sep 2, 2025919eb7a392aa1See the full diff
- ▲
  api path removed without deprecation
  api-path-removed-without-deprecation
This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history