Transaction Management

Manage customer transactions by listing all transaction details or manually adding points. Track all customer activities, including rewards and deductions.

Available APIs

GET - Transactions

https://api.gameball.co/api/v4/integrations/transactions

This API retrieves a paged list of transactions from Gameball, allowing for optional filtering. Each transaction record includes details such as type, direction, points, amount, transaction time, and balance changes, providing a comprehensive view of customer activity.

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

Query Parameters

direction string Optional Direction of the transaction:

+ Accumulation (points or rewards added to the customer).
- Deduction (points or rewards removed from the customer).

status string Optional Represents the current status of the transaction. Possible values are:

Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.

startAfter long Optional Specifies the page will start after which transaction id. Defaults to 0.

limit integer Optional Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page.

customerId string Optional 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. This is used to filter the transactions of the specified customer.

Response

application/json

transactions array List of transactions.

Transaction object

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.

gameballTransactionId string Unique identifier for the transaction in the Gameball system.

type string Type of the transaction.

AchievementReward: Captured when a customer reaches a VIP tier, participates in a reward campaign, or makes a referral.
PaymentReward: Recorded for rewarding a customer with points for every placed order.
Refund: Captured when points redeemed from a refunded order are returned to the customer.
Redemption: Recorded whenever a customer redeems their points for rewards.
Expiry: Captured when a customer's points expire, indicating a reduction in their total points.
Cancel: Recorded when a customer cancels an order, leading to the deduction of rewarded points.
Migration: Captured during updates or migrations of customer data via a CSV file, reflecting added or deducted points.
ManualAccumulation: Recorded for points that are manually added to a customer's balance.
DiscountCode: Captured when a customer creates a coupon code.
ManualDeduction: Recorded for points manually removed from a customer's balance.
ManualReward: Similar to AchievementReward, but specifically for manually awarding achievements to a customer.

direction string Direction of the transaction:

+ Accumulation
- Deduction

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.

points number Number of points involved in the transaction.

amount number Monetary value associated with the transaction.

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

status string Status of the transaction, represented by the following values:

Active: The transaction is completed, and any rewards or points have been applied successfully. Example: A customer earned 100 points after purchasing a product, and the transaction is fully processed.
Pending: The points or rewards from the transaction are temporarily on hold during the return window or any other pending period. Example: A customer earned 200 points, but the points are pending for 10 days due to the return policy.
Blocked: The transaction was flagged for potential fraud or another issue and is currently blocked from processing. Example: A transaction involving suspicious activity was blocked, preventing the rewards from being applied.
Expired: Points or rewards from the transaction have expired and are no longer available for use. Example: A customer’s 50 points expired because they were not used within the allowed timeframe.

couponCode string The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer.
Example : couponCode:"SAVE20" indicates the specific coupon the customer redeemed for a discount.

isCouponUsed boolean Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again.
Example: true means the customer has successfully used the coupon in this transaction.

couponType string The type of the coupon code that the customer has redeemed during the redemption transaction. This value categorizes the coupon based on its nature in the redemption process and can be one of the following:
- free_shipping: Provides free shipping on the order.
- percentage_discount: Offers a discount based on a percentage of the total amount.
- fixed_discount: Grants a fixed monetary discount on the total amount.
- free_product: Allows the customer to receive a specific product for free.
- fixed_rate_discount: Offers a discount with a predetermined fixed rate applied to the transaction.
- custom: Represents a unique discount or offer defined by the business.
Example: If a customer redeems a coupon that gives them 20% off their total purchase, the couponType would be "percentage_discount".

merchantName string Name of the merchant involved in the transaction, if any. Example: "TechGadgetStore" is the name of the store where the customer made their purchase.

branchName string Name of the branch involved in the transaction, if any. Example: "Downtown Branch" is the branch where the transaction occurred.

reason string Reason for the transaction, if applicable. Example: "Referral Bonus" could be the reason for rewarding points to the customer.

achievementName string The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable. Example: "First Purchase" represents the reward campaign that the customer has achieved and is being rewarded for in this transaction.

expiryDate string Date when the points or rewards from the transaction will expire, if applicable. Example: "2024-12-31" represents the expiry date for the earned points.

pointsBalanceBefore number The customer’s points balance before the transaction occurred. Example: The customer had 500 points before making the purchase.Then the pointsBalanceBefore will be 500.

pointsBalanceAfter number The customer’s points balance after the transaction is completed. Example: The customer had 500 points before making the purchase. After earning 100 points, the customer’s pointsBalanceAfter is now 600 points.

