The points API
All points changes over the API are done through the v3/point-accounts endpoints.
Note
One use of the points API is when Engage is acting as point follower. See here for more on this.
Terms and parameters
Some terms and parameters are useful to know before going into detail:
Point definitions: The "type" of points. Currently one point definition exists but the system allows for different kinds of points to be tracked in parallel, each with their own point definition value. Parameter is definitionId.
Point accounts: Points of different types are separated by their point definition value. This allows contacts to have many independent point totals and histories (accounts) each uniquely defined by a contact ID plus a definition ID. Parameter is accountId.
Point transactions: A transaction or update to a transaction containing a change to a contact's points.
Active points: The points a contact currently "has" that can be used to create vouchers.
Pending points: Points with a validFrom date in the future, that will not become active until then.
The offset and count parameters: Optional parameters that can be used to pagination the results.
The filter parameter: Can be "All", "Active", "Pending" or left blank. Used to return active points, pending points, or both.
Changes from v2 to v3
Several changes were made in these endpoints for v3. See the full list here.
Important
One important change is that in v3 a contact's total points (bonus points) are no longer returned from /contactoverview. This can now only be done through a separate GET request to the already existing but slightly changed /point-accounts endpoint. See the next section for details.
Point accounts
To get all of a contact's point accounts, use this endpoint:
GET api/v3/point-accounts
The contactId is sent as a parameter in the query string. This returns all point accounts like this:
{
"links": [],
"count": 2,
"offset": 0,
"items": [
{
"balance": 110,
"balanceExpires": "2023-08-14T13:03:52.0510384+02:00",
"contactId": "efaaefb8-e07a-46d5-89fa-1423e87b0798123111",
"definitionId": 1,
"id": 9,
"pendingPoints": 0,
"links": [
{
"id": 1,
"href": "https://yoururl/api/v3/point-accounts/definitions/1",
"method": "GET",
"rel": "definition"
},
{
"href": "https://yoururl/api/v3/point-accounts/transactions?accountId=9",
"method": "GET",
"rel": "transactions"
}
]
},
{
"balance": 110,
"balanceExpires": "2023-08-14T13:03:52.0510384+02:00",
"contactId": "efaaefb8-e07a-46d5-89fa-1423e87b0798123111",
"definitionId": 2,
"id": 9,
"pendingPoints": 0,
"links": [
{
"id": 1,
"href": "https://yoururl/api/v3/point-accounts/definitions/1",
"method": "GET",
"rel": "definition"
},
{
"href": "https://yoururl/api/v3/point-accounts/transactions?accountId=9",
"method": "GET",
"rel": "transactions"
}
]
}
],
"totalCount": 2
}If you know the unique ID of the point account, you can get the information directly by using the ID in the path. For example:
GET api/v3/point-accounts/fa1de1de-427d-4a63-8f43-513fc8b5e97b
This returns the following:
{
"balance": 110,
"balanceExpires": "2023-08-14T13:03:51.9719335+02:00",
"contactId": "af687249-b52a-4926-8591-ccf881b59e9e",
"definitionId": 1,
"id": 1234567899,
"pendingPoints": 0,
"links": [
{
"id": 1,
"href": "https://yoururl/api/v3/point-accounts/definitions/1",
"method": "GET",
"rel": "definition"
},
{
"href": "https://yoururl/api/v3/point-accounts/transactions?accountId=9",
"method": "GET",
"rel": "transactions"
}
]
}The links section contains optional information with some useful API calls you can use.
Point transactions
There are two endpoints used for fetching (and posting) individual points transactions.
Getting point transactions
To get a list of transactions that have generated points, use this endpoint:
GET api/v3/point-transactions
Send the point account ID in the query string as the parameter id.
The optional parameters offset and count can be used to paginate the results.
The optional parameter filter can also be used to fetch active points, pending points or both.
The optional parameter sortBy lets you sort the results on transaction date or created-on date.
With the optional parameter sortOrder you can order the results in ascending or descending order.
As an example. this request returns all pending points transactions for the given point account ID:
GET api/v3/point-transactions?id=55579bfd-718a-496e-bd80-50e5ec5b0d2b145&filter=pending
Adding point transactions
To add point transactions to Engage, or adjust existing points, use this endpoint:
POST api/v3/point-accounts/transactions
The transaction data is sent in the request body, in this JSON format:
[
{
"contactId": "111111fa6-103b-459b-8d01-b6c000e8e26a",
"amount": 12,
"definitionId": 1,
"timeStamp": "2023-06-01T08:40:51.658Z",
"source": "Purchase",
"description": "Gilded gauntlets",
"validFrom": "2023-06-16T08:40:51.658Z",
"validTo": "2024-06-16T08:40:51.658Z"
}
]Many transactions can be sent in this array, up to a maximum of 1000.
The points amount (12 in this case) will be added to the point account defined by this contact ID and definition ID. If no point account exists for that contact ID and definition ID, then one will be created and used.
Common values for source are "Purchase", "Adjustment" and "Return". Other values are also available.
Since the points in this example have a validFrom date that's in the future from the purchase date, these points will be pending until then. When that date arrives, they will change to active.
A successful POST to this endpoint gets a HTTP 202 Accepted response. Otherwise you'll get:
400 Too many items, New point system not active
Getting a specific transaction
You can fetch the information for a specific point transaction if your know its unique transaction ID:
GET api/v3/point-transactions/{id}
This returns the transaction with that ID (assuming it exists) in the following format:
{
"accountId": 1,
"amount": 800,
"createdOn": "2022-11-16T13:17:54+00:00",
"description": "Some text",
"id": 1,
"modifiedOn": "2022-12-16T00:05:21+00:00",
"source": "Adjustment",
"transactionDate": "2022-11-16T14:17:54+01:00",
"type": "Adjustment",
"validFrom": "2016-11-16T14:17:54+01:00",
"validTo": "2017-11-16T23:59:59+01:00",
"retailTransactionLineItemId": "d5ad8be8-6785-4922-95fe-b12500d3ff91"
"links": [
...
]
}Note
The value of retailTransactionLineItemId allows you to link this particular point transaction back to the exact line item that caused it.