Skip to main content

The points API

Handling points over the API has received an upgrade. Here you can first see the new way to handle points in Engage, and then, for reference, the older (deprecated) way.

Adjusting points

All points changes over the API are now done through the v2/point-accounts endpoints. These endpoints can be used to see point definitions, access active and pending points, get the points awarded by individual transactions as well as add point-generating transactions from other systems outside of Engage.

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 just active points, pending points or both.

Point accounts

To get all of a contact's point accounts, use this endpoint:

GET api/v2/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/v2/point-accounts/definitions/1",
          "method": "GET",
          "rel": "definition"
        },
        {
          "href": "https://yoururl/api/v2/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/v2/point-accounts/definitions/1",
          "method": "GET",
          "rel": "definition"
        },
        {
          "href": "https://yoururl/api/v2/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/v2/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/v2/point-accounts/definitions/1",
      "method": "GET",
      "rel": "definition"
    },
    {
      "href": "https://yoururl/api/v2/point-accounts/transactions?accountId=9",
      "method": "GET",
      "rel": "transactions"
    }
  ]
}

The links section contains optional information with some useful API calls you can use.

Point definitions

To get all the available point definitions:

GET api/v2/point-accounts/definitions

The response will look like this:

[
  {
    "description": "Some description",
    "id": 1,
    "name": "Default",
    "links": []
  }
]

Caution

Currently, Engage supports only one point definition, with a value of 1. Support for using several point definitions will be added in the future.

The optional parameters offset and count can again be used to paginate the results.

You can also get one specific point definition if you already know its ID, like this:

GET api/v2/point-accounts/definitions/1

  {
    "description": "Some description",
    "id": 1,
    "name": "Default",
    "links": []
  }

Point transactions

The transaction endpoint is used for fetching (and posting) the individual transactions that have generated points, along with the points generated and other transaction information.

Getting point transactions

To get a list of transactions that have generated points, use this endpoint:

GET api/v2/point-accounts/transactions

There are two ways to fetch the list of transactions:

  • Using just the accountId returns the transactions for that particular points account. If this is used, the parameters contactId and definitionId are not required. If they are given, they will just be ignored.

  • The other way is to specify both contactId and definitionId. Both must be given.

The optional parameters offset and count can be used in both cases to paginate the results.

The optional parameter filter can also be used to fetch active points, pending points or both.

All parameters are added to the query string. This example returns all pending points transaction for the point account with accountId of 145.

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

Adding point transactions

To add point transactions to Engage, use this endpoint:

POST api/v2/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/v2/point-accounts/1234567899

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.

Engage as point follower

One example of using the new points API is the case when Engage is acting as the point follower. There is a separate article that goes into detail about how point follower works.

Adjusting points (DEPRECATED)

Engage allows you to award customers with points based on achievements. While this can be done through an automation or a manual action in the Engage UI, there is also an endpoint specifically for this.

Note that this way is now considered deprecated.

POST /api/v2/contacts/{contactId}/rewardpointtransaction

Here is an example payload:

{
  "points": 123.45,
  "description": "Points adjustment via Engage API"
}

Warning

The points amount you send here represents an adjustment to the contact's points total.

Field name

Data type

Example value

points

decimal

25.95 (Can be positive or negative)

description

string

Performed a review

A successful request gets a HTTP 200 OK response. Otherwise you'll get one of these:

  • 404: ContactNotFound, BonusCheckNotFound

  • 409: BonusCheckAlreadyRedeemed, BonusCheckExpired