Skip to main content

Voyado Engage

Get promotions for contact

This endpoint is used to fetch all available promotions assigned to a contact:

GET /api/v2/contacts/{contactId}/promotions

You will need the unique contactId of the contact. If you don’t have it, you can use this endpoint to get it.

Getting the promotions

When calling this endpoint you can add a query-string parameter redemptionChannelType to filter the response.

The value of redemptionChannelType can be either ECOM, POS or OTHER. Here's how that looks:

GET /api/v2/contacts/67ea9958-0e09-484f-b4c4-aa3e00e1e24c/promotions?redemptionChannelType=ECOM

If this parameter is left out, then all promotions for this contact will be returned.

The response will look something like this:

[
  {
    "id": "a08c6a49-41b1-4f04-978f-adce009e081a",
    "externalId": 123214-413434-413443,
    "type": "Multichannel",
    "name": "3 for 2 Jeans",
    "expiresOn": null,
    "heading": null,
    "description": null,
    "redeemed": false,
    "redeemedOn": null,
    "imageUrl": null,
    "link": null,
    "redemptionChannels": [
      {
        "type": "ECOM",
        "valueType": "EXTERNALOFFER",
        "value": "DISCOUNTCODE",
        "instruction": “This is just an instruction”
      }
    ]
  },
  {
    "id": "594d98e1-ef73-40e3-9799-add400eaab05",
    "externalId": null,
    "type": "Multichannel",
    "name": "20% off t-shirts",
    "expiresOn": "2023-11-02T23:59:59+01:00",
    "heading": "You get a discount!",
    "description": "Hope you will enjoy this gift. ",
    "redeemed": false,
    "redeemedOn": null,
    "imageUrl": "https://images.eclub.se/images/voyadodemoeng/64DC1720689E4F5A0E1EAD92F3E9A6AFC0863D18.jpg",
    "link": "https://www.shop.com/sv-se/man/t-shirts/mfavouritetee-901-s-21350901003",
    "redemptionChannels": [
      {
        "type": "POS",
        "valueType": "PERCENT",
        "value": 20,
        "instruction": null
      }
    ]
  },
  {
    "id": "3cb87804-6b3b-4f24-a15a-ae8a00e0eacf",
    "externalId": null,
    "type": "Multichannel",
    "name": "Monetary discount 10€",
    "expiresOn": "2022-05-15T23:59:59+02:00",
    "heading": null,
    "description": null,
    "redeemed": true,
    "redeemedOn": "2022-05-03T13:39:49+02:00",
    "imageUrl": null,
    "link": null,
    "redemptionChannels": [
      {
        "type": "POS",
        "valueType": "MONEY",
        "value": {
            "currency": "EUR",
            "amount": 10
          }
        "instruction": null
      }
    ]
  }
]

Redemption channels

The object redemptionChannels in the response specifies if a promotion is a percentage, a monetary amount to be withdrawn from the total amount of the receipt, or an external discount code that refers to a price rule in your platform.

redemptionChannels.type declares which channel the promotion applies to.

redemptionChannels.valueType declares which type of discount we want to assign (percentage, monetary or external code).

redemptionChannels.value is the percentage, monetary amount or the external code referring to the external price rule. With a monetary discount we also expose the group currency set in Engage for the specific client.

redemptionChannels.instruction is an instruction that can be added to the promotion by the Engage user to, for example, give some information to store staff regarding the promotion.

These can be displayed in all currencies declared for the client installation of Engage.

A POS promotion with a percentage discount
"redemptionChannels": [
    {
        "type": "POS",
        "valueType": "PERCENT",
        "value": 15,
        "instruction": "POS instructions."
    }
]
An e-com promotion with an external discount code
"redemptionChannels": [
    {
        "type": "ECOM",
        "valueType": "EXTERNALOFFER",
        "value": "DISCOUNTCODE",
        "instruction": "POS instructions."
    }
]
A POS promotion with a monetary discount
"redemptionChannels": [
    {
        "type": "POS",
        "valueType": "MONEY",
        "value": {
            "currency": "EUR",
            "amount": 10
        }
    }    
]