> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# List Transactions
> Retrieve customer transaction history with filtering and pagination options.
## List 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.
**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.
## OpenAPI
````yaml GET /api/v4.0/integrations/transactions
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/transactions:
get:
description: >-
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.
parameters:
- name: direction
in: query
schema:
type: string
description: >-
Direction of the transaction: + (Accumulation - points or rewards
added to the customer), - (Deduction - points or rewards removed
from the customer).
- name: status
in: query
schema:
type: string
description: >-
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), Blocked (The transaction has been flagged and blocked due
to suspected fraud or other security concerns), Expired (The points
or rewards earned in this transaction have expired and are no longer
available for redemption or use).
- name: startAfter
in: query
schema:
type: integer
description: >-
Specifies the page will start after which transaction id. Defaults
to 0.
- name: limit
in: query
schema:
type: integer
default: 50
description: >-
Specifies the number of transactions to be returned per page.
Defaults to 50, with a maximum limit of 200 transactions per page.
- name: customerId
in: query
schema:
type: string
description: >-
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.
responses:
'200':
description: Transactions retrieved successfully
content:
application/json:
schema:
type: object
properties:
transactions:
type: array
items:
type: object
properties:
transactionId:
type: string
description: >-
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: txn123456
gameballTransactionId:
type: string
description: >-
Unique identifier for the transaction in the
Gameball system.
example: '11034736'
type:
type: string
description: >-
Type of the transaction. Possible values:
AchievementReward, PaymentReward, Refund,
Redemption, Expiry, Cancel, Migration,
ManualAccumulation, DiscountCode, ManualDeduction,
ManualReward.
example: Cancel
direction:
type: string
description: >-
Direction of the transaction: + (Accumulation), -
(Deduction).
example: '-'
customerId:
type: string
description: >-
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_12345abc
points:
type: number
description: Number of points involved in the transaction.
example: 10
amount:
type: number
description: Monetary value associated with the transaction.
example: 10
transactionTime:
type: string
format: date-time
description: >-
The time of the transaction in your system (e.g.,
order datetime, invoice datetime).
example: '2024-10-13T17:11:00.249'
status:
type: string
description: >-
Status of the transaction: Active (The transaction
is completed, and any rewards or points have been
applied successfully), Pending (The points or
rewards from the transaction are temporarily on hold
during the return window or any other pending
period), Blocked (The transaction was flagged for
potential fraud or another issue and is currently
blocked from processing), Expired (Points or rewards
from the transaction have expired and are no longer
available for use).
example: Active
couponCode:
type: string
description: >-
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: null
isCouponUsed:
type: boolean
description: >-
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: false
couponType:
type: string
description: >-
The type of the coupon code that the customer has
redeemed during the redemption transaction. Possible
values: free_shipping, percentage_discount,
fixed_discount, free_product, fixed_rate_discount,
custom.
example: null
merchantName:
type: string
description: >-
Name of the merchant involved in the transaction, if
any.
example: MERCH1234
branchName:
type: string
description: >-
Name of the branch involved in the transaction, if
any.
example: BRANCH123
reason:
type: string
description: Reason for the transaction, if applicable.
example: trx reason
achievementName:
type: string
description: >-
The name of the reward campaign associated with the
transaction, indicating the specific achievement
involved in the transaction, if applicable.
example: null
expiryDate:
type: string
format: date-time
description: >-
Date when the points or rewards from the transaction
will expire, if applicable.
example: '2025-10-13T17:11:00.249'
pointsBalanceBefore:
type: number
description: >-
The customer's points balance before the transaction
occurred.
example: 1164
pointsBalanceAfter:
type: number
description: >-
The customer's points balance after the transaction
is completed.
example: 1154
achievementType:
type: string
description: >-
Type of achievement earned during the transaction,
if applicable.
example: null
achievedRewardCampaignId:
type: string
description: >-
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: null
achievedTierId:
type: number
description: >-
The ID of the tier associated with the transaction,
indicating that the customer earned this transaction
as a reward for reaching this tier.
example: null
count:
type: number
description: The total number of transactions on the current page.
example: 2
hasMore:
type: boolean
description: >-
Indicating whether there are additional transactions to be
fetched beyond the current page.
example: true
security:
- apiKey: []
secretKey: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````