achievementType string Type of achievement earned during the transaction, if applicable. Example: "TierUpgrade" indicates that the customer upgraded to a new tier during this transaction.

achievedRewardCampaignId string The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign. Example: If the customer won a reward campaign called "First Order," which offered 500 points as a reward, this transaction object will have the achievedRewardCampaignId as the ID of the "First Order" reward campaign that the customer achieved.

achievedTierId number The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier. Example: 1872 represents the customer reaching the tier with this ID, and the transaction is the reward for achieving it.

count number The total number of transactions on the current page.

hasMore boolean Indicating whether there are additional transactions to be fetched beyond the current page.

Sample Response

{
    "transactions": [
        {
            "transactionId": "txn123456",
            "gameballTransactionId": "11034736",
            "type": "Cancel",
            "direction": "-",
            "customerId": "cust_12345abc",
            "points": 10,
            "amount": 10.0,
            "transactionTime": "2024-10-13T17:11:00.249",
            "status": "Active",
            "couponCode": null,
            "isCouponUsed": false,
            "couponType": null,
            "merchantName": "MERCH1234",
            "branchName": "BRANCH123",
            "reason": "trx reason",
            "achievementName": null,
            "expiryDate": "2025-10-13T17:11:00.249",
            "pointsBalanceBefore": 1164,
            "pointsBalanceAfter": 1154,
            "achievementType": null,
            "achievedRewardCampaignId": null,
            "achievedTierId": null
        },
        {
            "transactionId": "txn987657111",
            "gameballTransactionId": "11034735",
            "type": "Refund",
            "direction": "+",
            "customerId": "cust_12345abc",
            "points": 100,
            "amount": 10.0,
            "transactionTime": "2024-10-13T17:11:00.249",
            "status": "Active",
            "couponCode": null,
            "isCouponUsed": false,
            "couponType": null,
            "merchantName": "MERCH1234",
            "branchName": "BRANCH123",
            "reason": "trx reason",
            "achievementName": null,
            "expiryDate": "2025-10-13T17:11:00.249",
            "pointsBalanceBefore": 1064,
            "pointsBalanceAfter": 1164,
            "achievementType": null,
            "achievedRewardCampaignId": null,
            "achievedTierId": null
        }
    ],
    "count": 2,
    "hasMore": true
}

GET - Transactions including Customer Data

https://api.gameball.co/api/v4/integrations/transactions/customer-view

This API retrieves a paged list of transactions from Gameball, with support for optional filtering. It provides the same comprehensive transaction data as the previous version — including type, direction, points, amount, transaction time, and balance changes — but with an important enhancement: Each transaction now includes associated customer details, such as:

Customer Name
Customer Email
Customer Deletion Status

This allows for better traceability and visibility into who performed each transaction, even if the customer has since been deleted.

Security: Requires apikey and secretkey headers.

Request

Query Parameters

direction string Optional Direction of the transaction:

+ Accumulation (points or rewards added to the customer).
- Deduction (points or rewards removed from the customer).

status string Optional Represents the current status of the transaction. Possible values are:

Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.

startAfter long Optional Specifies the page will start after which transaction id. Defaults to 0.

limit integer Optional Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page.

Response

application/json

transactions array List of transactions.

Transaction object

gameballTransactionId string Unique identifier for the transaction in the Gameball system.

type string Type of the transaction.

AchievementReward: Captured when a customer reaches a VIP tier, participates in a reward campaign, or makes a referral.
PaymentReward: Recorded for rewarding a customer with points for every placed order.
Refund: Captured when points redeemed from a refunded order are returned to the customer.
Redemption: Recorded whenever a customer redeems their points for rewards.
Expiry: Captured when a customer's points expire, indicating a reduction in their total points.
Cancel: Recorded when a customer cancels an order, leading to the deduction of rewarded points.
Migration: Captured during updates or migrations of customer data via a CSV file, reflecting added or deducted points.
ManualAccumulation: Recorded for points that are manually added to a customer's balance.
DiscountCode: Captured when a customer creates a coupon code.
ManualDeduction: Recorded for points manually removed from a customer's balance.
ManualReward: Similar to AchievementReward, but specifically for manually awarding achievements to a customer.

direction string Direction of the transaction:

+ Accumulation
- Deduction

customerName string The display name of the customer associated with this transaction.

customerEmail string The email address of the customer associated with this transaction.

isCustomerDeleted boolean Indicates whether the customer has been marked as deleted in our system and is an existing customer or not.

