Pending points
Pending points are an Engage feature powered by the latest version of points. For more detailed information about the API for points, including for pending points, go here.
About pending points
Caution
This feature is only available to customers who are using the latest points calculator in Engage.
Pending points are points that are granted but that only become "real" after a configurable delay.
Active: Points with no validFrom date or one that is in the past (regular points, basically)
Pending: Points with a validFrom date in the future, after which they become active
Pending points can fetched via the points API. How this is done depends on whether you want the total number of points (the balance) or the detailed transactions showing each change for that point account.
Fetching pending point balance for a contact
To get the point account balances, you use the following endpoint, sending in the query string the contactId of the contact you are interested in.
GET api/v3/point-accounts
In the response you'll get the point account information and balance, with pendingPoints as one of the values.
Fetching pending point transactions for a contact
To get the pending point transactions for a contact, make a request with the point account ID (as id) in the query string to this endpoint.
GET api/v3/point-transactions
To get only pending points transactions, use the optional parameter filter in the query string with the value of "Pending".
Creating pending points for one or several contacts
Points can also be created as pending when added through this endpoint:
POST /api/v3/point-accounts/transactions
This is done by passing the validFrom parameter along with the other information required in the body of the request. Set validFrom it to the date in the future from which these points will change from pending to active, and now you have created pending points. Example:
[
{
"contactId": "00000000-0000-0000-0000-000000000000",
"amount": 0,
"definitionId": 0,
"timeStamp": "2024-09-26T08:01:19.710Z",
"source": "string",
"description": "string",
"validFrom": "2025-09-26T08:01:19.710Z",
"validTo": "2025-11-26T08:01:19.710Z"
}
]Adding points manually
The validFrom parameter is not used for points which are added manually or via automation flows. Points created in one of these ways will always be active immediately.
Important
When you activate pending points, a contact's already existing points will not be affected. Only points created after the activation will be able to use the pending points function.