v4.0 (Beta)

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.

page integer Optional The page number of the results. Defaults to 1.

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:

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

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

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

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

total number Represents the total number of transactions available across all pages.

count number Indicates the number of transactions retrieved for 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
        }
    ],
    "total": 2,
    "count": 2
}

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.

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

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

Here is the updated list of attributes with the required and optional tags:

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.

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.

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
}

PreviousHold ManagementNextTransaction Validation

Last updated