getBonusHistory
Get the current user's bonus transaction history. 🔐 This method requires authorization.
Description
Fetches the authenticated user's bonus transactions, optionally filtered by type, date range, discount, module and admin flag. Resolves to an IBonusHistoryResponse, a { items, total } container rather than an array.
The API returns at most the 30 most recent transactions, newest first. total is the full count of matching transactions, so it can be larger than items.length. The method doesn't accept offset or limit yet, so transactions beyond the first 30 can't be fetched; narrow the range with dateFrom/dateTo or type instead.
Before 1.0.168 the method was declared as returning IBonusTransactionEntity[], but the endpoint has always returned a container: an account with no transactions gets {"items":[],"total":0}. Code written against the old type read .length from an object and got undefined. Read the transactions from result.items and the count from result.total.
.getBonusHistory(
,
,
,
,
,
,
,
);
Parameters schema
Schema
type: IBonusTransactionType
Transaction type to filter by: ACCRUAL, USAGE, REDUCE, REVERSAL_ACCRUAL, REVERSAL_USAGE or EXPIRATION.
dateFrom: string
Start of the date range. Full ISO date-time (2026-01-01T00:00:00.000Z); a bare date answers 400 dateFrom must be a ISOString.
dateTo: string
End of the date range. Full ISO date-time (2026-12-31T00:00:00.000Z); a bare date answers 400 dateTo must be a ISOString.
discountId: number
Return only transactions of this discount ID.
moduleId: number
Return only transactions from this module, for example 2 for forms or 12 for orders.
isAdmin: boolean
When true, return only manual adjustments made by an administrator.
offset: number
Number of transactions to skip, 0 or more. Default: 0.
example: 0
limit: number
Maximum number of transactions to return, 1 or more. Default: 30.
example: 30
Examples
Minimal example
const response = await Discounts.getBonusHistory();
Example with optional parameters
const response = await Discounts.getBonusHistory(
'ACCRUAL',
'2026-01-01T00:00:00.000Z',
'2026-12-31T23:59:59.000Z'
);
Example response
{
"items": [],
"total": 0
}
Response schema
Schema: IBonusHistoryResponse
items: IBonusTransactionEntity[]
Up to 30 most recent matching transactions, newest first.
items.balanceId: number
ID of the bonus balance.
items.amount: string
Transaction amount. The API returns it as a decimal STRING, e.g. "100.00" (despite the swagger declaring it a number) — parse it before doing arithmetic.
items.type: IBonusTransactionType
Transaction type.
items.discountId: number
Discount ID.
items.moduleId: number
ID of the module that produced the transaction, for example 2 for forms or 12 for orders.
items.entityIdentifier: string
Identifier of the source entity in its module, such as an order ID or a form marker.
items.comment: string
Comment.
items.isAdmin: boolean
Whether an administrator made the transaction manually.
items.remainingAmount: string | null
Remaining amount (for FIFO usage/expiration). Decimal STRING like "100.00" on accruals, null on reductions.
items.triggerType: 'EVENT' | 'SCHEDULED'
What triggered the transaction: "EVENT" or "SCHEDULED".
items.expiresAt: string
When the accrued bonus expires; null if it doesn't expire.
items.createdAt: string
Creation date.
total: number
How many transactions the filter matches in total.