Points

In Customer Engagement, contacts can earn points when they make purchases, or be granted them for events such as when it’s their birthday or when they sign up. Those points can then be converted to vouchers.

A points model must be configured in your Customer Engagement installation, in the Rewards module, for points to be available. Contact your Voyado AM about this.
On the contact card under the tab “Reward points” in the Customer Engagement UI, you can see all points gained by a contact.
All points changes done over the API use the v3/point-accounts endpoints, which are discussed below.

Several changes were made in the various points endpoints when moving to the v3 API. See the full list here. An important change is that in v3 a contact’s total 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 details below.

Terms and parameters

Here are some important parameters and terms when working with points: 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. The parameter used to tell point definitions apart 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 specific contact ID and a specific definition ID. The parameter for a point account is accountId. Point transactions: A transaction or an update to a transaction that specifies the changes to a contact’s points. Active points: The points that a contact currently owns which can be used to create vouchers. Pending points: Points with a validFrom date in the future, which means they will not become active points until then. Pagination in responses: Done with the optional offset and count parameters. Filter active or pending: The filter parameter which can be “All”, “Active”, “Pending” (or blank) returns active points, pending points, or both.

Get all point accounts

To get all of a customer’s point accounts, use this endpoint:

GET api/v3/point-accounts

Send the customer’s contactId as a query string parameter. This returns all of their point accounts in this form:

Point accounts response

{
  "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,
      "pointsWillExpireDueToInactivity": "2024-06-02T10:53:04.5084821+02:00",
      "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,
      "pointsWillExpireDueToInactivity": "2024-06-02T10:53:04.5084821+02:00",
      "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
}

The pointsWillExpireDueToInactivity value indicates the point in time when transactions will expire due to the expiry method “Contact inactive”, and is only applicable for this expiry method.

Get specific point account

If you know the unique ID of the point account, you can get the data for that account directly by using its ID in the path as shown here:

GET api/v3/point-accounts/fa1de1de-427d-4a63-8f43-513fc8b5e97b

This returns the following structure:

Specific point account response

