Skip to main content

Pending points

Pending points are a new Engage feature powered by the latest version of points. To get more detailed information about the updated API for points, including for pending points, go here.

About pending points


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 via the API

For this, you use the following endpoint, sending the accountId of the points account you are interested in By adding the filter parameter as shown you will return only pending points:

GET api/v2/point-accounts?accountId=145&filter=pending

Or, if you know the contactId, you can use this to return the balance of all this contact's point accounts (again adding filter as "pending"):

GET api/v2/point-accounts?contactId={contactId}&filter=pending

Fetching pending point transactions via the API

To get the pending point transactions for a contact, you can make a call using the accountId for the points, with the filter parameter as shown:

GET api/v2/point-accounts/transactions?accountId=145&filter=pending

Alternatively, you can use the contactId and the point definitionId together, again adding the filter parameter as "pending":

GET api/v2/point-accounts/transactions?contactId={contactId}&definitionId=1&filter=pending

Creating pending points through the API

Points can also be created as pending when added through this endpoint:

POST /api/v2/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.

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.


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.