points number Number of points involved in the transaction.

amount number Monetary value associated with the transaction.

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

status string Status of the transaction, represented by the following values:

Active: The transaction is completed, and any rewards or points have been applied successfully. Example: A customer earned 100 points after purchasing a product, and the transaction is fully processed.
Pending: The points or rewards from the transaction are temporarily on hold during the return window or any other pending period. Example: A customer earned 200 points, but the points are pending for 10 days due to the return policy.
Blocked: The transaction was flagged for potential fraud or another issue and is currently blocked from processing. Example: A transaction involving suspicious activity was blocked, preventing the rewards from being applied.
Expired: Points or rewards from the transaction have expired and are no longer available for use. Example: A customer’s 50 points expired because they were not used within the allowed timeframe.

couponCode string The code for the coupon that the customer has redeemed during the transaction. This value is present if the transaction represents a redemption process initiated by the customer.
Example : couponCode:"SAVE20" indicates the specific coupon the customer redeemed for a discount.

isCouponUsed boolean Indicates whether the coupon redeemed in this transaction has been used by the customer. This flag signifies if the coupon applied in the redemption process has already been utilized or can be redeemed again.
Example: true means the customer has successfully used the coupon in this transaction.

couponType string The type of the coupon code that the customer has redeemed during the redemption transaction. This value categorizes the coupon based on its nature in the redemption process and can be one of the following:
- free_shipping: Provides free shipping on the order.
- percentage_discount: Offers a discount based on a percentage of the total amount.
- fixed_discount: Grants a fixed monetary discount on the total amount.
- free_product: Allows the customer to receive a specific product for free.
- fixed_rate_discount: Offers a discount with a predetermined fixed rate applied to the transaction.
- custom: Represents a unique discount or offer defined by the business.
Example: If a customer redeems a coupon that gives them 20% off their total purchase, the couponType would be "percentage_discount".

merchantName string Name of the merchant involved in the transaction, if any. Example: "TechGadgetStore" is the name of the store where the customer made their purchase.

branchName string Name of the branch involved in the transaction, if any. Example: "Downtown Branch" is the branch where the transaction occurred.

reason string Reason for the transaction, if applicable. Example: "Referral Bonus" could be the reason for rewarding points to the customer.

achievementName string The name of the reward campaign associated with the transaction, indicating the specific achievement involved in the transaction, if applicable. Example: "First Purchase" represents the reward campaign that the customer has achieved and is being rewarded for in this transaction.

expiryDate string Date when the points or rewards from the transaction will expire, if applicable. Example: "2024-12-31" represents the expiry date for the earned points.

pointsBalanceBefore number The customer’s points balance before the transaction occurred. Example: The customer had 500 points before making the purchase.Then the pointsBalanceBefore will be 500.

pointsBalanceAfter number The customer’s points balance after the transaction is completed. Example: The customer had 500 points before making the purchase. After earning 100 points, the customer’s pointsBalanceAfter is now 600 points.

achievementType string Type of achievement earned during the transaction, if applicable. Example: "TierUpgrade" indicates that the customer upgraded to a new tier during this transaction.

achievedRewardCampaignId string The ID of the reward campaign associated with the transaction, indicating that the customer earned points in this transaction as a reward for achieving this campaign. Example: If the customer won a reward campaign called "First Order," which offered 500 points as a reward, this transaction object will have the achievedRewardCampaignId as the ID of the "First Order" reward campaign that the customer achieved.

achievedTierId number The ID of the tier associated with the transaction, indicating that the customer earned this transaction as a reward for reaching this tier. Example: 1872 represents the customer reaching the tier with this ID, and the transaction is the reward for achieving it.

count number The total number of transactions on the current page.

hasMore boolean Indicating whether there are additional transactions to be fetched beyond the current page.

Sample Response

Sample Request

{
    "customerId": "cust_12345abc",
    "type": "All",
    "page": 1,
    "size": 10
}

Sample Response