{
  "balance": 110,
  "balanceExpires": "2023-08-14T13:03:51.9719335+02:00",
  "contactId": "af687249-b52a-4926-8591-ccf881b59e9e",
  "definitionId": 1,
  "id": 1234567899,
  "pendingPoints": 0,
  "pointsWillExpireDueToInactivity": "2024-06-02T10:53:04.5084821+02:00",
  "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 array contains optional information with some useful API calls you can use.The balanceExpires field indicates a point in time when the balance may change due to activation or expiration of points. However, because it depends on multiple factors, its behavior can be unpredictable. Therefore, we don’t recommend relying on this field.

Get transactions for point account

A point account ID is unique for every point account in the database. You get it using the contact ID and the /api/v3/point-accounts endpoint. Once you have the point account ID, you can then get all the detailed transactions for that particular point account, showing every time that particular contact’s points have been generated, removed or adjusted:

GET /api/v3/point-transactions

This request returns a response of this form:

All transactions for a point account

{
  "Items": [
    {
      "id": "861e728a-7037-4dc9-9907-5b38691a9c8e",
      "accountId": "33aac83b-a50c-1234-b57f-5b94b9f1a1a2",
      "description": "Test",
      "source": "Automation",
      "amount": 100,
      "type": "Addition",
      "transactionDate": "2024-09-20T11:51:29.408622+00:00",
      "createdOn": "2024-09-20T11:51:29.408622+00:00",
      "modifiedOn": "2024-09-20T11:51:29.408622+00:00",
      "validFrom": "2024-09-15T11:51:29.408622+00:00",
      "validTo": "2024-09-25T11:51:29.408622+00:00",
      "retailTransactionLineItemId": "5a3f4a1f-5f30-42c6-a333-dcaa68b3f09f"
    }
  ],
  "totalCount": 1,
  "offset": 0,
  "count": 1,
  "links": [
    ...
  ]
}

Every transaction (points change) for this account is an entry in the items array.The value of type can be “Addition”, “Deduction”, “Expiry” or “Cancellation”.

There are some optional parameters you can use to filter which results you get back:

The parameters offset and count can be used to paginate the results
The parameter filter can be used to fetch active points, pending points or both
The parameter sortBy lets you sort the results on transaction date or created-on date
With sortOrder you can order results in ascending or descending order

For example. this request returns all pending points transactions for this point account ID:

GET api/v3/point-transactions?id=55579bfd-718a-496e-bd80-50e5ec5b0d2b145&filter=pending

Point transactions descriptions

In the payload returned from /point-transactions you’ll see a “description” field. This functionality has changed somewhat in API v3.

Point transactions payload example

{
  "items": [
    {
      "id": "be5abf92-98ac-4192-b0c3-af7da42fbb5a",
      "accountId": "1096a160-af33-4f4f-b78a-5ddc284451af",
      "description": "@@(Bonus.Points) - Slim Fit T-shirt",
      "source": "Purchase",
      "amount": 719.7,
      "type": "Addition",
      ...
    },
    {
      "id": "12548f57-fbdf-1234-8b14-de9e30ce5e3a",
      "accountId": "2222a160-af60-4f4f-b78a-5ddc284451af",
      "description": "@@(ConvertedToBonusCheck)",
      "source": "RewardVoucher",
      "amount": -15000,
      "type": "Deduction",
      ...
    },
    {
      "id": "f5d27525-918c-4fb2-a71e-c90f5efbff09",
      "accountId": "7777a160-af60-4f4f-b78a-5ddc284451af",
      "description": "Plus member - extra points for purchase (45 points) - Regular Fit Sweatshirt",
      "source": "BonusPromotion",
      "amount": 449.85,
      "type": "Addition",
      ...
    }
  ],
  "totalCount": 2,
  "offset": 0,
  "count": 2,
  "links": []
}

In the above example, you’ll see that some description values contain a code, such as @@(ConvertedToBonusCheck). These codes are placeholders for a certain type of description and for each one you can configure a custom text to explain the transaction. for example, on a contact’s My Pages. Here are explanations along with suggested descriptions:

Code	Usage	Example description
@@(Bonus.Points)	When points are awarded for a purchase.	”Points awarded from purchase.”
@@(RemovedDueToTimeLimit)	When points have passed their expiry date and can no longer be used.	”Deduction for expired points.”
@@(Bonus.DeductionForDiscount)	When points are removed because of the price being discounted.	”Deduction for discount.”
@@(Bonus.DeductionForReturn)	When points are removed because of a return being made.	”Deduction for returned item.”
@@(ConvertedToBonusCheck)	When points are removed because they have been converted to a voucher.	”Points converted to voucher.”

You will need to handle this manually in your frontend, using either the texts suggested in the table, or your own customized version of them, whichever suit your needs.

Add single point transaction

This is the recommended way to add a single points transaction to a points account.

POST /api/v3/point-transactions

To add multiple points transactions at once, to one or many point accounts, can use the bulk endpoint /api/v3/point-accounts/transactions which is covered in the following section.

See request payload structure

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "transactionId": "00000000-0000-0000-0000-000000000000",
  "transactionType": "Addition",
  "amount": 0,
  "description": "string",
  "source": "Automation",
  "transactionDate": "2024-11-13T08:16:27.949Z",
  "validFrom": "2024-11-13T08:16:27.949Z",
  "validTo": "2024-11-13T08:16:27.949Z"
}

int

required

The account ID for the account you’ll be adding the transaction to.

int

required

If this transaction is coming from, for example, your e-com, then there is already a unique ID that you can use. Or you can create one and store it your own database as a reference.

See response errors

400: Bad Request
504: GatewayTimeout

If the settings for expiration are correctly set up AND the value of validTo or expireAfterMonthsInactive matches that expiration setting, these fields can both be set to blank and values will be added based on the expiration settings.

Add several point transactions

To batch-add point transactions to Customer Engagement, or adjust existing points, use this endpoint.

POST api/v3/point-accounts/transactions

The transaction data is sent in the request body:

See request payload structure

Adding several transactions at once

[
  {
    "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 the example above) 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.

See responses

202 Accepted response
400 Too many items, New point system not active

Get 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/{transactionId}

This returns the transaction with the given transaction ID (assuming it exists) in the following format:

See request payload structure

Transaction data example

{
  "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": [
    ...
  ]
}

The value of retailTransactionLineItemId allows you to link this particular point transaction back to the exact line item that caused it.

Pending points

Pending points are a Customer Engagement feature powered by the latest version of points. They can be seen as 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.

Fetch pending point balance

To get the point account balances for a customer, 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.

Fetch pending point transactions

To get the pending point transactions for a customer, 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”.

Create pending points

Points can also be created as pending for one or more contacts 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:

See request payload structure

Adding 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"
  }
]

Add points manually

The validFrom parameter is not used for points which are added manually or via automations. 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.

