Manage customer transactions by listing all transaction details or manually adding points. Track all customer activities, including rewards and deductions.
This API is used to get list of transactions from Gameball. The result is paged and can be filtered.
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
directionstringOptional
Direction of the transaction:
+ Accumulation (points or rewards added to the customer).
- Deduction (points or rewards removed from the customer).
statusstringOptional
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.
pageintegerOptional
The page number of the results. Defaults to 1.
limitintegerOptional
Specifies the number of transactions to be returned per page. Defaults to 50, with a maximum limit of 200 transactions per page.
customerIdstringOptional
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
transactionsarray
List of transactions.
Transaction object
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.
gameballTransactionIdstring
Unique identifier for the transaction in the Gameball system.
typestring
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.
directionstring
Direction of the transaction:
+ Accumulation
- Deduction
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.
pointsnumber
Number of points involved in the transaction.
amountnumber
Monetary value associated with the transaction.
transactionTimestring
The time of the transaction in your system (e.g., order datetime, invoice datetime).
statusstring
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.
couponCodestring
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.
isCouponUsedboolean
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.
couponTypestring
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".
merchantNamestring
Name of the merchant involved in the transaction, if any.
Example: "TechGadgetStore" is the name of the store where the customer made their purchase.
branchNamestring
Name of the branch involved in the transaction, if any.
Example: "Downtown Branch" is the branch where the transaction occurred.
reasonstring
Reason for the transaction, if applicable.
Example: "Referral Bonus" could be the reason for rewarding points to the customer.
achievementNamestring
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.
expiryDatestring
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.
pointsBalanceBeforenumber
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.
pointsBalanceAfternumber
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.
achievementTypestring
Type of achievement earned during the transaction, if applicable.
Example: "TierUpgrade" indicates that the customer upgraded to a new tier during this transaction.
achievedRewardCampaignIdstring
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.
achievedTierIdnumber
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.
total number
Represents the total number of transactions available across all pages.
count number
Indicates the number of transactions retrieved for the current page.
The API call adds or deducts points for a customer through a manual transaction. This allows for flexibility in managing customer loyalty points based on specific circumstances or adjustments.
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
Body
application/json
customerIdstringRequired
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.
emailstringOptional
Customer's email address.
mobilestringOptional
Customer's mobile number.
transactionIdstringRequired
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.
transactionTimestringRequired
The time of the transaction in your system (e.g., order datetime, invoice datetime).
usernamestringRequired
The username of the admin performing the manual transaction.
reasonstringRequired
Reason for manually rewarding or deducting points (e.g., "Referral bonus").
pointsintegerRequired
The number of points to be rewarded or deducted (should be positive for rewards and negative for deductions).
amountfloatOptional
The monetary value (in system currency) associated with the transaction.
Here is the updated list of attributes with the required and optional tags:
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.