{
    "transactions": [
        {
            "transactionId": "txn123456",
            "gameballTransactionId": "11034736",
            "type": "Cancel",
            "direction": "-",
            "customerId": "cust_12345abc",
            "customerName": "John Doe",
            "customerEmail": "[email protected]",
            "isCustomerDeleted": false,
            "points": 10,
            "amount": 10.0,
            "transactionTime": "2024-10-13T17:11:00.249",
            "status": "Active",
            "couponCode": null,
            "isCouponUsed": false,
            "couponType": null,
            "merchantName": "MERCH1234",
            "branchName": "BRANCH123",
            "reason": "trx reason",
            "achievementName": null,
            "expiryDate": "2025-10-13T17:11:00.249",
            "pointsBalanceBefore": 1164,
            "pointsBalanceAfter": 1154,
            "achievementType": null,
            "achievedRewardCampaignId": null,
            "achievedTierId": null
        },
        {
            "transactionId": "txn987657111",
            "gameballTransactionId": "11034735",
            "type": "Refund",
            "direction": "+",
            "customerId": "cust_12345abc",
            "customerName": "Jane Smith",
            "customerEmail": "[email protected]",
            "isCustomerDeleted": true,
            "points": 100,
            "amount": 10.0,
            "transactionTime": "2024-10-13T17:11:00.249",
            "status": "Active",
            "couponCode": null,
            "isCouponUsed": false,
            "couponType": null,
            "merchantName": "MERCH1234",
            "branchName": "BRANCH123",
            "reason": "trx reason",
            "achievementName": null,
            "expiryDate": "2025-10-13T17:11:00.249",
            "pointsBalanceBefore": 1064,
            "pointsBalanceAfter": 1164,
            "achievementType": null,
            "achievedRewardCampaignId": null,
            "achievedTierId": null
        }
    ],
    "count": 2,
    "hasMore": true
}

GET - Transactions Count

https://api.gameball.co/api/v4/integrations/transactions/count

This API retrieves the total count of transactions from Gameball, allowing for optional filtering. It provides the number of transactions matching the specified criteria without returning detailed transaction records.

Security: Requires apikey and secretkey headers.

Request

Query Parameters

direction string Optional Direction of the transaction:

+ Accumulation (points or rewards added to the customer).
- Deduction (points or rewards removed from the customer).

status string Optional Represents the current status of the transaction. Possible values are:

Active: The transaction is fully completed, and any points or rewards have been successfully added or redeemed.
Pending: Points or rewards from the transaction are pending during the return window period. These points cannot be used or redeemed until the pending status is resolved. Example: A customer earned 100 points for a purchase, but the points are pending for 14 days to allow for the return period to expire.
Blocked: The transaction has been flagged and blocked due to suspected fraud or other security concerns. Example: A transaction was blocked because it triggered a fraud detection rule, preventing the rewards from being applied to the customer's account.
Expired: The points or rewards earned in this transaction have expired and are no longer available for redemption or use. Example: A customer earned 200 points, but they were not used within the valid time frame and have now expired.

Response

application/json

count number The total number of transactions available in Gameball system.

Sample Response

{
    "count": 240
}

POST - Manual Transaction

https://api.gameball.co/api/v4/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.

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.

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

username string Required The username of the admin performing the manual transaction.

reason string Required Reason for manually rewarding or deducting points (e.g., "Referral bonus").

points integer Required The number of points to be rewarded or deducted (should be positive for rewards and negative for deductions).

amount float Optional The monetary value (in system currency) associated with the transaction.

Sample Request

{
  "customerId": "cust_abc12345xyz67890",                
  "transactionId": "txn543211",             
  "transactionTime": "2024-10-11T15:54:10.944Z", 
  "username": "admin_user",                
  "reason": "Referral bonus",              
  "points": 50,                            
  "amount": 0                          
}

Response

application/json

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.

gameballTransactionId number The unique identifier for the transaction within Gameball.

points number The number of points rewarded or deducted in the transaction.

amount number The monetary value processed in the transaction.

Sample Response

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

POST - Activate Transaction

https://api.gameball.co/api/v4/integrations/transactions/{transactionId}/activate

This API is used to immediately activate loyalty points that are currently in a pending state, bypassing the configured return window duration. This endpoint overrides that duration and activates the points immediately, making them available for use by the customer without waiting for the pending return window duration to elapse.

This API is especially useful for scenarios where the client determines that the order is confirmed and the points can be safely activated ahead of schedule.

Note: Once points are activated, the action cannot be reversed via this API.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

transactionId string Required

The transaction id on your system which you want to activate.

Response

application/json

pointsActivated number Number of points that has been successfully activated by the transaction

gameballTransactionId number The unique identifier for the transaction within Gameball.

clientTransactionId string A unique identifier for a transaction in your system (e.g., order number or invoice number).

Sample Response

{
  "pointsActivated": 50, 
  "gameballTransactionId": 11035201,
  "clientTransactionId": "txn54321221",
}

PreviousHold Management NextTransaction Validation

Last updated 22 days ago