Webhooks

Customer Engagement provides webhooks for working with points and vouchers.

Read a general introduction to webhooks

Read about webhooks for points and vouchers

Point follower

Sometimes a customer wants to be the point master (that is, to own and calculate their end-user’s points in their own system). But they might still want to use Customer Engagement’s functionality for visualizing and adding points based on non-purchase events like engagements, birthday, reviews or whatever. In this case, Customer Engagement can be configured to be the point follower. Customer Engagement and the point master system must then sync points with each other, with the point master being the single source of truth.

Point follower, on a functional level, means that Customer Engagement stops generating points from purchases. This means also means that point based member levels, extra point on purchase and generation of reward vouchers doesn’t work.

Customer Engagement receives the current point balances for a contact from the point master system and sets the total in Customer Engagement to this value. Not that there will be no information sent about why the balance changed. The current solution for Customer Engagement as point-follower uses a combination of API endpoints and webhooks. There are three parts to the solution:

The point master sends balance-only updates via the Customer Engagement API
Customer Engagement imports the points log from an external API provided by the point master
Customer Engagement exports point adjustments to the point master via a webhook

Expand the sections below to see each stage in detail.

1 - Balance-only points update via the API

The point master needs to regularly send points updates to Customer Engagement so that both systems remain in sync. This is done using this Customer Engagement API endpoint:

POST /api/v3/point-accounts/balances

The payload has the following form:

Payload to sync points accounts

[
  {
    "contactId": "00000000-0000-0000-0000-000000000001",
    "amount": 122,
    "definitionId": 1,
    "timeStamp": "2023-05-16T12:20:03.807Z"
  }, 
  {
    "contactId": "00000000-0000-0000-0000-000000000002",
    "amount": 63,
    "definitionId": 1,
    "timeStamp": "2023-05-16T12:20:03.807Z"
  }
]

When the point master calls this endpoint, Customer Engagement receives the request and puts it into a queue. A unique transaction ID is also returned. When the job “BalanceAccountToAmountJob” is run, the queue is processed and the received point balance is then set in Customer Engagement for each of the contacts, putting Customer Engagement in sync with the point master

Track processing of request

If the point master needs to track how the requests are being processed in Customer Engagement, it can use the following endpoint along with the transaction ID it received when it posted to /api/v3/point-accounts/balances:

GET /api/v3/point-accounts/balances/status/{id}

Be aware that this endpoint is due to be deprecated. Voyado recommend not building any new workflows using this endpoint.The response from this call will be in this form:

{
  "messages": [
    {
      "message": "string",
      "timeStamp": "2023-05-17T11:03:16.947Z"
    }
  ],
  "id": "string",
  "status": "string",
  "timeStamp": "2023-05-17T11:03:16.947Z"
}

2 - Fetch points log via external API

When Customer Engagement is acting as point follower, it does not hold the points log (points history) for a contact. The point master owns all that information. Customer Engagement, however, can fetch the points log using an external API supplied by the point master, and then display it on the contact card.The API call will look something like this:

GET https://someUrl.com/fetchPointHistory?id=contactId

The value “contactId” here is the ID of the contact in question.This URL is hosted by the point master on their end.This URL needs to be entered into the Customer Engagement back-end. Your Voyado team will do this.The point master needs to ensure the response from the endpoint has this form:

[
  {
    "transactionDate": "2023-05-08T12:06:58Z",
    "amount": 1900,
    "description": "Purchase of tshirt"
  },
  {
    "transactionDate": "2023-05-08T12:02:55Z",
    "amount": 1500,
    "description": "Purchase of jeans"
  }
]

Or, if the contact in question has no points yet, the response should be an empty array:

[]

3 - Points adjustment via a webhook

If a points adjustment is made in Customer Engagement manually in the UI or by an automation, and Customer Engagement is acting as point follower, then that adjustment is not made right away. Instead it is sent as a request to the point master system. This is done using a webhook, provided by the point master and configured in Customer Engagement.Once the point master has received the update, the points change will only be visible in Customer Engagement when the point master performs its next sync (see step 1 for how that works).Points adjustments made in Customer Engagement when it is acting as point follower might not have an immediate effect. You might have to wait for the next sync from the point master.The data sent over the webhook has the following form:

{
  "eventType": "loyalty.addPoints",
  "id": "70b84f00-d212-47c0-a56d-feaab6294333",
  "payload": "FtaW9DkGDs8yZGxkHU5Urh5B3fYpdjJylVwlCMUj1YlqcJ+9VVxO5dIhawwF2mbDJIkP1B9IVTM9+he86ZFBcIzGLr3K9nhH1hXuc0527Pkruan5TGsanjj4Kf2+7ZueY2FG6Vu5+nEuecxsDBgREyHOynieMBKRlBn3b1AVq7vw9D3dMdE6PpDGKFVAqrxrfP8jmmnPCn7orP4qAIxq6X67D8Jya4bs6ixJvZ66HPUwkmg0cEKiAhtgUlZko9XXMMPJUvHssQuIe6zhfx2r/bH9zwfbKPCNuTQ9q74iSc2CoA9akwCgk/f+PqnYspSznEnBvbwBUYlNoq39MOjjAtoMOoZD8+Jb3SGV9UxL8rHroSlOEttp1c7mX61UFIFCdo/OluCc54ycrjIx9Jgmww==",
  "tenant": "pointfollower"
}

The payload part is encrypted. The encryption key used must be entered into the Customer Engagement back-end, and also communicated separately to the point master system so they can perform the decryption with the same key. Once decrypted, the form of the payload will depend on whether the points adjustment was done via an automation, or manually in the Customer Engagement UI.

Points adjustment via automation

In this case, the decrypted payload will look like this:

{
  "contactId": "1dfe06cd-a1be-4423-8ed4-afd900d998aa",  
  "amount": 40,
  "description": "Points awarded",
  "source": "Automation",
  "pointDefinitionId": 1,
  "reason": "Voyado",
  "processId": "d6342090-7410-4c00-aa4b-dbd394dac7e6",
  "workflowId": "44931e65-e188-46c4-92bd-50e4818fece2",
  "workflowName": ""
}

The attributes ProcessId, WorkflowId and WorkflowName refer to the automation.

Points adjustment manually

In this case, the decrypted payload will look like this:

{
  "contactId": "1dfe06cd-a1be-4423-8ed4-afd900d998aa",  
  "amount": 40,
  "description": "Give points from Engage",
  "source": "Manual",
  "pointDefinitionId": 1,
  "userId": "c23f28cb-d62d-42cf-9d11-b919198409ea",  
  "userName": "Jimmy User",  
}

The userId and userName here refer to the user who made the change in Customer Engagement.The point master system can now read the points adjustment and apply it.

View points in Customer Engagement

As mentioned, when Customer Engagement is point follower, adjustments are not applied directly, but instead sent to the point master using the webhook, and from there back to Customer Engagement via the API when the next sync happens.

It’s important that the webhook from the point master is configured in Customer Engagement before the customer starts using it, or else points updates from automations and so on will be missed.

In the Customer Engagement UI, the user can view the points added and sent out:

The Customer Engagement UI acts as an iFrame for showing point transactions after collecting them though the point master’s API.

Return matching

When a return is made, certain adjustments need to be made in Customer Engagement to the item and, if relevant, to the points.

Contacts

Transactions

Orders

Loyalty

Product data

Ratings and Reviews (BETA)

Product Discovery

Terms and parameters

Get all point accounts

Get specific point account

Get transactions for point account

Point transactions descriptions

Add single point transaction

Add several point transactions

Get a specific transaction

Pending points

Fetch pending point balance

Fetch pending point transactions

Create pending points

Add points manually

Webhooks

Read a general introduction to webhooks

Read about webhooks for points and vouchers

Point follower

Track processing of request

Points adjustment via automation

Points adjustment manually

View points in Customer Engagement

Return matching

See how return matching is done here

​Terms and parameters

​Get all point accounts

​Get specific point account

​Get transactions for point account

​Point transactions descriptions

​Add single point transaction

​Add several point transactions

​Get a specific transaction

​Pending points

​Fetch pending point balance

​Fetch pending point transactions

​Create pending points

​Add points manually

​Webhooks

Read a general introduction to webhooks

Read about webhooks for points and vouchers

​Point follower

​Track processing of request

​Points adjustment via automation

​Points adjustment manually

​View points in Customer Engagement

​Return matching

See how return matching is done here

Terms and parameters

Get all point accounts

Get specific point account

Get transactions for point account

Point transactions descriptions

Add single point transaction

Add several point transactions

Get a specific transaction

Pending points

Fetch pending point balance

Fetch pending point transactions

Create pending points

Add points manually

Webhooks

Point follower

Track processing of request

Points adjustment via automation

Points adjustment manually

View points in Customer Engagement

Return matching