` containers anywhere in your HTML. These containers must be pure HTML, they *cannot* be injected by GTM. They must be part of your page templates.
For all widgets below set **all** the following attributes on each container, in this order:
| Attribute | Required | Description |
| - | - | - |
| `data-product-group-id` | **Yes** | Product group identifier (for variant grouping) |
| `data-product-id` | **Yes** | Product identifier |
| `data-variant-id` | **Yes** | Specific variant identifier |
Example values are:
* `data-product-group-id` = "Product"
* `data-product-id` = "Product-Color"
* `data-variant-id` = "Product-Color-Size"
Here are the available widgets in more detail, along with where they are shown.
* PLP = Product Listing Page
* PDP = Product Detail Page
Either the Badge widget ("voyado-badge") or the Add Review widget ("voyado-add-review") or both must be present on the product detail page (PDP). This is to ensure that the variant structure is known when the customer writes a review in the review pop-up.
### Ratings widget (PDP & PLP)
This is an inline star \ score count. It is typically placed near the product title.
```html Ratings widget theme={null}
```
Variants:
* `voyado-ratings--small` (16 px text)
* `voyado-ratings--vertical` (stacked layout)
* Or both combined.
### Badge widget (PDP — sidebar)
This includes a large numeric score, stars, a review count and a "Review this product" CTA that opens the review popup.
```html Badge widget theme={null}
```
Variants:
* `voyado-badge--compact` for a smaller score (48 px instead of 78 px with CTA hidden)
### Summary widget (PDP)
This includes AI generated sentiment highlights from customer reviews. It is automatically hidden when there are no reviews.
```html Summary widget theme={null}
```
### Reviews widget (PDP)
This is a full review list with sort dropdown, pagination, author, date, star rating, text, verified-buyer badge, thumbs up/down voting, and comment threads. Authenticated users can edit their own reviews.
```html Reviews widget theme={null}
```
Variants:
* `voyado-reviews--boxed` wraps each review in a card
### Highlights widget (PLP / PDP)
This is a single AI-selected review excerpt including title, date, and a "Powered by Voyado" footer. It is lighter than the full Summary widget.
```html Highlights widget theme={null}
```
### Distribution widget (PDP — rating breakdown)
Five-row breakdown (5★ down to 1★), each row showing a mini star icon, the review count for that star value in parentheses, and a horizontal bar sized to that rating's share of all reviews.
This is the widget referenced internally as "rating breakdown (5★/4★/3★…)."
```html Distribution widget theme={null}
```
### Carousel widget (PDP — scrolling review cards)
A horizontally-scrolling row of review cards under the heading "What our customers are saying," with prev/next nav buttons.
Supports two optional filtering attributes not used by any other widget:
* `data-min-rating`: Include only reviews at or above this star rating (for example, 4 means show only 4 and 5 star reviews)
* `data-max-review-count`: Cap the number of review cards rendered (for example, to 10)
```html Carousel widget theme={null}
```
### Add Review widget (PDP — standalone collection button)
A standalone CTA button that opens the review-submission modal directly.
```html Add Review widget theme={null}
```
## 3 - Loading widgets
This is how the widgets are loaded:
```javascript Loading widgets theme={null}
voyado('load-widgets', [types])
```
You will replace \[types] here by the list of widgets you want to load. Available are:
* "ratings"
* "badge"
* "summary"
* "reviews"
* "highlights"
* "distribution"
* "carousel"
* "add-review"
```javascript PLP example theme={null}
voyado('load-widgets', ['ratings']);
```
```javascript PDP example theme={null}
voyado('load-widgets', ['badge', 'ratings', 'summary', 'reviews', 'distribution', 'carousel', 'add-review']);
```
Make this call to load the widgets *after* the widget containers are in the DOM.. Only use the widget types that are present on the current page; listing absent types wastes DOM searches.
### Clearing widgets
To clear the loaded widgets, call:
```javascript theme={null}
voyado('reset-widgets')
```
Call this before a SPA route change, then call `load-widgets` again after the new view is rendered.
### Keeping widget attributes in sync
It's important to always keep widget attributes in sync with the selected variant.
This means you should always ensure that the attributes `data-product-group-id`, `data-product-id` and `data-variant-id` match what the shopper is currently viewing on the page and not just contain the values present when the initial page load was done.
Whenever the shopper changes size, color, or otherwise selects a different variant, update these three attributes on *every Voyado widget present on the page* (such as .voyado-badge, .voyado-add-review, and any others you've added):
If you don't do this, the attributes will be never updated, meaning a shopper who switches variant will end up submitting — or viewing — reviews for the wrong product and/or variant.
Always keep widget attributes `data-product-group-id`, `data-product-id`, `data-variant-id` in sync with what the customer is currently viewing.
#### If no variant is selected
If the merchant hasn't selected a variant on the site (for example, the shopper is on a product page where no size or color is chosen yet), set `data-variant-id` to an empty value on the widgets.
Do *not* leave a stale variant from an earlier selection.
#### Links from review-request emails
When a visitor arrives at your site through a link in a review-request email, the link also carries a `voyado-rating-item` parameter. The script then:
* Looks for other Voyado widgets on the page, such as `voyado-badge` or `voyado-add-review`
* Reads `data-product-group-id`, `data-product-id` and `data-variant-id` from the widgets and uses only the attributes that have values
* If there is no widget, or all three attributes are empty, it will fall back to the value in `voyado-rating-item`
For example, consider when a customer buys "variant 107-blue-xl", and that value is added to the email link as the value for `voyado-rating-item`.
When the customer follows this link, the script gets this information on your site and tries to set it as `data-variant-id` in the `voyado-badge` and `voyado-add-review` widgets, but only if that attribute is empty. Here `data-product-group-id` and `data-product-id` have already been set by the script.
The script only fills in an empty `data-variant-id`. It never overwrites a value you have already set. If the shopper then selects another variant, be sure to update all three attributes as described above.
## Starting from zero
When starting off, when a product has no reviews and the goal is not to display but to start collecting, Voyado recommends using only the `add-review` widget and "Add Review" button.
When there are no reviews, other display widget either will show an empty/zero state or hides themselves, which reads as broken or unfinished to a shopper. The "Add Review" button however works identically no matter how many reviews a product has.
Once a product has a meaningful number of reviews, add the other display widgets. The "Add Review" button can still remain.
## SPA Handling
If your site uses client-side routing (single page application), call `reset-widgets` before each navigation and then `load-widgets` after the new content is in the DOM:
```js SPA Handling theme={null}
// Before navigating away
voyado('reset-widgets');
// After new view is rendered
voyado('load-widgets', ['badge', 'reviews']);
```
## CSS Customization
All visual tokens are CSS custom properties on `:root`. Override them to match your brand.
```css theme={null}
:root {
/* Colors */
--voyado-rating: #66C1BF; /* Filled star / accent */
--voyado-neutral: #D8D8D5; /* Empty star / dividers */
--voyado-text: #333333; /* Body text */
--voyado-cta-color: #437984; /* CTA button background */
--voyado-cta-text-color: #FFFFFF; /* CTA button label */
--voyado-review-interactions-color: #A7A7A7;
--voyado-trophy-color: #E1C32E;
--voyado-select-bg: #FFFFFF;
--voyado-select-border-color: #E5E5E5;
/* Typography */
--voyado-font-family: "Helvetica", sans-serif;
--voyado-font-size-large: 28px;
--voyado-font-size-medium: 22px;
--voyado-font-size-small: 16px;
--voyado-font-size-micro: 12px;
/* Star sizes */
--voyado-star-size-large: 40px;
--voyado-star-size-small: 16px;
/* Spacing */
--voyado-spacing-xs: 5px;
--voyado-spacing-sm: 10px;
--voyado-spacing-md: 20px;
--voyado-spacing-lg: 40px;
/* Accessibility */
--voyado-focus-color: #005fcc;
--voyado-focus-ring-width: 2px;
}
```
### Brand override example
```css theme={null}
:root {
--voyado-rating: #ff6b35;
--voyado-cta-color: #4a90e2;
--voyado-font-family: "Inter", sans-serif;
}
/* Or scoped to a wrapper */
.my-product-page {
--voyado-rating: #FFD700;
}
```
### CSS classes for overrides
| Class | Element |
| - | - |
| `.voyado-star--filled` | Filled star SVG |
| `.voyado-star--half` | Half-filled star |
| `.voyado-star--empty` | Empty star SVG |
| `.voyado-ratings--value` | Numeric score text |
| `.voyado-ratings--count` | Review count text |
| `.voyado-badge--score` | Large numeric score |
| `.voyado-cta` | CTA button (Badge, Rate) |
| `.voyado-review--author` | Reviewer name |
| `.voyado-review--text` | Review body |
| `.voyado-review--interactions` | Thumbs + comment row |
| `.voyado-reviews--select` | Sort dropdown |
| `.voyado-summary--title` | AI summary heading |
# Article register
Source: https://developer.voyado.com/docs/setup/article-register
Customer Engagement holds an internal article register for each tenant, containing all the articles (purchasable items) in the client's system.
The article register is used to **enrich data within Customer Engagement** like transactions and products of interest. The register can be created and updated in two ways:
* Using a product feed to populate the register
* Using sources like XML files from a PIM or ERP system
The line-items on a contact's transaction represent *articles*. By connecting these to the product data for those articles, you can more precisely segment and analyze a contact's shopping behavior.
The more data you have about a product, the more you know about the person who bought it.
## Article vs product
There is a difference between products (used for communication) and articles (used for data enrichment). These represent two separate functions and areas within the system.
In more detail:
An **article** is an individual line-item purchase on a transaction.
* For example: A certain hat.
A **product** is an article plus the other information relevant for this retail context.
* For example: That certain hat, in the color red, available at a specific store.
The **product metadata** is all the other pieces of information connected to a product.
* For example: The hat's availability, review score, number of sellers, how many variations exist...
The SKU (stock-keeping unit) is the most detailed designator for a particular article and these are always unique. Whereas article number and group number can be shared by color variants of the same product and can therefore encompass multiple SKUs.
## Article data
An article in Customer Engagement includes standard fields and some flexible extra fields configured per client installation. These “spare fields” are of two types:
* 10 "spare" string fields (spare1, spare2 ... spare10)
* 5 "spare" date/time fields (datespare1, datespare2 ... datespare5)
These fields are used to save product data.
## Article enrichment
In receipts, articles generally lack any useful product data or metadata. This is to save space in the transmission and importing of transactions, but also to allow flexibility in adding product data later. This process is known as "enrichment".
Enrichment involves linking the articles on a transaction with their product data.
### The SKU
An article's SKU code is the key to enrichment. Since an SKU exists both for the article on the transaction and in the article register, this allows the two to be connected.
The SKU is mapped to `ArticleNr` in Customer Engagement. Note that a line-item row in Customer Engagement always refers to the *most detailed version* of a specific article.
You can read more about this here:
There are many ways to integrate your systems with Customer Engagement. Here you'll see the integration best practice that Voyado recommends.
This is a *high-level* overview so data fields and JSON specifications will not be covered in any detail. If you need that, consult your Swagger page, or the other relevant parts of this documentation.
This guide assumes you'll be integrating your system to Customer Engagement *from scratch*. Customer Engagement also has prebuilt integrations (accelerators) supporting many third-party systems, enabling a faster and easier integration.
Connecting a system to Customer Engagement is always *synchronous*. So when the Customer Engagement API is called, your workflow needs to wait for a response before continuing. If Customer Engagement does *not* return a response in time, you'll need a fallback with a retry function to handle this.
First, check if the contact already exists in Customer Engagement, using this endpoint:
```http theme={null}
GET api/v3/contacts/id
```
In the query string of this request you will send some identifier of the contact, such as their email or mobile phone number.
If a contact **exists**, Customer Engagement returns their unique `contactId` value.
If a contact **doesn't exist**, you'll get error code “404 contact not found” and must proceed to the next step, where you will create a contact for this customer.
Now you know the customer does not already exist as a contact in Customer Engagement, you can create them using:
```http theme={null}
POST api/v3/contacts
```
Customer Engagement returns *HTTP Code 201* if the creation has been successful.
In the response payload you'll get a JSON with the contact's full information.
In both of the steps above, the GUID of the created contact will be returned as the `id` value in the response payload. Store this value for that contact in your own system and use it in the future for looking them up. This simplifies your flows and reduces unnecessary delays and API calls to Customer Engagement.
### Contact creation error handling
When no response is received from the Customer Engagement API, or when the response has errors, you'll need a plan in place to ensure that no data is lost.
* **Validation errors**: Here, something in the data you sent was wrong. You should follow the error instructions to ensure good data quality before you retry.
* **No-response error**: In the case of no answer, or when you get a 500 or 504 error, you should perform a retry.
If errors remain, or no response is received, you should save contact changes to *local XML files in your system* while the disruption is underway. Then, when the connection has been restored, these files can be transferred to Customer Engagement to update the contact data, in one of these two ways:
Here you copy the XML file you created to your FTP folder, where it is then uploaded to Customer Engagement and all affected contacts are updated.
When uploading XML files via the FTP, new contacts might be created, but their contact GUIDs will *not* be returned from Customer Engagement. Therefore, the next time that contact is identified, you'll need to manually check if their GUID already exists in your systems, and save it there if it doesn't.
You can send your saved contact changes to Customer Engagement using the bulk API:
```http theme={null}
POST /api/v3/contacts/bulk
```
Posting data like this puts it in a queue that Customer Engagement handles asynchronously. In the meantime, you can continue with your normal workflow.
### Updating contacts
When a customer changes some personal data (new address, new name, change in some consent) you'll need to do an update to sync those changes to Customer Engagement.
If the Customer Engagement `contactId` has been saved in your system, as recommended above, you will not need to query Customer Engagement for it first and can just continue directly to the updating. However, if the `contactId`, for whatever reason, has not been saved, then a lookup to the Customer Engagement API must be done to fetch it, using the general lookup endpoint along with some identifying information:
```http theme={null}
GET api/v3/contacts/id
```
When you have the `contactId`, the update is then done like this:
```http theme={null}
PATCH api/v3/contacts/{contactId}
```
The contact attributes to be updated are sent in the request payload.
You can't use this endpoint to update a contact's contact type. This has to be done using the `/contacts/{contactId}/updateContactType` endpoint. See the "Upgrading a contact" section below.
When updating contacts in Customer Engagement, be sure to send only the **changes**. Empty or null values sent in an update payload will overwrite any existing values which is probably not what you want.
Customer Engagement will return a *200* or *202* response code to show the request was successful.
### Contact update error handling
Like in the contact creation case, it's important to have a fallback in place for when problems occur, such as when Customer Engagement is down, or does not respond, or return error code *500* is received.
Again, if your first call is unsuccessful, perform a retry.
To fetch the full contact data use the first endpoint:
```http theme={null}
GET /api/v3/contacts/{contactId}
```
This returns a JSON with the contact's personal information (but not transactions or promotions). This is useful, for example, to get a contact's postal address, see the store where they signed up, or to display their personal information on their My Pages in your e-com.
Which information you will display and how is up to you. Customer Engagement will return all contact information and you must then filter out what you wish to show for your customer.
To fetch the contact's purchase and returns history, along with article data, use the second endpoint:
```http theme={null}
GET /api/v3/transactions
```
The `contactId` is sent as a query string parameter.
This endpoint allows you some control in paginating the response.
Purchases and returns are both present in the data received from this endpoint.
To fetch all of the contact's active promotions use the third endpoint:
```http theme={null}
GET /api/v3/promotion-assignments
```
You have the option to restrict the response by promotion type (ECOM, POS).
A promotion will be returned if both the assigned promotion AND the main promotion (the "template" it was created from) are active. Redeemed promotions may be included in this response if they otherwise fulfill the criteria for being active.
### Upgrading a contact
Customer Engagement can handle multiple contact types. For example, you might want to separate your newsletter subscribers from account holders, so you will have a contact type for each.
An account holder usually has contact type "Member". Ideally,this is where you want all your contacts to be. Changing a contact from other type to "Member" is called upgrading.
Upgrading contacts is done using the following endpoint:
```http theme={null}
POST /api/v3/contacts/{contactId}/updateContactType?contactTypeId=Member
```
When upgrading a contact to a member, it's common to *enrich* their information using the regular update method shown above.
## 3 - Transactions flow
A transaction can be seen as the "receipt" showing what the contact has bought. A transaction can contain many items, those that were purchased as well as those being returned. Transaction are sent to Customer Engagement and saved there, using `contactId` to connect them to a specific contact.
The endpoint used to save them is:
```http Save transactions to Engage theme={null}
POST /api/v3/receipts
```
The `/orders` endpoint also exists which is used to trigger automations and transactional communication. Don't confuse these two.
### Saving a transaction
1. First check if the customer already exists as a contact in Customer Engagement.
2. If they don't exist, you'll need to create them (and remember to save their `contactId` in your system for future use).
3. Now POST the purchase information to the `/receipts` endpoint shown above, with the payload data in the correct JSON format.
If you've tried to create a contact during your transaction flow, or have updated contact information, then you'll have to handle that too when the connection is down. Remember also that when uploading XML files via the FTP, contact GUIDs will *not* be returned from Customer Engagement for any new contacts created. Therefore, the next time that contact is identified, you'll need to check if their GUID already exists in your systems, and save it there if it doesn't, to reduce unnecessary API calls and improve your flow.
## 4 - Promotions flow
Promotions can be created and assigned to contacts in Customer Engagement, and then fetched for display in your e-com or POS. You will need to redeem (mark as used) any promotion that is applied to a purchase.
Some things need to be done before a promotion can be used:
1. **Set up** the promotion in your own ECOM/POS/ERP using whatever discount rules might apply.
2. Set up a **matching promotion** in Customer Engagement.
3. In Customer Engagement, **assign the promotion** to one or several contacts.
Fetch a customer's active promotions with this endpoint, using `contactId` in the query string:
```http theme={null}
GET /api/v3/promotion-assignments
```
You can select promotions based on redemption channel (for example, some might only be available offline / online) by adding the "redemptionChannelType" attribute as "POS" or "ECOM" to the query string.
In the API response, Customer Engagement returns the available promotions for that customer.
You can now use your price logic to display and apply the promotion as a deduction at checkout.
If a customer has updated their information during the purchase, Customer Engagement needs that updated information. Use the usual endpoint for updating contact data:
```http theme={null}
PATCH /api/v3/contacts/{contactId}
```
Now redeem the promotion with the `/redeem` endpoint to stop it from being used again:
```http theme={null}
POST /api/v3/promotions/codes/{promotionId}/redeem
```
This will set the promotion to “used” in Customer Engagement for that contact.
The promotion identifier should also be included in the API call that is used to register the transaction, along with the rest of the transaction's data, to allow Customer Engagement to match the receipt to the promotion.
```http theme={null}
POST /api/v3/receipts
```
### Redeem promotions error handling
You'll need a plan in place to handle when no response is received from the Customer Engagement API, or if the response has error code *500*. This is to ensure that no data is lost until the connection is restored. As always, there are two approaches here:
1. **Retry**: If your first call is unsuccessful, perform a retry.
2. **Local XML**: If errors remain, or no response is received, you should be ready to save the redeemed promotion to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Customer Engagement via the FTP server.
If you've tried to create a contact during your promotions flow, or have updated contact information, then you'll have to handle that too when the connection is down.
Remember too that when uploading XML files via the FTP, contact GUIDs will *not* be returned from Customer Engagement for any new contacts created. Therefore, the next time that contact is identified, you'll need to check if their GUID already exists in your systems, and save it there if it doesn't, to reduce unnecessary API calls and improve your flow.
## 5 - Orders flow
An order represents the goods and services being purchased (or returned) at a given point in time, whether online or in-store. Unlike a transaction, an order's data can change and may be updated multiple times throughout its life-cycle, for example when its status changes, or when line items are added, updated, or removed.
Orders are sent to Customer Engagement using the contact's `contactId`, in the same way as transactions. The endpoint used to save them is:
```http theme={null}
POST /api/v3/orders
```
### Creating an order
Creating an order in Customer Engagement consists of these steps:
Before an order is sent, always check that the contact already exists in Customer Engagement, using this endpoint:
```http theme={null}
GET /api/v3/contacts/id
```
Send an identifier such as email or mobile phone number in the query string. If the contact exists, Customer Engagement returns their `contactId`.
If not, you'll get error code *404 contact not found* and must create the contact before continuing.
If the contact doesn't already exist, create them first:
```http theme={null}
POST /api/v3/contacts
```
Store the returned `contactId` in your own system, just as you would for a transaction, so it can be reused for future orders without an extra lookup.
Once the contact is confirmed to exist, POST the order data to the orders endpoint:
```http theme={null}
POST /api/v3/orders
```
The request is validated on receipt. If the format is valid, Customer Engagement responds with *202 Request has been accepted* together with a `jobId`, which can be used to poll the `/jobstatus` endpoint and confirm when the order has finished processing.
Processing is asynchronous, so a successful *202* response does not yet mean the order is stored. If you need to trigger an action based on the order, either poll `/jobstatus` for a `Completed` status, or use an embedded order action as described below.
### Order error handling
As with contacts and transactions, you'll need a plan for when no response is received from the Customer Engagement API, or when the response contains errors.
* **Validation errors** — something in the sent data was incorrect. Follow the error instructions and correct the data before retrying.
* **No-response error** — in case of no answer, or a 500/504 error, perform a retry.
* **Contact missing** — if the order data is valid but the referenced contact doesn't exist, Customer Engagement returns status *CompletedWithErrors*. In this case, delete the order, create the contact ,and then register the order again.
If errors remain, or no response is received, save the order data to local files in your system while the disruption is underway, and resend it once the connection is restored, in the same way as the fallback used for contacts and transactions.
### Triggering automations for an order
Once an order has been processed by Customer Engagement, it can be used to trigger an automation, for example an order confirmation or shipping notification.
There are two ways to do this.
**Option 1 — Call the action endpoint with a VersionTag**
Trigger the automation by calling the action endpoint:
```http theme={null}
POST /api/v3/orders/action
```
To make sure Customer Engagement uses the correct data when communicating, this call must include a `VersionTag`. The `VersionTag` is returned once a change to the order has been processed, and can be fetched either from the `/jobstatus` endpoint after creating or updating the order, or from the `/orders` endpoint directly.
This approach requires you to first poll for the order's `Completed` status (or fetch the current `VersionTag` from `/orders`) before calling the action endpoint.
**Option 2 — Include an embedded order action**
As a simpler alternative, include an embedded order action directly in the payload when creating or updating the order:
```http theme={null}
POST /api/v3/orders
PUT /api/v3/orders/{orderId}
```
Add your instructions as an action object in the request payload. As soon as the order reaches status `Completed`, Customer Engagement automatically triggers the automation — no polling or separate call needed.
An embedded action is only executed if the order is successfully processed and reaches status `Completed`. If processing fails — for example due to a validation error — the embedded action is discarded and the automation must be triggered manually afterwards.
In short: use embedded order actions whenever possible, since they remove the need for polling. Fall back to the action endpoint with a `VersionTag` when you need to trigger an automation independently of an order being created or updated — for example, later in the order's life-cycle.
## Summary
The most important design considerations when connecting your client system to Customer Engagement from scratch are these:
1. The connection is usually synchronous, meaning you'll need to **wait for a response from Customer Engagement** before proceeding in your flow. The average response time for the API endpoints is generally short, but longer response times can happen.
2. Always have a **retry policy** in place, in case of network problems or the API slowing due to heavy traffic. Retry logic makes your solution more reliable.
3. Build any redundancy and backup solutions **on the client side**. For example, a purchase should always be possible to complete even if you can't get an answer from the Customer Engagement API in a reasonable time for your scenario.
4. Implement **error handling** for extraordinary situations when the connection to Customer Engagement is down. Do not make your vital business processes depend on Customer Engagement always being reachable.
5. Whenever possible **asynchronous flows** should be used for non-time-critical API calls, for example sending orders and transactions to Customer Engagement for storage of purchases and triggering automations.
6. Ensure that your client application can handle **heavy load** and high data volumes without exceeding the API rate limits, for example, by implementing queues for non-time-critical messages.
7. Any contact IDs returned from Customer Engagement should be **saved in your local systems** and used in following requests to avoid unnecessary traffic to Customer Engagement, to simplify and speed up look-ups, and to generally improve your customer's experience.
# Consents
Source: https://developer.voyado.com/docs/setup/consents
A consent is something that an end-user of Customer Engagement has agreed to (or not agreed to) concerning their data or their account. Proper handling of consents is important from a legal perspective. Consents turn up in the POS or, in for an e-com, on the website, and are essentially requests from the retailer which the end-user can choose to allow or deny.
An example would be: "Do you agree to receive our newsletter?"
For each contact, the consent can be in one of three states:
* **Yes** (aka True) - The contact has agreed to receive the newsletter
* **No** (aka False) - The contact does not want to receive the newsletter
* **Not set** - The contact has not yet given their answer
Once its value has been set, a consent can only have the value "Yes" or "No". It can never again revert to “Not set”. This is by design. The consent can, however, be changed between "Yes" and "No".
## Setting up consents
You can set up a consent in the Contact Attributes section of Config Hub.
![Adding attribute example]()
**Name:** The name of this consent as will be displayed in the POS or e-com.
**Id:** A unique identifier for this consent.
**Type:** Choose "Consent" here.
**Default value:** If you want the consent to have a value before it's set. Use "Not set".
The actual text shown for the contact, where they are asked to accept the consent, is made of two parts that are pasted together. These are entered as Display text and Link text:
* **Display text:** The text displayed in the POS or e-com immediately before the link part.
* **Link text:** The "link" part of the text that, when clicked on, leads to the full terms and conditions.
**Condition text:** The full terms and conditions, in HTML format (shown truncated in the image above). Normally, these would be a whole page of HTML formatted text.
Since Customer Engagement does no versioning of fields, the condition text is often stored at an external URL, managed by the customer. Your Voyado team will help you with setting this up.
The other settings are the same as for all custom attributes. Read more about those [here](https://help.engage.voyado.com/hc/en-gb/articles/23406421398428-Contact-attributes).
Be sure to hit "Save" when you are finished to save the consent in Customer Engagement.
As seen in the image above, the texts in these three fields can be localized following the standard for language culture names (sv-SE, en-GB, fr-FR and so on).
## Seeing all consents for a tenant
There can be more than one consent in use. To see the all consents for a tenant, this endpoint is used:
```http theme={null}
GET /api/v3/consents
```
This returns a JSON array with all the consents for that tenant (or an empty array if there are no consents). Note that this holds no information about how individual contacts have responded to the consents.
```json See all consents theme={null}
[
{
"name":"Consent for Prescription Purchase",
"id":"consentRX",
"metaData":{
"displayText":{
"en-GB":"I consent to Rx purchases."
},
"linkText":{
"en-GB":"Read the terms here."
},
"conditionText":{
"en-GB":"The terms as a HTML block."
}
}
},
{
"name":"Consent for Membership Terms",
"id":"consentMemberTerms",
"metaData":{
"displayText":{
"en-GB":"Yes, I consent."
},
"linkText":{},
"conditionText":{}
}
}
]
```
## Getting a contact's consent states
By fetching a contact's data using the /contactoverview endpoint, you can see what consents exist for this contact, and what their state is.
```json See consents for a contact theme={null}
{
"firstName": "Example",
"email": "example@example.com",
"countryCode": "SE",
"contactType": "ExampleContactType",
"preferences": {
"acceptsEmail": true,
"acceptsPostal": true,
"acceptsSms": true
},
...
"consents": [{
"id": "consentMemberTerms",
"value": true,
"date": "2022-01-01T00:00:00+0100",
"source": "ECOM",
"comment": "Approved member terms at checkout"
}]
}
```
Only consents with a value or "true" or "false" will be shown in this response. So if a consent is not set, it will not show up here. You can, however, fetch all the consents through /consents and combine that with the consent data returned for an individual contact. In this way, all consents can be shown for a contact (for example, in the POS) even if their value is not set.
By combining all the consents for a tenant from /consents with a specific contact's consents fetched from /contactoverview, you can build up a complete picture of the consents for that specific contact, including the ones not set.
## Giving or revoking a consent
Setting the state of a consent for an individual contact is done in the same way as for any contact update:
```http theme={null}
PATCH /api/v3/contacts/{contactId}
```
In the body of the update request, add the consent like this:
```json Adding the consent theme={null}
{
"consents":[{
"id": "consentMemberTerms",
"value": true,
"comment": "Some comment here",
"source": "POS"
}]
}
```
This example would set the state of the "consentMemberTerms" consent to true (or Yes).
## Double opt-in
A double opt-in is where a contact must confirm their sign-up before they can receive marketing communication / membership. It basically makes signing up into a two-step process. How you set this up in Customer Engagement is covered in this article:
![The triggers available]()
At the bottom of this list, you should find your custom trigger or triggers.
![Your custom triggers]()
From this point on, your custom trigger can be handled like a standard one. Use it to create an automation, and create branches based on the incoming data.
Here is how a custom trigger automation looks:
![A custom trigger automation]()
When this trigger is activated, contacts are moved into one of three branches, depending on a keyword found by a value split ("Bike", "Ski" or everything else) and then sent an SMS. The number of contacts directed into each of the three branches can be seen, as well as the total number who triggered this automation.
The important points to remember about custom triggers are:
* They are called over the API using `triggerId` plus some identifier (`contactId` or another key)
* They can receive JSON data (data fields), the structure of which is defined per custom trigger
The data fields in your custom trigger can be used both for filtering in the automation and also as variable data in the content produced by the automation.
## Custom triggers and Design Studio
When working with Design Studio, you'll also need to define the JSON schema for the custom trigger so that it can be used. How you do that is described here:
A custom trigger can only be triggered for an contact that exists in Customer Engagement.
There are a few ways to activate a custom trigger over the API, depending on what information you have:
```http If you know the contact ID theme={null}
POST /api/v3/automation/customTriggers/{triggerId}/triggerByContactId/{contactId}
```
```http If you know contact type and the key identifier value theme={null}
POST /api/v3/automation/customTriggers/{triggerId}/triggerByContactTypeAndKey/{contactType}/{keyValue}
```
```http If you know the external contact ID theme={null}
POST /api/v3/automation/customTriggers/{triggerId}/triggerByExternalContactId/{externalId}
```
```http If you know the personal identity number theme={null}
POST /api/v3/automation/customTriggers/{triggerId}/triggerBySocialSecurityNumber/{ssn}
```
### Examples of values
Here are some example values for the properties in the endpoints above:
| Attribute | Type | Example value |
| :- | :- | :- |
| triggerId | String | myCustomTrigger |
| contactId | GUID | a67f201f-d86d-4ee2-bdc7-abce4444a804 |
| contactType | String | Member |
| keyValue | String | 46739666666 / [test@example.com](mailto:test@example.com) |
| externalId | String | 012345 |
| ssn | String | 198101010101 |
Note that a mobile phone number is sent *with* the country code ("46" in the example above) but *without* a `+` at the start.
The actual kind of value sent for `keyValue` depends on how that is set up in the Customer Engagement back-end. It could for example be a value representing "memberNumber", "email", "mobilePhone" or "externalId", depending on your particular configuration. So if `keyValue` is configured as "email" then the email address of the contact in question is sent in the API request.
## Payload example
Custom triggers are often used for transactional communication from the e-com or business layer to the end user. In these cases, a payload is often sent. Below is an example of the setup in the backend for a custom trigger that is used to populate a reset password email.
```json Custom trigger payload example theme={null}
{
"oldAccount":"true" OR "false",
"username":"[username]",
"resetUrlHTML":"[http address of unique reset link]"
}
```
The value of the `oldAccount` flag can be used to filter different kinds of communication or trigger a specific automation. All automations using a certain trigger will listen for any responding API call but only the responding data sent in the payload will start the specific automation.
# Product feeds
Source: https://developer.voyado.com/docs/setup/product-feeds
A product feed is a detailed representation of a retailer's entire product catalog. It has two main uses in Customer Engagement.
The first is when Customer Engagement needs to *communicate products in emails*. This applies both to manual use cases, such as product feed modules where specific product IDs are inserted, and automated scenarios like abandoned cart, browse abandonment, and back-in-stock flows. In this context, the product feed is purely used for communication.
The second use of a product feed is to populate the article register. See more about that here:
While a product feed URL must be open, it is possible to restrict access by allow-listing only those IP adresses that Customer Engagement will use. Talk to your Voyado account manager if this is something you need.
The URL for a retailer's product feed (or feeds) is entered into the Customer Engagement back-end, by their Voyado team. If the feed exists in different languages, a feed can be defined for each language.
Voyado recommends 800 000 items as the maximum in a product feed, to assure the best experience with Customer Engagement. If you need to have a product feed with more items, contact your Voyado account manager. Products of interest are connected to the *article register* and not the product feed.
This simplified example above contains one item node. An actual product feed will usually have all of a retailer's products, which can be thousands or even millions of item nodes.
```xml theme={null}
ExampleShop.dk - Example
https://www.ExampleShop.dk
-
Taljebælte til line Showmaster®
https://www.ExampleShop.dk/hund/aktivering-traening/traening/taljebaelte-til-line
Taljebælte med indbygget forlængelse, som dæmper ryk fra din hund. Benstropper forhindrer, at bæltet kryber op over hofterne. Justerbart mellem 75 - 130 cm.
041213-10-00000
Hund > Aktivering & Træning
Showmaster®
https://www.ExampleShop.dk/pub_images/large/041213-10-00000_1.jpg?timestamp=1618572964
new
in stock
199.00 DKK
7315470000683
20381
TRUE
Sort
DK
Standard
0.00 DKK
https://www.ExampleShop.dk/pub_images/large/041213-10-00000_2.jpg?timestamp=1618572965
281
```
When migrating historical transactions, the product feed won't be able to add metadata, since the feed normally contains current data (the e-com does not need “old” data to be sent out to, for example, Google Shopping). Therefore, you might end up missing historical data. In some cases, a separate migration is recommended. Talk to your Voyado PM about the best approach.
# Stores
Source: https://developer.voyado.com/docs/setup/stores
All your stores, whether physical or digital, are represented in the Customer Engagement database. They are either added manually by you, or created automatically whenever a purchase references a store that does not yet exist in your Customer Engagement environment.
## Stores and contacts
Every contact in Customer Engagement has two stores connected to them:
**Created-in store**: Also known as the recruited-in store, this is the store where a contact was first added to Customer Engagement. Once this is added to a contact's data it cannot ever be changed.
**Regular store**: This is the contact's "usual" store as determined by RFM values. This can change based on the contact's behaviour.
When a contact is created, the regular store is by default the created-in / recruited-in store.
## Working with stores
Your active stores should be set up in Customer Engagement before contacts are created. Additionally, any new stores that open should also be added. This allows customers to be linked to the correct recruited-in store or regular store through the store ID in their purchase data.
If a transaction is processed by Customer Engagement using a store ID that doesn't exist, then Customer Engagement will create that store.
## Creating a store
Here is how to create a store in Customer Engagement:
In Customer Engagement, go to **Administration**, then select **Stores** and **Stores** again.
On the **Stores** page select "Create store" in the upper right corner.
Fill in the fields. Required fields are "Store", "Time zone" and "External ID".
The "Store" field is the display name for this store as it will be shown in Customer Engagement. It should be unique to reduce confusion but doesn't have to be.
The "External ID" is the one on the receipt. It is usually found in your ERP system. This is the store's unique ID in Customer Engagement and can't be the same as another store in Customer Engagement.
![Adding a store]()
Ensure the "Active" checkbox is checked and then select "Save".
## Changing store's External ID
A store's External ID is used to connect imported receipts with that store. If you change a store's External ID in Customer Engagement, but are still sending receipts using the old External ID, Customer Engagement will then create a new store using that old External ID. That is not good.
To correctly change a store's External ID, the customer needs to stop sending receipts using the old External ID, then change the External ID value in Customer Engagement, and then begin sending receipts using the store's new External ID. Doing it this way avoids any issues.
Be sure, if changing a store's External ID, that you do it the way described above.
## Sending email as specific store
This is for the classic editor only.
When designing an e-mail send-out, there's a way to decide which product feed will be used to populate it. To get this working, there's a few things to do in the Customer Engagement back-end and front-end.
Your Voyado team needs to make adjustments to the Customer Engagement back-end. Contact them for this step.
When that's done, go to the Customer Engagement frontend and select **Administation** then **Stores** and then **Stores** again. You'll see a list of all your stores. Selecting one takes you to **Edit store**. Scroll down to the **Spare fields** section. Locate the "Locale" field.
This is where you will enter the same locale as the one specified in whatever product feed you want to use for this store.
![Configuring spare field]()
Now, when you are creating an email, you can select "Send as a specific store" and select the store (and, indirectly,the locale or product feed connected to it) that will be used for this send-out.
![Configuring store settings]()
If you define the "locale" attribute for all stores, even physical, you can send as *any* store using the correct language/currency when creating a email send-out. You are not restricted to just e-com stores.
It's only possible to get data from ONE specific product feed for every email send-out. Therefore, in Customer Engagement, you can only use one language (and one currency) per send-out.
## API endpoints for stores
Here are the endpoints used for working with stores.
### Create a store
To create a store, use this endpoint with the following payload structure:
```http theme={null}
POST /api/v3/stores
```
```json Payload structure theme={null}
{
"name": "string",
"externalId": "string",
"type": "string",
"timeZone": "string",
"city": "string",
"county": "string",
"countryCode": "string",
"email": "string",
"adjacentZipCodes": "string",
"emailUnsubscribeText": "string",
"emailViewOnlineText": "string",
"footerHtml": "string",
"headerHtml": "string",
"homepage": "string",
"phoneNumber": "string",
"region": "string",
"senderAddress": "string",
"senderName": "string",
"street": "string",
"zipCode": "string",
"active": "boolean",
"locale": "string"
}
```
The required fields here are `name` and `externalId`. The POST request will return a *400* error if these are missing from the payload.
While not required, you should also specify:
* `timeZone`: Since the Customer Engagement UI requires it and you'll probably be accessing the store through the UI at some point
* `type`: Given as either "ECOMM" or "RETAIL" or "OTHER"
* `countryCode`: For example "SE", "FI", "IR" - Used to improve reporting and segmentation
The string value for the country will be calculated from the `countryCode` value so you don't need to send that. Note that `county` also exists as an attribute. This can be seen as an area that's between `city` and `region` in size.
### Get all stores
Use this endpoint to fetch all your stores.
```http theme={null}
GET /api/v3/stores?includeInactive=true
```
Optionally add `includeInactive` as "true" as shown above to include inactive stores in the response.
Leave it out if you don't need it (the default is "false").
The response will have this structure:
```json theme={null}
[
{
"name": "010",
"externalId": "010",
"city": null,
"countryCode": null,
"county": null,
"email": null,
"adjacentZipCodes": null,
"emailUnsubscribeText": null,
"emailViewOnlineText": null,
"footerHtml": null,
"headerHtml": null,
"homepage": null,
"phoneNumber": null,
"region": null,
"senderAddress": null,
"senderName": null,
"street": null,
"type": "RETAIL",
"zipCode": null,
"active": true,
"timeZone": null
}
]
```
This example contains just one store object, but a real response will usually contain many.
### Get a single store
You can fetch a single store's data if your know its external ID:
```http theme={null}
GET /api/v3/stores/{externalId}
```
### Update a single store
You can update a store using the same endpoint:
```http theme={null}
POST /api/v3/stores/{externalId}
```
The payload will be similar to the one you used to create the store:
Only send the values you want to change (which means a smaller payload than the one shown in "Create a store" above). Any empty or null values sent in the payload will overwrite the existing values for that store.
The payload you'll usually send to update a store looks more like this, containing only the value or values to change:
```http theme={null}
{
"homepage": "newhomepage.com"
}
```
# Back in stock
Source: https://developer.voyado.com/docs/tracking/back-in-stock
In Customer Engagement you can set up back-in-stock automations. These are used to notify customers when a particular product they have indicated an interest in is available to buy again.
The main steps of a back-in-stock flow in Customer Engagement are:
* Create a back-in-stock subscription
* Receive a stock level update
* Start the back-in-stock automation
* Send a back-in-stock email
This article will focus on the back-in-stock and stock-levels API endpoints.
Any back-in-stock subscription created will be deleted as soon as it has triggered a back-in-stock automation for that contact. The subscription is then seen as "used".
### 1 - Create a new subscription
A back-in-stock subscription is created using the following API endpoint:
```http theme={null}
POST /api/v3/inventory/backinstock/subscriptions
```
With the following kind of payload:
```json theme={null}
{
"contactId": "f5774867-8358-111f-85a4-af1200eced95",
"locale": "en-US",
"sku": "AD_0397_V_685_006_66",
"externalId": "12165253-34345"
}
```
The subscriber's Customer Engagement contact ID.
The SKU of the item being subscribed to.
Locale of the SKU and therefore which product feed to fetch product data from.
A reference to an entity in an external system, only required if the value is included in the stock level update.
A successful request gives a *HTTPS 201 Created* response.
Since the `contactId` is sent when creating a back-in-stock subscription, that contact needs to exist in Customer Engagement. If they don't exist, you'll need to create them. For example, when a user enters their email to request a back-in-stock message, and that email can't be connected to any existing contact.
When doing this, Voyado recommends using your default contact type and collecting the contact's consent for future communication. This will allow you to stay in touch after the back-in-stock notification has been sent, and communicate with that contact outside of the back-in-stock scope.
The unique ID of the back-in-stock subscription.
A successful deletion gives a *HTTPS 204 No Content* response.
### 3 - Get all subscriptions for a contact
You can fetch all back-in-stock subscriptions for a contact like this:
```http theme={null}
GET /api/v3/contacts/{contactId}/backinstock/subscriptions
```
The standard GUID identifying a contact in Customer Engagement.
A successful request returns a *HTTPS 202 OK* response and this kind of data:
```json theme={null}
{
"data": [
{
"id": "cba5aba5-cf3c-40f5-a4db-b0d100bb2c7a",
"contactId": "48fba7e7-e447-4d90-a9ca-a86e00b1d8f4",
"sku": "AD_0743_V_395_001_31x65",
"locale": "en-US",
"externalId": "12165253-34345",
"createdOn": "2023-12-07T12:21:28+01:00"
},
{
"id": "bfca224c-de4c-4d61-903d-b0d100bb331c",
"contactId": "48fba7e7-e447-4d90-a9ca-a86e00b1d8f4",
"sku": "AD_0397_V_685_006_29",
"locale": "en-US",
"externalId": "12823253-89054",
"createdOn": "2023-12-07T12:21:34+01:00"
}
]
}
```
### 4 - Update one or several stock levels
This endpoint updates stock levels of one or more specific SKUs in Customer Engagement. This is then used to trigger the automations that will send back-in-stock communication to subscribed contacts.
Stock level updates are done like this:
```http theme={null}
PUT /api/v3/inventory/stock-levels
```
With this kind of payload:
```json theme={null}
[
{
"quantity": 15,
"locale": "sv-SE",
"sku": "AD_0397_V_685_006_29",
"externalId": "12165253-34345"
},
{
"quantity": 10,
"locale": "en-US",
"sku": "AD_0743_V_395_001_31x65",
"externalId": "48165253-23345"
}
]
```
For Customer Engagement to trigger a back-in-stock email, all products (including out of stock products) must be present in the product feed that is connected to Customer Engagement. If a product is not in the feed, a BIS email cannot be sent for it.
Latest stock quantity of the SKU.
The SKU of the item which has received a stock level change. This SKU has to exist in the product feed.
Locale of the SKU and therefore which product feed to fetch product data from.
Reference to an entity in external system.
A successful request gives a *HTTPS 202 Accepted* response.
Customer Engagement should be notified whenever the stock level of the given SKU has changed, or when it is considered back in stock. This enables Customer Engagement to keep track of the entire inventory regardless of the stock level. A stock quantity threshold of what the client considers to be "back in stock" can be configured in the automation trigger.
## locale and externalId in stock level updates
Although neither `locale` nor `externalId` are required for stock level updates, it's strongly recommended to include at least one of these attributes when a stock level update is done. Which one you use depends on what your subscription look like.
Consider the following situation. Five subscriptions are set up using these values (the `externalId` attribute is optional when setting up a subscription):
| Subscription | sku | locale | externalId |
| - | - | - | - |
| #1 | SKU-1 | sv-se | |
| #2 | SKU-1 | pl-pl | |
| #3 | SKU-1 | sv-se | SE-SKU-1 |
| #4 | SKU-1 | pl-pl | PL-SKU-1 |
| #5 | SKU-2 | sv-se | |
**Case 1:** The retailer sends `sku`, `quantity` and `locale` when doing a stock level update. An event is then triggered if both the `sku` and `locale` in the request match one or more of the subscriptions. The event created will be enriched based on the value in `locale`.
* Example: The retailer sends `sku` as "SKU-1" and locale as "sv-se", triggering subscriptions #1 and #3.
**Case 2:** The retailer sends `sku`, `quantity`, `externalId` in a stock update. Now for an event to be triggered, `sku` and `externalId` have to match a subscription. The event will be enriched based on `locale`.
* Example: The retailer sends `sku` as "SKU-1" and `externalId` as "SE-SKU-1", triggering subscription #3.
**Case 3:** The retailer sends only `sku` and `quantity` in a stock update. All subscriptions containing that `sku` will now be triggered regardless of their `externalId` or `locale` value. The event will be enriched based on the `locale`.
* Example: The retailer sends the `sku` as "SKU-1" which triggers subscriptions #1, #2, #3 and #4.
## Triggering the back-in-stock automation
For Customer Engagement to trigger a back-in-stock email, all products (including out of stock products) must be present in the product feed that is connected to Customer Engagement. If a product is *not* in the feed, a BIS (back-in-stock) email cannot be sent for it.
A stock level update sent to Customer Engagement triggers any back-in-stock automation triggers.
![The automation trigger]()
The following conditions must be met for a back-in-stock automation for a subscription to proceed.
1. The stock quantity must be higher than 0
2. A product feed must be configured for the specified locale
3. Product data must exist for the specified SKU
As well as these predefined conditions, you can also define custom conditions for your back-in-stock automation trigger based on:
* Locale
* Quantity
* SKU
* ExternalId
* Product data
* Subscription time
* Purchase
* Contact attributes
Once the automation has started (and passed all trigger conditions) that specific subscription will be deleted, regardless of whether the automation included communication to the subscriber or not.
A value split for `locale` is also supported in back-in-stock automations.
## Logging of back-in-stock
The integration log will show you which SKU has passed the predefined conditions in the automation, and the number of subscriptions that have been sent to the back-in-stock automation trigger.
![Back-in-stock logging]()
# Identification and cookies
Source: https://developer.voyado.com/docs/tracking/identification-and-cookies
How the tracking script links a website visitor to a contact in Customer Engagement, and the cookies it uses to do it.
*Identification* means linking a visitor browsing your website to a specific contact ID in Customer Engagement. Until that happens, their activity is stored against their browser instead.
Once a visitor is identified, all their activity from that browser — including the activity recorded **before** they were identified — is connected to their contact record in Customer Engagement.
Because anonymous activity is connected retroactively, never restrict `cart()` or `productview()` calls to logged-in or identified visitors. Send events for everyone.
## How a visitor gets identified
The tracking script identifies a visitor in three ways:
1. **They click a link in an Customer Engagement email.** The link carries a `vtid` query parameter, which the script reads from the URL.
2. **Your site identifies them and calls `setContactId()`**, for example on login, registration, newsletter signup, completed purchase, or [soft identification](/docs/contacts/identify-contact/soft-identification).
3. **A `_vaI` cookie already exists** from a previous visit.
The identification then applies to all subsequent events from that browser, until the cookie expires or changes (such as when a different person logs into the same browser).
`_vaI` is `_va` followed by an uppercase letter **I** (I as in Ingemar), not a lowercase L.
In Safari, any cookie created with JavaScript lives for a **maximum of 7 days**, regardless of the expiry date set. See [server-side cookies](#server-side-cookies) for the workaround.
### About the vtid parameter
`vtid` holds the contact ID in an encoded form, which Customer Engagement decodes internally. An Customer Engagement user cannot retrieve the contact ID or identify the contact from the `vtid` value alone.
When you send events, the `contactId` field accepts either the full contact ID guid or the encoded value from `vtid`.
## Using setContactId()
Call `setContactId()` with the visitor's `contactId` at the moment your site identifies them:
```javascript theme={null}
va("setContactId", "contactId");
```
When using soft identification on a site running the tracking script, take the `contactId` from the decrypted `eClub` query parameter.
`setContactId()` does not generate a request to the Collect endpoint.
Never call `setContactId()` with zero, an empty string, `null`, `undefined` or any other invalid value.
A visitor may already be identified without being logged in. For instance, if they arrived from an email link. Calling `setContactId()` with an invalid value clears that existing identification.
Voyado recommends also including `contactId` explicitly in every `cart()` and `productview()` event for identified visitors.
## Server-side cookies
Apple's Intelligent Tracking Prevention (ITP) caps client-side cookies and LocalStorage in Safari at 7 days. Since `_vaI` is created by the script, an identified visitor who doesn't return within 7 days loses their identification.
The cap does not apply to cookies created server-side. Script version 0.1.7 and later can therefore read a server-created cookie named `_vaI_server` and use it to recreate `_vaI`. Identified visitors then stay identified when they return, even after months away.
### How to implement it
Server-side, check whether the incoming request contains a `_vaI` cookie. If it does, copy its value into a new `_vaI_server` cookie with a one-year expiry and add it to the response.
```csharp An example in C# theme={null}
if(HttpContext.Request.Cookies.TryGetValue("_vaI", out var contactId) && !string.IsNullOrWhiteSpace(contactId) && contactId != "undefined")
{
var option = new CookieOptions
{
Expires = DateTimeOffset.Now.AddYears(1),
HttpOnly = false
};
HttpContext.Response.Cookies.Append("_vaI_server", contactId, option);
}
```
![Server-side cookie]()
### When \_vaI is recreated
The script recreates the `_vaI` cookie in any of these cases, checked in this order:
1. Your site calls `setContactId()`, or includes `contactId` in an event.
2. The URL contains a `vtid` parameter.
3. LocalStorage contains a `vtid` key.
4. A `_vaI_server` cookie exists.
The tracking script is not the same thing as the tracking parameters attached to a URL. The script runs on your pages while the URL parameters (such as `vtid`) are read *by* the script.
## Configure the script
This is the Voyado tracking script:
```javascript theme={null}
```
Replace these two placeholders before you use it:
The path to the JavaScript analytics package. There are two options, depending on the environment you are running in.
```http Production theme={null}
https://assets.voyado.com/jsfiles/analytics_0.1.8.min.js
```
```http Staging theme={null}
https://assets.voyado.com/jsfiles/analytics_0.1.8.staging.min.js
```
Use the path that matches your environment. Running the production script in staging (or the other way round) means tracking will not work.
`analytics_0.1.8` is the latest version. You can pin an earlier version if you need to, but note that server-side cookie support requires 0.1.7 or later.
Your unique client (tenant) ID. It is the same in production and staging, and is usually the subdomain in your Customer Engagement root URL.
For example, if your URL is `supershop.voyado.com`, the tenant ID is `supershop`.
Contact your Voyado Customer Engagement team if you are unsure.
A configured script looks like this:
```javascript Complete tracking script theme={null}
```
## Implement the script
The script must be present, initialized and running on *every page* of your site. including landing pages, category pages and other non-product pages. The script is what identifies a visitor who arrives from a Customer Engagement email link. If an email link lands on a page without the script, identification will fail.
Implement the script either directly in your page templates or through a tag manager.
Copy your configured snippet and paste it immediately after the `` tag of every page on your website.
1. Log into your tag manager.
2. Select **New Tag**.
3. Give the tag an easily recognizable name.
4. Open **Tag configuration** and select **Custom HTML** as the tag type.
5. Paste your configured tracking script into the box.
6. Open **Triggers** and select **All pages** (recommended).
7. Save the tag.
8. Publish the new version of your tag container.
## Script methods
Once the script is running, the following functions are available on your pages.
| Method | Call it | Sends a request to Collect? |
| - | - | - |
| `checkout` | When the checkout changes in any way | Yes |
| `setTenant` | Once, in the snippet itself | No |
| `setContactId` | When your site identifies the visitor | No |
| `cart` | When the cart changes in any way | Yes |
| `emptyCart` | When the cart is emptied or checkout completes | Yes |
| `productview` | What a product is shown to the visitor | Yes |
Even though you will see these referred to as functions, they are not actual functions in JavaScript. Instead, the va() function is called with two arguments: the function name as a string, and then the value / payload. For example:
```javascript theme={null}
va("emptyCart", {"cartRef": "354354"});
```
`_vaI` is `_va` followed by an uppercase letter **I** (I as in Ingemar), not a lowercase L. The two are hard to tell apart in many fonts.
## Where to start
Cart and product view data is enriched from the product feed. Without a feed for the relevant locale, no automation can trigger.
One snippet, on every page of the site.
Call `setContactId()` at the moment your site identifies someone, and understand how the cookies work.
Track every cart change, and every product view.
Work through the checklists before going live.
# Discounts
Source: https://developer.voyado.com/docs/transactions/discounts
In Voyado Customer Engagement, vouchers and promotions are applied as discounts. This avoids having a customer be awarded points from a voucher that is used in a purchase. There are two kinds of discounts, line-item and total, and they work in similar ways.
The discount amount is always given as the *gross* amount, which includes VAT / MOMS.
## Line-item discount
A line-item discount is applied directly to the specific line-item in the transaction. For example, if the discount is 25%, the price for that specific line-item will be the original price \* 0.75. This new amount is then what the customer pays.
## Total discount
A total discount is applied across the whole transaction and is not recorded as its own separate line-item. Essentially, it is a series of line-item discounts. For example, a 30% total discount will result in the price of every line-item being multiplied by 0.70, and this new total is what the customer pays.
## Example
If a customer makes a purchase containing multiple items for an amount of €15, and uses a voucher with a total discount value of €5, the price the customer pays is then €10. The discount from the voucher (€5) should be evenly spread out across all line-items, meaning the amount discounted on each line-item may vary.
In this example, the customer will only receive points on the amount paid by other payment methods besides the voucher (which is €10 in this case).
## The preferred method
If you as a merchant are not able to make vouchers-as-discount configurable for every client, it is possible to do it other ways, but the preferred method is to always handle vouchers as a discount.
## Applying a discount
Both line-item and total discounts need to be applied before the transaction is sent. The `grossPaidPrice` should always describe the amount actually paid for the item, with all discounts already removed.
Regardless of the nature of the discount, `item.discount` can be used to tell Customer Engagement which discounts have been used. If an article is exposed to both a total discount (for instance 20%) and a 100 SEK line-item discount, both of those will contribute to the total amount withdrawn from the original price.
For example, an article for 240 SEK will cost (240 \* 0.80) – 100 = 92 SEK after both these discounts have been applied. These aggregated row values are stored as a parameter for searching the total discount per sold article in Customer Engagement.
A Customer Engagement instance needs to be configured to allow searching by discounts. Ask your Voyado team about this.
## Redeeming vouchers
When a voucher is included in a purchase, it should be redeemed by [a separate API call](/docs/loyalty/vouchers#redeem-a-voucher), and also be included in the `usedBonusChecks` array in the call to `/receipts`:
```json theme={null}
"usedRewardVouchers": [
{
"voucherNumber": "2342"
}
]
```
In the API v3 `usedRewardVouchers` has replaced `usedBonusChecks` and `voucherNumber` has replaced `checkNumber`.
## Redeeming promotions
A promotion is handled in the same way as a voucher. But if a Customer Engagement promotion is used in the transaction, it should be redeemed by separate API call to the `/redeem` endpoint and should also be included in the `usedPromotions` array in the call to `/receipts`:
```json theme={null}
"usedPromotions": [
{
"promotionId": "6374dfaa-31c5-4e34-bb88-7ccfc5fe8bf7"
}
]
```
It is important to do both of these things to ensure the promotion is properly redeemed.
See the process in more detail here:
Clearly, `fromFactor` multiplied by `toFactor` for a currency has to equal 1.0.
## Group currency in transactions
If a transaction is sent to Customer Engagement in a currency that isn't the group currency, it will be converted to the group currency using the values given in the conversion table. These values, though, are static and don't consider the daily fluctuations in the currency. A more exact way is to send the currency conversion at the moment the transaction was made, using the `exchangeRateToGroupCurrency` field in the transaction payload.
Here is an example when the group currency in Customer Engagement is set to EUR:
```json Example of EUR group currency theme={null}
{
"contact": {
"matchKey": "1c333c0a-ed33-3333-33cb-b0333333c333",
"matchKeyType": "contactId"
},
"uniqueReceiptId": "20180906468464468",
"receiptNumber": "468464468",
"createdDate": "2018-09-06T15:55:54+01:00",
"storeExternalId": "321",
"currency": "GBP",
"exchangeRateToGroupCurrency": 0.877969,
"totalGrossPrice": 11.00,
"paymentMethods": [{
"type": "Card",
"description": "Debit Card",
"value": 11.00
}],
"items": [{
...
```
So if `exchangeRateToGroupCurrency` exists in the payload, it will be used to convert the amount to the group currency. Otherwise the default value in the conversion table will be used to do that.
# Introduction to transactions
Source: https://developer.voyado.com/docs/transactions/introduction-to-transactions
A transaction, as defined in Customer Engagement, is when a customer visits a physical or online store and purchases (or returns) one or more items. The transaction contains its own data -- such as the transaction's unique ID, the store's ID, the timestamp -- plus the data for each individual item that was purchased or returned (known as the line items).
All fields in the transaction data model can be used for segmentation and analysis in Customer Engagement.
Transaction data is sent to the endpoint called `/receipts`. You might see the term "receipt" turning up other places in the Customer Engagement API or in field names. Keep in mind that "receipt" means "transaction".
You might also come across an API endpoint named `/transactions`. This is a legacy endpoint maintained for a few older clients, so, despite the name, do NOT send your transaction data here.
## Processing of API calls
Transactions posted to the `/receipts` API are not relayed to the database immediately. Instead, they are collected and, at a preset interval, converted into an XML file. This XML is processed and applied to the database. By default, an XML is generated every 15 minutes, meaning it could take this amount of time for a transaction to be registered in the database. It’s possible to change this interval, all the way down to 0 minutes if needed, to speed up testing.
Talk to your Voyado Customer Engagement team about this.
The transaction XML is converted through XSLT in the same way as historical transaction which are imported through Customer Engagement's ftp. However, no XSLT is required in this case as long as no special transformations are used.
## Duplicates
Any transaction imported that has the same `uniqueReceiptId` as an already existing transaction in the database will be seen as a duplicate and ignored.
## Discounts (line-item and total)
Total discounts (ex. 30% on an entire purchase) should not be recorded as a separate line item. Instead, the discount should be applied on each line-item so that each item reflects the actual price paid for the item. The same applies for line item discounts (ex. 25% on a specific item), where the discount should be deducted from the specified line item price (i.e. original price \* 0.75).”. Read more about discounts below and in the section [Discounts](/docs/transactions/discounts)
## Updates to a transaction
Once a transaction is imported into Customer Engagement it is not possible to update it with new information.
## Group currency and local currency
Group currency is the default currency for the specific Customer Engagement instance, normally decided in the pre-study. The property `currency.conversion.factors` sets the different exchange rates used when converting between the group currency and the local currency.
## Product metadata and spare fields
Customer Engagement can access all product metadata from the transaction as well as the specific line items. Read more about other options [here](/docs/setup/article-register). There are also a limited amount of fields per product that can be used for storing extra data for a transaction:
* 10 spare string fields (spare1, spare2 ... spare10)
* 10 spare date fields (datespare1, datespare2 ... datespare5)
These fields can be found in the API and XML under “extraData”. If they are named the same as in the client configuration, no transformation needs to be done.
## Freight
In Customer Engagement's transaction model, freight should not be included, to avoid the end-user being awarded bonus points based on the freight cost. Bonus points should only be based on what the end-user has actually paid for their purchase.
There are also some reports and KPIs in Customer Engagement that require the freight fee to be excluded. For example, most purchased articles, number of articles purchased, total purchase amount and the average amount on the transaction.
So freight should always be excluded from the transaction's total, even if the e-com handles it separately, whether per item row or as a total amount. Regardless on how the e-com handles it, the amount total on the receipt sent to Customer Engagement is calculated *without* the freight cost, and the amount for each item must sum to the total amount.
This is only true for the endpoint `/receipts`. For the /orders endpoint, Customer Engagement uses an object called freightFee to inform the end customer, in their order communication emails, how much they have paid for freight.
## Validations
* `discounts.value` should always be negative
* A return should have `item.type` as "return" and `quantity` should be negative
* A purchase should have `item.type` as "purchase" and `quantity` should be positive
* quantity should never be 0
* Sum of all `paymentMethods` should equal `totalGrossPrice`.
* Sum of all `grossPaidPrice` should equal `totalGrossPrice`.
* `taxAmount` should equal `grossPaidPrice` – `grossPaidPrice` / (1 + taxPercent / 100)
* `createdDate` should be in ISO8601 with time zone designator
# Purchase history summary
Source: https://developer.voyado.com/docs/transactions/purchase-history-summary
This endpoint can be used to get a summary of all a contact's previous purchases.
```http theme={null}
GET /api/v3/contacts/{contactId}/purchasehistorysummary
```
## Responses
A successful update will return *HTTP 200 OK* along with the contact's purchase history summary as the response body. That will look like this:
```json theme={null}
{
"lastUpdated": "2025-09-05T14:53:50.4905776+02:00",
"purchaseAmountAll": 2219.26,
"numberOfArticlePurchasesAll": 3,
"averageReceiptAll": 2219.26,
"latestReceiptDate": "2023-09-05T14:53:50.4905776+02:00",
"purchaseFrequencyAll": 1,
"purchaseAmountLastYear": 0,
"numberOfArticlePurchasesLastYear": 0,
"averageReceiptLastYear": 0,
"purchaseFrequencyLastYear": 1,
"purchaseAmountLastTwoYears": 2219.26,
"numberOfArticlePurchasesLastTwoYears": 3,
"averageReceiptLastTwoYears": 2219.26,
"purchaseFrequencyLastTwoYears": 2219.26
}
```
Amounts shown are given in the group currency.
If the request has not been successful, you'll get this HTTP error code:
* *404: RetailKpiNotCalculated*: The contact ID given was not found in the database.
# Register a purchase
Source: https://developer.voyado.com/docs/transactions/register-a-purchase
When an identified contact finalizes a purchase, it should be sent to Customer Engagement and made available for segmentation and reporting. Usually a finalized purchase means that payment has been successfully processed.
The data is sent to the following endpoint:
```http theme={null}
POST /api/v3/receipts
```
Data sent here cannot be reversed or updated, hence the importance of only sending finalized purchases.
## Identification
To be able to store a transaction in Voyado, you’ll need to connect it to a specific contact.
The key has to be a unique data field for the specific contact type. One of these fields is used:
* contactId
* email
* mobilePhone
* memberNumber
* externalId
* socialSecurityNumber (actually a Swedish or Finnish Personal Identification Number)
However, the key used does **NOT** have to be the key value for the specific contact type.
The default contact type is usually “Member”. To send transactions for any other contact type, include contactType in the request. This is not required if contactId is used as matchKeyType, since it uniquely identifies the contact.
### Example
```json theme={null}
"contact": {
"matchKey": "e8a5a8ff-1616-4990-b16d-af9412999824",
"matchKeyType": "email",
"contactType" : "contact"
}
```
### Example payload
In the below example payload the key type is “contactId”. When using this key type, you do not need to specify contactType as contactId is always unique. If you do send contactType, it will be used in the matching logic and has to match.
```json theme={null}
{
"contact": {
"matchKey": "1c277c0a-ed93-4928-86cb-b0820090c111",
"matchKeyType": "contactId"
},
"uniqueReceiptId": "20180906468464468",
"receiptNumber": "468464468",
"createdDate": "2018-09-06T15:55:54+01:00",
"storeExternalId": "321",
"currency": "NOK",
"exchangeRateToGroupCurrency": 1.0,
"totalGrossPrice": 200.00,
"paymentMethods": [{
"type": "Card",
"description": "Debit Card",
"value": 200.00
}],
"items": [{
"type": "PURCHASE",
"quantity": 2,
"grossPaidPrice": 200.00,
"taxAmount": 40.00,
"taxPercent": 25.00,
"sku": "10015563434",
"articleNumber": "2324234",
"articleName": "Gambeson",
"articleGroup": "Jackets",
"extraData": [{
"name": "campaign",
"value": "Socks 3 for 2"
}, {
"name": "size",
"value": "M"
}],
"marginPercent": "25.00",
"awardsPoints": false,
"discounts": [{
"type": "325",
"description": "50% autumn discount",
"value": -200.00
}]
}],
"usedRewardVouchers": [{
"voucherNumber": "2342"
}],
"usedPromotions": [
{
"couponId": "272cd4e4-5cb4-472f-8747-a61112083ccb"
}
]
}
```
In the API v3 `usedRewardVouchers` has replaced `usedBonusChecks` and `voucherNumber` has replaced `checkNumber`.
If `contact.matchKeyType` is set to "contactId", then `contact.contactType` is not a required field.
If using any other matchKeyType, and contactType is not provided, Customer Engagement will just use whatever your default contact type is (normally Member).
A successful POST operation returns a 202 (Accepted).
Transactions can also be imported through an XML file format. Read more about in this article, [Receipt XML import](/docs/file-based-transfer/transactions-xml-import).
Find the complete list of transaction field definitions [here](/docs/transactions/transaction-field-definitions).
In the "usedPromotions" section of the payload, send either ´couponId´ OR ´promotionId´ but not both. Voyado recommends that you use the ´couponId´ as shown here.
# Register a return
Source: https://developer.voyado.com/docs/transactions/register-a-return
In Customer Engagement, a return is viewed as just another transaction, but with a different transactional status. There is no direct connection between a purchase and a return that comes after, it’s considered a new transaction and handled accordingly.
Some important points to remember:
* The `quantity` field has to be **negative**, reflecting the number of returned items.
* The line item `type` needs to have the value “RETURN”.
* The `grossPaidPrice` on a return should be sent as a **positive** value of type "decimal".
* The `taxAmount` should be sent as a **positive** value of type "decimal".
In the same way as for a purchase, the payload is sent to the following endpoint:
```http theme={null}
POST /api/v3/receipts
```
## Example payload
This example transaction is a return for a customer with contact type “Member”. Note that `quantity` is negative, the price is positive and the line item type is “RETURN”.
```json theme={null}
{
"contact": {
"matchKey": "1c277c0a-ed93-4928-86cb-b0820090c111",
"matchKeyType": "contactId"
},
"uniqueReceiptId": "20180909468464496",
"receiptNumber": "468464496",
"createdDate": "2018-09-09T12:05:23Z",
"storeExternalId": "321",
"currency": "NOK",
"exchangeRateToGroupCurrency": 1.0,
"totalGrossPrice": -400.00,
"paymentMethods": [{
"type": "card",
"description": "Debit Card",
"value": -400.00
}],
"items": [{
"type": "RETURN",
"quantity": -2,
"grossPaidPrice": 400.00,
"taxAmount": 80.00,
"taxPercent": 25.00,
"sku": "10015563434",
"articleNumber": "2324234",
"articleName": "Ipsum Wool Jacket",
"articleGroup": "Jackets",
"marginPercent": "25.00",
"awardsPoints": false
}]
}
```
## Return matching logic
When a customer returns an item, Customer Engagement needs to match that returned item with the original purchase to display it in the GUI but also to ensure the correct adjustment of points. If the purchase awarded points, for example, the return should then remove them again.
The process of return matching involves retrieving potential matches and confirming them like this:
1. Fetch all returned items for a specific import.
2. Attempt to find purchase items that match the returned items by SKU. Or, if an SKU is not found, by `ArticleNumber`.
3. If no matching purchase item can be found, exit the process here. If a matching purchase can be found then update the purchase item in the Customer Engagement database to indicate that it has been returned.
If there are multiple purchases that match the return, the return will be connected to the latest purchase made before the return date.
4. If points are being used, the points total will have to be adjusted. If the price differs between the purchase and the return, the points deduction will be based on the points earned from the purchase, not those calculated from the return price.
For example: A purchase with value 299 SEK awards 299 points. A return is made and the matching purchase is located. However the return value, for whatever reason, is 250 SEK. The points removed will be 299 since that's what was originally earned for that purchase.
# Transaction field definitions
Source: https://developer.voyado.com/docs/transactions/transaction-field-definitions
Customer Engagement expects dates and times to be formatted according to [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) with Time Zone Designators. For example:
```bash theme={null}
2021-11-12T10:14:00+01:00
```
This represents 10:14 on the 12th of November, 2021, in a time zone one hour ahead of [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
Use local time with an offset, like in the example shown, instead of converting to UTC time.
## Transactions
The fields are as follows:
A value to match against the specified `customerKeyType` and `contactType`. If a transaction is submitted with a contact match key that does not exist in the system, that transaction will be *skipped* and not imported.
What the `matchKeyType` value represents. Options are: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email.
If used, matching will only be done for this contactType. If NOT used the default value will be "Member".
If a transaction already exists with this `uniqueReceiptId` the new transaction with the same value will be seen as a duplicate and ignored.
Datetime when order was first created formatted according to ISO 8601. Example: 2017-09-06T15:55:54+01:00.
The external id for the store (usually a numerical code).
The currency code according to ISO 4217 for the currency that the customer paid in (local currency). Example: NOK, SEK, EUR.
The total price paid by the customer including VAT. A decimal point (.) is always used as decimal separator. If the transaction is of type RETURN then `totalGrossPrice` should be negative.
All payment methods used in this transaction.
One row per line item in the transaction.
The transaction number, does not need to be unique.
Currency values for a transaction should be in the local currency. This multiplier is used to convert those to a group currency when storing them for segmentation and reporting. Omitting this will cause problems.
One row per used reward voucher.
One row per used promotion.
While `exchangeRateToGroupCurrency` is not mandatory, it's recommended in order to ensure that currency conversions are correct. If no exchange rate is sent, Customer Engagement will use the fallback conversion set up in the back-end.
If `contact.matchKeyType` is set to `contactId`, then `contact.contactType` is not a required field. In this case, if the value is not given, Customer Engagement will just use whatever your default contact type is.
## paymentMethods\[row]
A string, for example: “card”, “cash”, “creditcard”, “swish”, “klarna” (max 245 characters).
Amount as a decimal. This can't be empty.
Descriptive text (max 255 characters).
Additional data regarding the specific payment method. This field is accepted in the request but is not stored, processed, or available for segmentation in Customer Engagement. If you need to act on or segment by this information, contact your Voyado team so they can advise on the best approach.
## items\[row]
A line item can either be a PURCHASE or a RETURN.
Stock keeping unit.
Can be the same as the SKU.
The name.
Number of units sold in this line item. Must be negative for a return.
The paid price including VAT for this line item. Note: always withdraw discount values for the item itself or the distributed discount value for a total discount. Read more under Discounts.
The VAT paid for this line item.
The VAT (moms) percentage for this line item.
The group.
The margin in percent on this order line. Can't be empty or negative. Note that your Customer Engagement instance needs to be activated for searching on margins. Please contact your Voyado team for configuration requests.
Flag that controls if the line item should award points or not when generating reward points. Values are "true" or "false". If not specified, this will default to "true".
Key/value pairs for additional data regarding the transactional line item apart from the article meta-data.
Could be several sources of discounts for the total discount. One row per discount type.
The `grossPaidPrice` value sent to Customer Engagement always reflects the total price paid for a specific item or multiples of that item. So if `quantity` for an item is greater than 1 (or less than -1) then `grossPaidPrice` is the total price of all those items. Or to put it another way, the calculation of (quantity \* item price) is already done. Of course, if `quantity` is 1, then `grossPaidPrice` is just the single item price.
For returns, `quantity` is always negative but `grossPaidPrice` is still positive.
## Discounts - items\[row].discounts\[row]
Customer Engagement requires discounts to be taken care of before the data is sent. The `grossPaidPrice` should always describe the amount the contact has paid for the item, meaning that the discount values withdrawn with the following patterns:
* Full discounts (*e.g. 20% off the whole purchase*) should always be applied for every line item, equally distributed.
* Specific transaction item discounts should be withdrawn for the specific line item only.
Regardless of the nature of a discount, `item.discount` can be used to tell Customer Engagement what discounts have been used. If a line item is exposed to both a full discount, for instance 20% on a whole purchase, and a 100 SEK off for that article, these are combined to make the total value withdrawn from the original price. These aggregated row values are stored as a parameter for searching in Customer Engagement.
![Screenshot of Customer Engagement showing how the aggregated row values can be used as a search parameter]()
In Customer Engagement the search locates every transaction connected to a particular contact that contains one or more items that have been exposed to discounts greater/less/equal to a total value or total percentage of the original price.
Searching using discounts needs to be activated in your set-up. Please contact your Voyado team about this.
Discount value in the local currency. Should always be negative. Searching for discounts in Customer Engagement is possible.
Type of discount.
A description.
## usedRewardVouchers\[row]
The unique ID number of the reward voucher to be redeemed when saving the transaction.
## usedPromotions\[row]
The ID for the main promotion. Can be used to link the purchase to a promotion.
The ID for the "instance" of the promotion assigned to a contact.\
Don't confuse the `couponId` (for an individual contact) with the `promotionId` (the "template" used).\
Voyado recommends you use `couponId` over `promotionId` if possible, to avoid ambiguity in matching.
## Validations
* `discounts.value` should always be negative
* A return should have `item.type` "RETURN" and the `quantity` should be negative
* A purchase should have `item.type` "PURCHASE" and the `quantity` should be positive
* A `quantity` should never be 0
* Sum of all `paymentMethods` should equal `totalGrossPrice`
* Sum of all `grossPaidPrice` should equal `totalGrossPrice`
* The `taxAmount` should equal `grossPaidPrice` - `grossPaidPrice` / (1 + `taxPercent` / 100). The rounding error precision of this validation is by default 0.01. This value can be configured in the Customer Engagement backend to other values, or also turned off completely.
You can download the XSD schema [on the example files page](/docs/file-based-transfer/example-files).
# Webhook use cases
Source: https://developer.voyado.com/docs/webhooks/webhook-use-cases
Here are some examples of working with webhooks in Customer Engagement.
A complete list of events and latest payload specification can be found in the client's Svix portal.
## 1 - Contact preferences & consents
**Preferences** are a contact's communication channel opt-ins — the acceptsEmail, acceptsPostal, and acceptsSms boolean flags that define how a contact wants to be contacted.
**Consents** are formal agreements a contact makes regarding their data or account (e.g., "Do you agree to receive our newsletter?" or membership terms). Once set, a consent can never revert to "Not set."
The contact preferences in use in Customer Engagement are:
* acceptsEmail
* acceptsSms
* acceptsPostal
Other data regarding a contacts legal settings can be encoded as consent values in Customer Engagement. These are handled for every contact as custom fields on a per brand/client level.
To get all consents for your Customer Engagement environment use the following endpoint:
```http theme={null}
GET /api/v3/consents
```
As a retailer, you will often need to show the preferences, and sometimes the consent values, for a contact. For example on **My Pages** or at the checkout. And you will need to be sure the values shown are correct.
Since Customer Engagement often is the master of these settings, the preferences and consents will either have to be fetched every time they are needed, or you'll need some system in place to **constantly poll Customer Engagement** for the current values.
Neither way is efficient. This is why webhooks are a good solution.
### Webhook solution
For this situation, you create a webhook for the systems you want to keep updated about contact preference changes to your contacts in Customer Engagement. Then, whenever a preference is changed in Customer Engagement, the webhook will be used to inform all the subscribed external systems, keeping them all in sync with Customer Engagement.
The webhooks available for syncing of contact preferences are:
Triggered whenever the `acceptsEmail` preference changes
Triggered whenever the `acceptsSms` preference changes
Triggered whenever the `acceptsPostal` preference changes
Customer Engagement also supports a dedicated webhook for changes in consent-typed fields:
Triggered whenever a consent value for a contact is changed
```json Payload structure theme={null}
{
"eventId": "ac01d383-b83f-45b1-a60b-275bc7bba6b2",
"eventType": "contact.consent.changed",
"isEncrypted": false,
"payload": {
"consentAlias": "myConsentAlias",
"consentValue": true,
"contactId": "e5f70fe1-a0cf-4d16-898e-b3d800ff4103",
"dateChanged": "2026-01-20T16:28:38.985631+01:00"
},
"tenant": "myTenantName"
}
```
The webhooks for contact preferences and consents are only triggered for *already existing contacts*. They will not be triggered when a contact is created.
Be aware of the [legal requirements](/docs/webhooks/webhooks#legal-requirements) when working with webhooks.
## 2 - Contact changes
Many retailers operate several systems that need access to up-to-date customer data, such as e-commerce, POS, CRM, customer service, or data platforms. If Customer Engagement is used as the source of truth for your customer data, contact webhooks can be used to keep those systems synchronized in your system whenever this data changes.
The webhooks available for changes to contact data are:
Triggered when a contact is created in Customer Engagement.
```json Payload structure theme={null}
{
"eventId": "4ff4d68b-d299-4a17-81cc-e81abbf8932f",
"eventType": "contact.created",
"isEncrypted": true,
"payload": {
"careOf": "c/o John Smith",
"city": "Stockholm",
"contactId": "515c1b2a-7124-4bb9-826b-aedbbe5da8c4",
"contactTypeId": "Member",
"countryCode": "SE",
"creationTime": "2024-03-15T10:30:15Z",
"customAttributes": {
"myCustomAttribute": "myCustomAttributeValue"
},
"dateOfBirth": "2004-02-17",
"email": "john.doe@example.com",
"externalId": "CRM-12345",
"firstName": "John",
"gender": "male",
"language": "sv",
"lastName": "Doe",
"marketingGroupId": "ce62abff-aeb5-45b1-90f0-909194f33c29",
"memberNumber": "1234567",
"mobilePhone": "+46701234567",
"postalCode": "11122",
"registrationByStoreId": "560d70fe-7a47-43af-87d4-875afe4f8cc3",
"registrationDate": "2024-03-15T10:30:00Z",
"registrationSourceType": "API",
"registrationSpecificSource": "newsletter-signup",
"street": "Storgatan 1",
"swedishFinnishPersonalIdentityNumber": "20040217-7935"
},
"tenant": "myTenantName"
}
```
Triggered when a contact is updated in Customer Engagement.
```json Payload structure theme={null}
{
"eventId": "4ff4d68b-d299-4a17-81cc-e81abbf8932f",
"eventType": "contact.updated",
"isEncrypted": true,
"payload": {
"careOf": "c/o John Smith",
"changedValues": [
{
"path": "Email",
"previousValue": "previousEmail@email.com",
"value": "myNewEmail@email.com"
}
],
"city": "Stockholm",
"contactId": "515c1b2a-7124-4bb9-826b-aedbbe5da8c4",
"contactTypeId": "Member",
"countryCode": "SE",
"creationTime": "2024-03-15T10:30:15Z",
"customAttributes": {
"myCustomAttribute": "myCustomAttributeValue"
},
"dateOfBirth": "2004-02-17",
"email": "john.doe@example.com",
"externalId": "CRM-12345",
"firstName": "John",
"gender": "male",
"language": "sv",
"lastName": "Doe",
"marketingGroupId": "ce62abff-aeb5-45b1-90f0-909194f33c29",
"memberNumber": "1234567",
"mobilePhone": "+46701234567",
"postalCode": "11122",
"registrationByStoreId": "560d70fe-7a47-43af-87d4-875afe4f8cc3",
"registrationDate": "2024-03-15T10:30:00Z",
"registrationSourceType": "API",
"registrationSpecificSource": "newsletter-signup",
"street": "Storgatan 1",
"swedishFinnishPersonalIdentityNumber": "20040217-7935",
"updatedViaSourceType": "API",
"updatedWithSpecificSource": "myEcom"
},
"tenant": "myTenantName"
}
```
Triggered when a contact is deleted in Customer Engagement.
```json Payload structure theme={null}
{
"eventId": "6a21bf40-56c1-49cf-ae6e-53b987ff2da4",
"eventType": "contact.deleted",
"isEncrypted": true,
"payload": {
"contactId": "d3bdcad4-3f90-46ce-be4c-b3d800dc7979",
"deletionReason": "cancelled membership"
},
"tenant": "myTenantName"
}
```
A typical use case for these webhooks is to create, update, or remove customer records in downstream systems whenever the customer profile changes in Customer Engagement.
The `contact.updated` event includes delta tracking through changedValues, which helps the system receiving the data to understand what has changed without having to infer it from the full payload.
## 3 - Loyalty
There are webhooks available for syncing of points and vouchers in Customer Engagement:
Triggered when points are added to a contact via the Customer Engagement UI or through an automation. The transaction is sent in the webhook.
This is *only* for customers using the point follower solution.
```json Payload structure theme={null}
{
"eventType": String,
"id": String,
"isEncrypted": Boolean,
"payload": : {
"amount": Decimal,
"contactId": String,
"pointDefinitionId": Int,
"source": String,
"description": String,
"userId": String,
"userName": String,
"reason": String,
"sourceId": String,
},
"tenant": String
}
```
Triggered whenever a contact's point balance is changed.
```json Payload structure theme={null}
{
"eventType": String,
"id": String,
"isEncrypted": Boolean,
"payload": : {
"balance": Decimal,
"contactId": String,
"accountId": Int,
"definitionId": String,
"balanceExpires": DateTimeOffset
},
"tenant": String
}
```
Triggered when a new reward voucher is created for a contact.
```json Payload structure theme={null}
{
"eventId": String,
"eventType": String,
"isEncrypted": Boolean,
"payload": {
"id": String,
"contactId": String,
"validFrom": DateTimeOffset | null,
"validTo": DateTimeOffset | null,
"currency": String,
"uniqueCode": String,
"rewardVoucherPayoutId": String | null,
"value": Decimal,
},
"tenant": String
}
```
The `rewardVoucherPayoutId` is the ID of the payout that the voucher was issued from. After you have migrated to the new reward voucher flow, `rewardVoucherPayoutId` will be populated with a value and `currency` and `value` will always reflect the group currency you have configured. If your integration relies on these values, make sure it handles them correctly.
In some retail setups, it is Customer Engagement that decides if a customer has been assigned a promotion, while another system is responsible for making that benefit available in checkout, e-com, or POS. This, the multichannel promotion assignment webhook, can be used to notify external systems when a promotion has been assigned, so they can create or expose the corresponding coupon or voucher. This supports event-driven orchestration across channels and helps external systems react when a promotion is assigned in Customer Engagement.
The event is intended to be triggered regardless of where the assignment originated: via the UI, an automation activity, or over the API.
```json Payload example theme={null}
{
"eventId": "171c62d9-1007-4453-ab0b-e5bda4ace6e2",
"eventType": "promotion.multiChannel.assigned",
"isEncrypted": false,
"payload": {
"contactId": "a0e0a130-9fd1-4180-9f2e-0d38b1c2a2e4",
"promotionAssignmentId": "7e5866cb-441f-433e-87c7-048bf8c9e41d",
"promotionId": "d22615d8-dd23-4b40-832b-3fbafb4f2fbf",
"timestamp": "2026-07-15T14:06:47.301Z"
},
"tenant": "test-tenant"
}
```
# Introduction to webhooks
Source: https://developer.voyado.com/docs/webhooks/webhooks
A webhook can be seen as a reverse API. Instead of a user polling an API endpoint in a system (Customer Engagement, for example) to check for new data, the user can instead configure an URL in that system that can be called only when there is new data. This, essentially, is a webhook.
Structurally, a webhook is just a HTTP POST to an open API. They are simpler than an API endpoint, but have less functionality.
Webhooks, for example, don't allow pushing, deleting or updating data in another system, only receiving data. When you're only sending *specific data occasionally* webhooks might be a good solution.
You only receive data over a webhook when an event occurs. So if the other system doesn't call your webhook with data you can't be sure if it's because no events are occurring, or if the other system is down. Keep this in mind.
The advantages of webhooks are therefore:
* A simpler integration
* Less data being passed
* No polling needed
* Updates only sent when changes happen
## Webhooks currently available
Currently these webhooks can be used in Customer Engagement:
This webhook with the ID `contact.acceptsEmail.changed` is triggered whenever the `acceptsEmail` preference changes for an already existing contact.
This webhook with the ID `contact.acceptsSms.changed` is triggered whenever the `acceptsSms` preference changes for an already existing contact.
This webhook with the ID `contact.acceptsPostal.changed` is triggered whenever the `acceptsPostal` preference changes for an already existing contact.
The webhook with the ID `contact.consent.changed` is triggered for changes in consent-typed fields on a contact.
This webhook with the ID `loyalty.addPoints` is triggered whenever points are added to a contact via the Customer Engagement UI or through an automation. The transaction is sent in the webhook.
This is used *only* for customers using the point follower solution.
This webhook with the ID `point.balance.updated` is triggered whenever a contact's point balance has changed.
This webhook with the ID `reward.voucher.created` is triggered whenever a reward voucher is created for a contact.
This webhook with the ID `promotion.multiChannel.assigned` is triggered when a multichannel promotion is assigned to a contact in Customer Engagement.
This webhook with the ID `contact.created` is triggered whenever a new contact is **created** in Customer Engagement.
This webhook with the ID `contact.updated` is triggered whenever a new contact is **updated** in Customer Engagement.
This webhook with the ID `contact.deleted` is triggered whenever a new contact is **deleted** in Customer Engagement.
Read more about how each webhook event can actually be used in the use-cases article:
Even though you are free to configure subscriptions to all the available events, you'll still need to reach out to your Voyado Account Manager or Voyado support to activate the events that you want to subscribe to, so that the data actually gets sent from Customer Engagement.
## Requirements
Here are the various requirements for working with webhooks in Customer Engagement.
### Basic client requirements
To receive webhooks from Customer Engagement you will need to develop and deploy a web service. This is basically an API with a POST endpoint. It's common to use one service for all webhooks, and then distribute the incoming events internally to your different systems.
When developing your webhooks, a service like [Svix Play](https://www.svix.com/play) or [ngrok](https://ngrok.com/) can be used to receive webhooks from the internet on your local development machine.
Your web service must be accessible over the internet. Fixed source IP addresses can be used if your endpoint is behind a firewall or NAT.
There should be no authentication at the receiving endpoint. Instead, you'll verify that the events received are sent from Voyado Customer Engagement using signatures and a shared signing secret.
The service you provide must be able to scale with the load.
Voyado's webhooks service provider Svix has good documentation on how to consume webhooks.
When you are implementing webhooks in Customer Engagement and move to a production environment, you'll need to approve Svix (Voyado's webhooks provider) as a GDPR sub-processor.
While it is the client themselves who decides how many layers to implement, layers 1 and 2 above are the absolute minimum.
## Setting up a webhook in Customer Engagement
Once you have created your webhooks, you'll need to set them up in Customer Engagement. The steps are:
Contact your Voyado account manager to enable webhooks in your Customer Engagement instance. Depending on your agreement, a supplement might be required. The webhooks module must then be activated in the Customer Engagement back-end, and the correct permissions granted to users.
Now you'll configure the client endpoint in the Customer Engagement UI.
Go to **Administration/Webhooks Dashboard** to see the Webhooks already set up.
Then select **+ Add Endpoint** to add another.
![Webhooks already set up]()
After adding your endpoint, select it and then choose which event you want to send to it:
![Choose event to send]()
Get the Signing Secret used for verification, as well as the Payload Encryption Key (if you are using it) from your Voyado account manager. When sending these to somebody else, be careful to use the same trusted method as when sharing API-keys. The signing secret is created and handled by Svix, and can be rotated if needed.
![Choose event to send]()
You can use the “Testing” functionality in Svix to send test-events to the endpoint. Check the log for errors.
If you need it, configure a rate limit so the client endpoint can handle the load.
You can also choose to configure a custom header with some kind of token to further increase security.
## Disabling of failing endpoints
If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled and an operational webhook (EndpointDisabledEvent) will be sent.
For example, if your receiving service responds with 404 for whatever reason, such as as a contact not being present, over a 5 day period, this behaviour is triggered and the endpoint will be disabled. See more details at the Svix docs:
Your base path URL will be referred to as `` from this point on.
## Authentication
Every call to the App Push API requires a Bearer token:
```http Authorization theme={null}
Authorization: Bearer
```
Identifies your app to Customer Engagement. Passed as a Bearer token. You will set this in [Config Hub](https://help.engage.voyado.com/hc/en-gb/sections/21844508239004-Config-Hub) as part of configuring push settings.
The `PublicApiKey` is best thought of as an identifier for your app, and not a secret to be protected. It ships inside your compiled app binary, so it can be found by decompiling your IPA/APK. But that is fine - the key is write-only and scoped to registering devices and reporting events for one specific app configuration. It cannot read, modify, or delete any other tenant's or app's data. Treat it how you'd treat any other client-visible app identifier.
If you'd rather avoid shipping this identifier inside your app at all, see [Backend-mediated integration](#backend-mediated-integration) below.
## The endpoints
There are three endpoints and you use your base path to build the URLs like this:
| Endpoint | POST request URL |
| :- | :- |
| Register | `POST /installations` |
| Unregister | `POST /installations/unregister` |
| Event | `POST /events` |
In each case, insert your own version of the base path.
Here are the endpoints in more detail:
Used to register a device to a certain contact or update its record. The JSON payload contains the attributes:
* `platform`
* `push_token`
* `contact_id`
* `app_version?`
* `os_version?`
* `device_model?`
* `locale?`
* `timezone?`
```bash Example call theme={null}
# Register
curl -X POST /installations \
-H "Authorization: Bearer $PUBLIC_API_KEY" -H "Content-Type: application/json" \
-d '{"platform":"ios","push_token":"","contact_id":""}'
```
Used to stop a certain device from receiving pushes, for example on logout or opt-out. The JSON payload contains the attributes:
* `push_token`
```bash Example call theme={null}
# Unregister (logout)
curl -X POST /installations/unregister \
-H "Authorization: Bearer $PUBLIC_API_KEY" -H "Content-Type: application/json" \
-d '{"push_token":""}'
```
Used to report what happened when a push arrived or was interacted with. Sent as an "events" array of JSON objects:
* `type`
* `message_id`
* `contact_id`
* `recipient_id`
* `occurred_at`
* `app_state?`
* `deeplink?`
* `action_id?`
```bash Example call theme={null}
# Report an opened notification
curl -X POST /events \
-H "Authorization: Bearer $PUBLIC_API_KEY" -H "Content-Type: application/json" \
-d '{"events":[{"type":"opened","message_id":"","contact_id":"","recipient_id":"","occurred_at":"2026-07-02T10:20:42Z"}]}'
```
### Failure modes
| Situation | Response |
| :- | :- |
| Missing or malformed `Authorization` header | 401 unauthorized |
| Key doesn't match the tenant/app config | 401 unauthorized |
| Invalid value of base-path | 400 invalid\_path |
## Core concepts
Here are some core concepts for working with the App Push API.
### 1. An installation is a device
An "installation" is a single app install on a single device. It is identified solely by its push token (the APNs device token or FCM registration token). If the push token changes, the installation should be updated.
### 2. Binding a contact
The `contact_id` is the existing Customer Engagement contact identifier for the signed-in user. Registering an installation with a `contact_id` *binds* that device to that contact. Customer Engagement can then send targeted pushes to it.
### 3. Registration is idempotent
Calling the register endpoint with the same push token twice doesn't create a duplicate, it just updates the existing record (for example by giving a new `contact_id` or refreshed device metadata).
## Integration guidance
This section describes *how* to use the API. These are the patterns every integration should follow.
### 1. Authenticate first
Only call the register endpoint once you know, with certainty, who the current user is — that is, you have a valid `contact_id` from your own app's authentication/session system.
Voyado does not know or derive your contact identity; your app must supply it. Registering a push token using the wrong (or a stale) `contact_id` means personalized pushes could go to the wrong person, so this ordering matters: confirm identity first, then register.
### 2. Register early
Register the device as early as possible in your app's lifecycle but only when *both* of these conditions are met:
You have their `contact_id` from your own authentication system.
This condition is implicit: you cannot obtain a push token from the OS at all until the user has granted notification permission, so simply having a token in hand already satisfies this.
In practice this usually means to *request notification permission* at an appropriate point in your onboarding flow, and as soon as you have both a push token and a signed-in user, *call register*. For most apps that's at app launch, if already logged in or immediately after login.
### 3. Minimize redundant calls
Registration is idempotent and safe to call repeatedly, but you should still avoid calling it more than necessary. So you should:
* **Cache** the last successfully registered `(push_token, contact_id)` pair locally on the device
* **Only call register again** when either value changes, such as when the push token rotates, the user logs in as a different contact, or you haven't registered yet at all.
* Don't call register "just in case" on every single app launch if neither value has changed since your last successful call. Doing this will not break anything, but it creates unnecessary network traffic and battery cost.
### 4. Unregister on logout
When the user logs out, call the unregister endpoint along with the device's current push token:
```http theme={null}
POST /installations/unregister
```
This is the recommended way to fully remove the installation from Customer Engagement.
If the same device is used to log back in later (by the same or a different contact), your app should call the *register* endpoint again with the current push token and the newly authenticated `contact_id`. As in, a completely fresh registration.
Also call the unregister endpoint whenever a user explicitly opts out of push notifications in your app's settings, or when you detect that OS-level notification permission has been revoked.
## Endpoints in detail
Here is a more detailed run-down of the three endpoints mentioned above and how they are used.
Important points:
* All requests and responses attribute names use JSON with *snake\_case* field names.
* All endpoints use the same base path and require the `Authorization: Bearer ` header
### Register installation
The endpoint is:
```http Register endpoint theme={null}
POST /installations
```
This creates or updates an installation. This call is idempotent, which means it is safe to call every time your app has a current push token and a signed-in contact, without checking whether the device is already registered.
The following attributes can be used:
This will be "ios" or "android".
The APNs device token or FCM registration token. This is the installation's identity.
Your Voyado contact identifier for the signed-in user.
Your app's version string. (See note below.)
Device OS version. (See note below.)
Device model identifier. (See note below.)
Device locale, for example `en-US`. (See note below.)
IANA timezone, for example `Europe/Stockholm`. (See note below.)
`app_version`, `os_version`, `device_model`, `locale`, and `timezone` are metadata that Voyado does not currently use for any targeting, filtering, or business logic. It is recommended to send them anyway as they are likely to power future capabilities (such as minimum-OS-version rules or locale-aware send scheduling), and it costs you nothing to include them now rather than adding them retroactively later.
This is an example request for tenant "acme" (using a likely value for ``):
```Http Request details theme={null}
POST https://app-push-prod.voyado.com/api/v1/acme/abc123/default/installations
Authorization: Bearer
Content-Type: application/json
```
The payload:
```json Registering an installation theme={null}
{
"platform": "ios",
"push_token": "a1b2c3d4e5f6...",
"contact_id": "496977ad-1d09-4993-9957-ef019eaa1eb3",
"app_version": "3.4.1",
"os_version": "26.4.4",
"device_model": "iPhone15,2",
"locale": "sv-SE",
"timezone": "Europe/Stockholm"
}
```
A successful request gives a *HTTP 202 Accepted* response with an empty body.
| Status | Code | When |
| :- | :- | :- |
| `400` | `invalid_json` | Malformed JSON body. |
| `400` | `invalid_request` | Missing `push_token` or `platform`. |
| `400` | `invalid_platform` | `platform` is not "ios" or "android". |
| `401` | `unauthorized` | Missing/invalid Bearer token. |
### Unregister installation
The endpoint is:
```http Register endpoint theme={null}
POST /installations/unregister
```
This entirely removes the installation identified by the push token sent. Use this on logout and when the user explicit opts out.
The push token is sent *in the request body*, not in the URL. A push token is a sensitive value and should never appear in a URL path, since URLs are logged by proxies, browsers, and monitoring tools far more readily than request bodies.
The push token identifying the installation that is to be removed.
```http Request details theme={null}
POST https://app-push-prod.voyado.com/api/v1/acme/abc123/default/installations/unregister
Authorization: Bearer
Content-Type: application/json
```
The payload:
```json Registering an installation theme={null}
{ "push_token": "a1b2c3d4e5f6..." }
```
A successful request gives a *HTTP 202 Accepted* response with an empty body.
| Status | Code | When |
| :- | :- | :- |
| `400` | `invalid_json` | Malformed JSON body. |
| `400` | `invalid_request` | Missing `push_token`. |
| `401` | `unauthorized` | Missing/invalid Bearer token. |
### Report events
An engagement events describes what happened to a push after it was sent. The endpoint to send one or a batch of events:
```http Report events endpoint theme={null}
POST /events
```
Events are validated as a *whole batch* before any of them are accepted. If any event in the batch is invalid, the whole batch is rejected.
```json Events request body theme={null}
{
"events": [
{ /* event */ },
{ /* event */ }
]
}
```
One of `delivered` or `opened` or `dismissed` - See "Event types" below for more details.
Echoed back from the push payload your app received.
Echoed back from the push payload your app received.
When the event happened, from the device's clock. ISO-8601 format.
The Voyado contact this event relates to.
This will be "foreground", "background", or "killed", which is the app's state when the event occurred.
Echoed from the push payload, if the notification carried one and the user tapped it.
The identifier of a custom notification action button the user tapped, if the notification included custom actions and tapping one opened the app. Reported alongside `opened`.
| Type | Fire when: |
| :- | :- |
| `delivered` | The push arrived on the device (before the user does anything with it). |
| `opened` | The user tapped the notification (or a custom action button that opens the app). |
| `dismissed` | The user dismissed the notification without opening it (Android only — iOS has no reliable equivalent). |
Every push Voyado sends includes both a `message_id` and `recipient_id` in its payload specifically so your app can echo it back on every event. This is how Voyado correlates "delivered" and "opened" events with the original send. Consult your platform's push payload documentation for exactly where this value appears in the payload your app receives.
```http Reporting a batch of events theme={null}
POST https://app-push-prod.voyado.com/api/v1/acme/abc123/default/events
Authorization: Bearer
Content-Type: application/json
```
The payload:
```json The events theme={null}
{
"events": [
{
"type": "delivered",
"message_id": "msg-abc123",
"contact_id": "496977ad-1d09-4993-9957-ef019eaa1eb3",
"recipient_id": "572c44be-945d-879-41a2-77826b6bb21b",
"occurred_at": "2026-07-02T10:20:15.123Z",
"app_state": "background"
},
{
"type": "opened",
"message_id": "msg-abc123",
"contact_id": "496977ad-1d09-4993-9957-ef019eaa1eb3",
"recipient_id": "572c44be-945d-879-41a2-77826b6bb21b",
"occurred_at": "2026-07-02T10:20:42.456Z",
"deeplink": "myapp://product/sku-123"
}
]
}
```
A successful request gives a *HTTP 202 Accepted* response:
```json theme={null}
{ "accepted": 2 }
```
| Status | Code | When |
| :- | :- | :- |
| `400` | `invalid_json` | Malformed JSON body. |
| `400` | `invalid_request` | Empty or missing `events` array. |
| `400` | `invalid_event` | An event is `null`, or missing `message_id` / `occurred_at` / `contact_id`. |
| `400` | `invalid_event_type` | `type` is not one of the event types above. |
| `401` | `unauthorized` | Missing/invalid Bearer token. |
Every error from every endpoint uses the same envelope:
```json Error response theme={null}
{
"error": {
"code": "invalid_request",
"message": "platform and push_token are required",
"request_id": "0f1e2d3c-..."
}
}
```
The `request_id` value uniquely identifies the request server-side; include it when contacting support about a specific failed call.
What the delivered event is designed to mean is that your app push has “reached" the user, and that it is now possible for them to see it (think of an email reaching an inbox). However the notification permissions on a user’s device can vary wildly. For example, a user may allow pushes but choose to show them not as a banner but as a red notification badge on the app icon. Therefore it is hard to give exact guidance on when you should send the “delivered” event and it is up to you to implement it in a way that works for you.
## Sending a push
Here are example payloads for sending a push on Android and on iOS.
```json theme={null}
{
"voyado_push_service_message_id": "3f2c9b1e-8a4d-4e77-9c2a-1d7b6f0a5e3c",
"voyado_push_service_contact_id": "322c4bbe-9ccd-3e79-91aa-17826b6bb21a",
"voyado_push_service_recipient_id": "572c44be-945d-879-41a2-77826b6bb21b",
"body": "20% off everything this weekend only!",
"title": "Weekend sale",
"voyado_push_service_deeplink": "https://shop.example.com/campaigns/weekend-sale",
"voyado_push_service_image_url": "https://cdn.example.com/campaigns/weekend-sale.png"
}
```
```json theme={null}
{
"aps": {
"alert": {
"title": "Weekend sale",
"body": "20% off everything this weekend only!"
},
"sound": "default",
"mutable-content": 1
},
"voyado_push_service": {
"message_id": "3f2c9b1e-8a4d-4e77-9c2a-1d7b6f0a5e3c",
"contact_id": "322c4bbe-9ccd-3e79-91aa-17826b6bb21a",
"recipient_id": "572c44be-945d-879-41a2-77826b6bb21b",
"deeplink": "https://shop.example.com/campaigns/weekend-sale",
"image_url": "https://cdn.example.com/campaigns/weekend-sale.png"
}
}
```
## Migrating from another provider
If you're currently sending push notifications through a different push provider and want to move to Voyado, it's recommended to follow a *gradual, dual-provider transition* rather than a sudden total cut-over.
This works best when your app's implementation can actually support running two providers side by side. So check that first. Some existing push SDKs register their own OS-level callbacks (such as `UNUserNotificationCenterDelegate` on iOS or `FirebaseMessagingService` on Android) and don't forward those callbacks anywhere your own code can intercept them, which can make it difficult or impossible to also wire up Voyado registration and event reporting alongside them.
Only your app's developers can assess whether your current setup allows for this. If it doesn't, talk to your Voyado contact about alternative migration approaches.
Add Voyado registration (this API) to your app alongside your existing provider's SDK. Your app now registers with *both* providers whenever a user authenticates.
As your existing users open the app over the following days and weeks, each one registers with Voyado automatically — no forced re-login, no push notification required to trigger it, no big migration event. Coverage grows organically with normal app usage.
How many registered contacts is "enough" to switch is entirely a business decision on your side — Voyado doesn't enforce or suggest a threshold. Once you're satisfied with coverage, you cut over.
Registering a device with Voyado never causes a push to be sent, this must still be explicitly done. This means that running both providers' registration side by side during the transition does *not* risk duplicate pushes on its own.
Do this when you're fully cut over and confident that you no longer need the legacy SDK.
You should not send pushes from both the old provider and from Voyado at the same time during the transition. Doing this creates a risk of sending the push twice.
## Backend-mediated integration
Not every customer wants their mobile app talking to Voyado directly. If you'd rather route push registration and event reporting through your own backend, that's fully supported.
In this case your backend just calls the same API as discussed above on your app's behalf.
```mermaid theme={null}
flowchart LR
A["📱 Mobile app"] -->|"registers device"| B["⚙️ Your backend"]
B -->|"App Push API"| C["🔔 Voyado App Push API"]
subgraph yours ["You build this"]
A
B
end
subgraph voyado ["Voyado provides this"]
C
end
style A fill:#f0f4ff,stroke:#4a6cf7,stroke-width:2px
style B fill:#f0f4ff,stroke:#4a6cf7,stroke-width:2px
style C fill:#fff4ed,stroke:#f77f4a,stroke-width:2px
```
Important points to consider are:
* Your backend calls **the exact same Voyado endpoints** (register, unregister, events) as those described above, with the exact same fields.
* **Your backend can supply `contact_id` itself** when calling Voyado, since it already knows which of your own users is making the request (via your existing session/auth system), Your mobile app only needs to hand its push token to your backend, and not to Voyado directly.
* The key **never ships inside your distributed app binary** where it could be extractable by unpacking the IPA/APK. This is a meaningful security advantage. If keeping the key off-device matters to you, this pattern is worth the extra implementation effort.
Everything else in this guide — when to register, when to unregister, the migration approach — applies in the backend-mediated case. It's only *who* makes the HTTP call to Voyado that changes.
# Bounced and unsubscribed
Source: https://developer.voyado.com/docs/campaigns/bounced-and-unsubscribed
Two important concepts when dealing with send-outs in Customer Engagement are *bounced* and *unsubscribed*.
## Bounced
When an email or SMS sent from Customer Engagement can't be delivered, this is known as a *bounce*. There are two kinds of bounces, with different consequences in Customer Engagement:
* A **soft bounce** means the email or SMS can't be delivered. This can happen because the user's inbox is full, or the mail server has temporary issues. When the next send-out is done from Customer Engagement, addresses / mobile numbers that have soft bounced will be tried again. If an email address soft bounces 10 consecutive times, Customer Engagement will block it for further communication (although this is not the case for SMS).
* A **hard bounce** means that the ISP (for email) or the mobile carrier (for SMS) is permanently not reachable. This might happen because the domain name doesn’t exist, the recipient is unknown, or the phone number is no longer active. Customer Engagement will deactivate an email address / mobile number that has hard bounced, which will then be shown in red and struck through on the contact card.
## Unsubscribed
An email address or mobile number is considered unsubscribed for a contact when the contact owning it has actively opted out of receiving marketing information. Their email / phone number is probably still valid, but the contact does not want it used for marketing send-outs.
## Starting up with Customer Engagement
When you're moving to Customer Engagement from another platform it's important to realize that Customer Engagement will *not* automatically get updated about historical email bounces and unsubscribed contacts. Therefore you'll need to manually update Customer Engagement with the emails and mobile numbers that should not be used for send-outs.
Doing this will ensure you don’t send communication to old and inactive addresses, since that can be devastating to your sender reputation and risk flagging you as a spammer, which you don't want.
While it is possible to have the same email / phone number attached to several contacts, each email or phone number can only be used once in the same send-out. So if two contacts share an email (unusual, but it can happen) and are in the same send-out, only one will be mailed.
## Bounced and unsubscribed lists
Updating Customer Engagement with hard bounced and unsubscribed emails / phone numbers is done using a bounce list, which is a CSV file with a single row containing the emails that Customer Engagement can’t communicate with. These lists can be uploaded in the Config Hub. Once imported, hard-bounced emails are then stored in the database to make sure they are never used in email send-outs from Customer Engagement.
Read more about this in the Help Center:
Email addresses and phone numbers imported via a bounce list will be blocked for future send-outs. This applies both to contacts who currently exist in Customer Engagement with one of those emails / phone numbers, as well as future contacts created with one of these as their identifier.
# Email content population
Source: https://developer.voyado.com/docs/campaigns/email-content-population
In emails created in Customer Engagement, it's possible to add content that has been fetched from an external source. This requires the use of specific email modules that match the specific type of content.
The most common use case is populating product modules from a XML product feed (the Google format is recommended). Content can also be fetched from an external API endpoint.
Your product feed need to be accessible through an open URL so that Customer Engagement can fetch it. Your product feed can't be on a file or located in an FTP folder; it *must* be located on an open HTTP endpoint.
## Content from API endpoint
The information below covers the classic email editor. There are also dedicated articles about working with external / custom data in the new email Design Studio.
This is only relevant for the classic email editor and not for Design Studio.
### Request URL
Your custom API endpoint should be able to handle a search query with multiple product IDs that are comma separated, like in this example. Besides this requirement, the actual URL can be determined by you.
```http theme={null}
GET https://[customerdomain].com/api/endpoint/exampleID1,exampleID2,exampleID3
```
It is also possible to add several extra parameters to personalise the URL. The examples below use a parameter called locale which enables you to dynamically call for an endpoint connected to a specific country/language.
```http theme={null}
GET https://[customerdomain].com/api/{locale}/endpoint/
```
Or you could also do it this way:
```http theme={null}
GET https://[customerdomain].com/api?locale={locale}&id=exampleID1,exampleID2
```
These extra parameters are decided per project and configured by a product specialist at Voyado.
### Response JSON
This is an example of how a response should look like to match the Customer Engagement format:
```json theme={null}
[
{
"productNumber": "12334",
"description": "Superproduct 2000 Ultra, matte black",
"imageUrl": "https://customerimages.imgix.net/71303.jpg",
"originalPrice": "1 699 kr",
"discountPrice": "1 549 kr",
"discount": "- 9 %",
"link": "https://www.customerdomain.com/product/71303",
"fromPrice": "1 699 kr",
"name": "Superproduct 2000 Ultra",
"price": "1 549 kr",
"sellText": "Looking for Superproducts latest groundbreaking innovation? With the 2000 Ultra Superproduct has done it again. The 2000 Ultra offers..."
},
{
"productNumber": "12335",
"description": "Superproduct 2003 Ultra, matte white",
"imageUrl": "https://customerimages.imgix.net/product/71304.jpg",
"originalPrice": "1 699 kr",
"discountPrice": "1 549 kr",
"discount": "- 9 %",
"link": "https://www.customerdomain.com/product/71304",
"fromPrice": "1 699 kr",
"name": "Superproduct 2000 Ultra",
"price": "1 549 kr",
"sellText": "Looking for Superproducts latest groundbreaking innovation? With the 2000 Ultra Superproduct has done it again. The 2000 Ultra offers..."
}
]
```
## QR and barcodes in emails
Voyado has an online tool for generating QR and barcode images which can then be sent out in Customer Engagement emails. Such an image could encode something personal like a member number (for easier identification), a personal reward voucher number or an order number. These images could then be used by a POS to easily read that information from a customer’s mobile phone screen.
All the steps below should be considered **mandatory** to ensure the best possible email deliverability.
## Step 1 - The course “Introduction to Email Deliverability”
This online training course will give you the basics of emails deliverability and is strongly recommended. It serves as a foundation for your warmup phase before launch and shows you how to keep in the loop after the launch, helping you monitor and act when needed.
This table above shows the *recommended* maximum number of new contacts you can mail from Customer Engagement each week. For the recommended maximum send-out frequency per week, see the section “Suggestions for the warmup period” at the bottom of this article.
## Warmup planning - high volume case
This case is for when your monthly send-out volume is *more than* a million emails per month, or your contact database has *more than* 80 000 contacts with email marketing consent.
For this case, we suggest two different variants: “Activity based warmup” and “Randomized split warmup”. Read through both variants to decide which version suits your organization the best. If possible, and you have the relevant data, Voyado recommends “Activity based warmup”.
## Activity based warmup
To ensure you have the highest possible engagement level, and that you send to the best possible addresses, it is recommended to divide up your send-out groups and send-out volumes per week according to the tables below:
**Table 1: Sendout groups**
| Sendout group | When contacts last opened an email |
| - | - |
| Warmup Group 1 | 0 - 7 days |
| Warmup Group 2 | 8 - 14 days |
| Warmup Group 3 | 15 - 30 days |
| Warmup Group 4 | 31 - 60 days |
| Warmup Group 5 | 61 - 90 days |
| Warmup Group 6 | 91 - 120 days |
| Warmup Group 7 | 121 - 150 days |
| Warmup Group 8 | 151 - 180 days |
| Warmup Group non-active | 181 days and higher |
**Table 2: New contact allowance per week**
| Week | Max number of new contacts mailed |
| - | - |
| Week 1 | 25 000 |
| Week 2 | 50 000 |
| Week 3 | 75 000 |
| Week 4 | 100 000 |
| Week 5 | 125 000 |
| Week 6 | 125 000 |
| Week 7 and every week after | 100 000 |
This table shows the recommended maximum number of new contacts you should mail per week from Customer Engagement during the warmup.
Voyado recommends that you work with the so-called "Primary Warmup” and “Secondary Warmup”. See the following sections for how these work.
## The primary warmup
Here you will focus on warmup groups 1-8.
Start with warmup group 1 and add more and more volume as you get further into the warmup period.
The weekly sending allowance is stated in the table “Recommended new contact allowance per week” below. Voyado strongly suggests that you follow this for optimal deliverability and proper warmup of your IP-address.
**Table 3: Sendout structure**
| Warmup Group | When contacts last opened an email | Amount |
| - | - | - |
| Warmup Group 1 | 0 - 7 days | 32 000 |
| Warmup Group 2 | 8 - 14 days | 42 000 |
| Warmup Group X | ... | ... |
| Week | Warmup Group | Amount |
| - | - | - |
| Week 1 | Warmup Group 1 | 25 000 |
| Week 2 | Warmup Group 1 (7 000) + Warmup Group 2 (42 000) | 49 000 |
| Week X | ... | ... |
## The secondary warmup
Recipients who haven't opened any email in the last six months are a potential risk for your email deliverability. It could even be argued that inactivity over the previous 90 days is enough to be a potential risk. This all depends on how often you send and how you segment your send-outs.
For many businesses, however, even 180 days of inactivity may not be long enough to merit complete exclusion from future email send-outs. The recipients, for example, may be interacting in physical stores but might not be so active in the email channel. Or they may be “seasonal customers”. How then should this be handled?
It's all about balance and planning. Which takes us to the secondary warmup group.
The idea behind this is to gradually move contacts in and continuously monitor the effect of each group. Some suggestions to optimize this are:
* Before you start sending to this group, consider if you might benefit from a re-activation program for these contacts, such as giving some incitement for inactive contacts to re-engage in your email program. You could, for example, use an automation in Customer Engagement. If you choose to start sending to these contacts, our recommendation is that you add them in small groups (maximum of 5% new inactive contacts per week). This will give you good control in understanding how these contacts are performing.
* Even after re-engagement activities, you'll most likely still have some inactive recipients. Just as above, ff you choose to start sending to these contacts, the recommendation is that you add them in small groups (maximum 5% new inactive contacts per week).
* Even after these steps, you might still have contacts that are not re-activated. If these contacts are still eligible for communication from you, try alternative channels. Maybe SMS, for example, might be a better communications channel for them.
## Sendout groups and new contact allowance per week (randomized split)
If you don't have access to "Last Opened Date" for each recipient, consider splitting the list up randomly and sending according to the recommended send-out volumes below. With this approach, you'll send emails to both your active and inactive contacts from the beginning. It is therefore important to have a slower and more careful pace.
**Table 4: Recommended new contact allowance per week**
| Week | Max number of new contacts mailed from Customer Engagement |
| - | - |
| Week 1 | 10 000 |
| Week 2 | 20 000 |
| Week 3 | 40 000 |
| Week 4 | 60 000 |
| Week 5 | 80 000 |
| Week 6 | 100 000 |
| Week 7 and on | 80 000 |
The table above shows the recommended maximum number of new contacts you should send to form Customer Engagement each week. For the recommended maximum sendout frequency per week, consult the section “Suggestions for the warmup period" at the bottom of this article.
## Use your current platform in parallel with Customer Engagement to maintain your reach
As you only have a limited send-out volume in Customer Engagement during the warmup period, it's likely you'll want to reach out to the rest of the groups from your current platform. This is perfectly fine to do. This is how a split between the platforms can look:
**Table 5: Example 1 - Shared IP Pool (65 000 contacts)**
| Week | Platform | Contacts |
| - | - | - |
| Week 1 | New contacts emailed from Customer Engagement | 25 000 |
| Week 1 | Contacts emailed from your current platform | 40 000 |
| Week 2 | New contacts emailed from Customer Engagement | 40 000 |
| Week 2 | Contacts emailed from your current platform | 0 |
**Table 6\_ Example 2 - Dedicated IP and Activity based warmup (300 000 contacts)**
| Week | Platform | Contacts |
| - | - | - |
| Week 1 | Warmup group 1 from Customer Engagement | 25 000 |
| Week 1 | Warmup Groups 2 - 8 | 275 000 |
| Week 2 | Warmup group 2 from Customer Engagement | 75 000 |
| Week 2 | Contacts emailed from your current platform | 225 000 |
Ensure that all unsubscribed contacts from your current platform also are unsubscribed in Customer Engagement before the first send-out of each warmup week.
## Suggestions for the warmup period
Here are some important suggestions for the warmup period.
### Sendout frequency
Frequency of newsletters (which are defined as bulk sendouts to all or a large part of your total database) can be kept as normal during the warmup period, if that frequency is 3 sendouts per week or less. However, if the desired sendout frequency is higher, you should anyway keep it to a maximum of 3 newsletters per week from Customer Engagement during the following periods:
* The first three weeks (if sending less than a million emails per month)
* The first six weeks (if sending more than a million emails per month)
### Batchwise delivery
For mails sent during the warmup period, it is recommended that you split up your send-outs into batches (4 batches with an hour in between each batch) using Customer Engagement's “Batchwise Delivery”.
Even after the warmup period, you should continue using “Batchwise Delivery”, the recommendation now being to send in at least 4 batches with 30 mins between each batch.
### Monitoring your sendouts during the warmup period
Follow your open rate (and also your click rate trend) to understand potential effects of email filtering at the ISP:s. While this is extra important during the warmup period, it is also very important for your day-to-day business.
Find out more here:
# Get historical messages
Source: https://developer.voyado.com/docs/campaigns/get-historical-messages
The Customer Engagement API has three endpoints to fetch the latest SMS, email and postal messages saved for a specific contact.
```http Emails theme={null}
GET /api/v3/contacts/{contactId}/emailmessages
```
```http SMS theme={null}
GET /api/v3/contacts/{contactId}/smsmessages
```
```http Postal theme={null}
GET /api/v3/contacts/{contactId}/postalmessages
```
By default, the newest 100 messages will be fetched.
By adding the parameter `count` to your query, you can request any number up to the maximum of 500.
An actual request to this endpoint might look like this:
```http theme={null}
GET /api/v3/contacts/111d3329-7eef-45c0-37f9-ae9300a0dacei/emailmessages?count=350
```
This endpoint is primarily for first-line support platforms, allowing customer service employees to quickly troubleshoot a contact's sent messages without having to log into Customer Engagement.
### Response codes
You'll get one of these two response codes:
* '200' : OK
* '404' : ContactNotFound
### Example response and fields
```json theme={null}
{
"count": 2,
"items": [
{
"messageId": "c524e468-pee9-43d5-8f33-af3801140666",
"name": "test",
"sendDateTime": "2022-10-24T16:47:45+00:00",
"type": "SmsMessage",
"source": "Manual",
"isTransactional": false,
"status": "Delivered",
"messageLink": "https://myurl.customer.staging.eclub.se/Open/SmsOnline/Show/aOQaxknO1UOPRq84ARQDBB",
"messageText": "Hello and welcome to ExampleShop. Please add your consent and email here [[registrationUrl:123456c7-79bb-41d4-8db8-af2a00894f33]]"
},
{
"messageId": "d4afac12-2222-4d17-b009-af11009b9a1a",
"name": "Testauto",
"sendDateTime": "2022-09-15T07:26:32+00:00",
"type": "EmailMessage",
"source": "Automation",
"isTransactional": false,
"status": "Delivered",
"messageLink": "https://myurl.customer.staging.eclub.se/open/email/online/Eqyv1ICQF02wCa8FUKlejA/n0pgJu8BBkySna8RAHnP8w/8coDxC_inkCP_K8RAJuajA",
"messageText": "This is a test email."
}
]
}
```
Unique message ID.
Name of the message in Voyado.
Date and time when the message was sent, including offset.
Type of message. Possible values include `EmailMessage`, `SmsMessage`, and `PostalMessage`.
Where the message was sent from in Voyado Customer Engagement. Possible values include `Automation`, `Manual`, and `System`.
Indicates whether the message was sent as a transactional message. Does not take opt-in status into account.
Delivery status of the send-out. Example: `Delivered`
URL to the web version of the email.
The text content of an SMS message or the subject line of an email.
# Sending SMS
Source: https://developer.voyado.com/docs/campaigns/sending-sms
This is how to get started sending SMS to your customers from Customer Engagement.
In the Customer Engagement UI, go to **Administration/Config Hub** and then [Contact attributes](https://help.engage.voyado.com/hc/en-gb/articles/23406421398428-Contact-attributes).
Edit the standard attribute "Mobile phone" to make it active and visible on the contact card.
Decide the sender name for your SMS (this is the name shown in the SMS inbox).
Decide on the opt-out method.
* A stop word, allowing the customer to send a certain word to a certain number to unsubscribe. For this, contact your Voyado specialist or account manager.
* The default, which is standard Voyado opt out link. In this case, do nothing.
Decide where the customer can enter their mobile number:
* In My Pages.
* At the POS terminal.
* Opting in by sending a certain word to a number (for example, "Voyado in" sent to 123 123). Contact your Voyado specialist or account manager to arrange this.
In your integration, be sure to always include the `mobilePhone` attribute in the create contact JSON payload. This makes sure your contacts is always reachable by SMS.
Also include the preferences object in the create contact JSON payload, with `acceptsSms` set to "true" when the customer opts into SMS communication. This is required for them to receive SMS.
```json theme={null}
{
"firstName": "Example",
"email": "example@example.com",
"countryCode": "SE",
"birthDay": "1966-06-26",
"lang":"en",
"contactType": "ExampleContactType",
"preferences": {
"acceptsEmail": true,
"acceptsPostal": true,
"acceptsSms": true
},
"consents": [{
"id": "memberConsent",
"value": true,
"date": "2022-01-01T00:00:00+0100",
"source": "ECOM",
"comment": "Approved member terms at checkout"
}]
}
```
Now create an SMS. [Here you can see](https://help.engage.voyado.com/hc/en-gb/articles/17233924490780-Sending-SMS-messages) how that's done.
Send a test SMS to your phone. Opt out through the method you selected in step 4. Now verify that the `acceptsSms` attribute goes from "true" to "false" on the contact card.
Here's a payload example for creating a contact including mobile number and consent:
```json theme={null}
{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"mobilePhone": "+46700111222",
"preferences": {
"acceptsEmail": true,
"acceptsSms": true
}
}
```
And here's an example of the payload sent to do a contact update:
```json theme={null}
{
"mobilePhone": "+46700111222",
"preferences": {
"acceptsSms": true
}
}
```
## Unsubscribe from messages
The Customer Engagement API has endpoints to allow unsubscribing of contacts from emails and SMS messages.
### Unsubscribe from specific message
Using these two endpoints, a contact can be unsubscribed from a specific email or SMS. This is effectively the same as them unsubscribing via the unsubscribe link in an email, or through the unsubscribe link in an SMS.
```http theme={null}
POST /api/v3/contacts/{contactId}/unsubscribeEmail?messageId={messageId}
```
```http theme={null}
POST /api/v3/contacts/{contactId}/unsubscribeSms?messageId={messageId}
```
If messageId is not sent in the request, the messageId of the last message received by the contact will be used.
| Field | Type | Example value |
| - | - | - |
| contactId (mandatory) | GUID | a67b201f-d86d-4ee2-bdc7-abce0080a803 |
| messageId | GUID | f0370cc7-5428-4cc3-85c9-ad0800f0bc28 |
## The sendToPhoneNumbers endpoint
The Customer Engagement API has the following endpoint:
```http theme={null}
POST /api/v3/sms/sendToPhoneNumbers
```
This allows the client to send out SMS messages via Customer Engagement (using it as a proxy) without any connection to a specific contact. Even if the mobile number used happens to exist for a contact in Customer Engagement, no link will be made to them.
This is a service that can be used as a workaround in case the sending out of SMS can't be solved using an automation. The payload used to send out SMS looks like this:
```json theme={null}
{
"description": "Message to our members",
"invoiceReference": "Week 3",
"message": "We have exciting news for you...",
"phoneNumbers": [
"46701234567",
"443456789123"
],
"sender": "MyBrand"
}
```
The `sender` field can consist of the characters a-z, A-Z, 0-9, and "+". It can be 3-11 characters in length.
This method should only be used for transactional communication as it doesn't validate consents or accept flags for the receivers, and it doesn't record any statistics.
Any SMS sent in this way will show up on the client's SMS usage account as "Send to phone numbers" but no more details will be given.
# Suggested products
Source: https://developer.voyado.com/docs/campaigns/suggested-products
A personalized suggested product is an item that a customer might be likely to buy, based on their previous purchases, activity and other factors.
Customer Engagement's suggested products engine looks at all historical purchases and identifies how products relate to each other through the behavior of your customers. Once the AI engine learns your customers' purchase and return behavior, it can use their favorite product categories, favorite brands, viewed relevant products online, and abandoned carts to present them with suggested products.
If you want to control which products are included in the recommendation engine and which are not, you can use a separate product feed for suggested products. However, if you do this, be aware that it needs to be structured the same way as your other product feeds.
## Prerequisites
To get started with the suggested products engine, your Customer Engagement environment (tenant) needs to have these features activated:
* Product feed (only products in this feed can be recommended)
* A BI-export to the Customer Engagement BI-lake
Your Voyado PM will need to help you with this.
## Fetching suggested products
There is an API endpoint to do this. You'll need the contact's unique contact ID.
```http theme={null}
GET /api/v3/contacts/{contactId}/productrecommendations
```
The response payload will be something like this:
```json theme={null}
{
"skus":[
"1234","2345","3456","4567","5678","6789","7890","8901","9012","0123"]
}
```
If the request has not been successful, you'll get one of the following HTTP error codes:
* *400 - InvalidContactId*
* *404 - ContactNotFound*
## Promote/demote suggested items
It is possible to promote or demote items that come from your product feed. This is done with a number between -100 and 100 (referred to as the product's **weight**). A weight of -100 will demote the item to the maximum extent while 100 will promote it to the maximum extent. The "maximum extent" is determined by a setting in the back-end which control the maximum (and minimum) boost effect. So you'll need to inform your Voyado PM if you plan to use this promote/demote functionality.
The default maximum / minimum boost effect is 20% and usually this is the best value.
The field in the XML that contains the promotion weight for a product should be named "productRecommendationPromotionWeight":
```xml theme={null}
50
```
Contact your Voyado PM if you have any more questions about this.
# About partner integrations
Source: https://developer.voyado.com/docs/introduction/about-partner-integrations
The partner integrations (third party integrations) articles have been moved to a dedicated portal.
## Engage -> Customer Engagement
The name "Engage" has now become "Customer Engagement" and you'll see that change across the docs.
## Elevate -> Product Discovery
The name "Elevate" has now become "Product Discovery" and you'll also see that change across the docs.
## Abandoned checkout
Documentation added for [abandoned checkout](/docs/tracking/tracking-checkout-changes).
## Tracking script version
Latest tracking script version is now `0.1.8`.
## Search results page reverted
The search results page functionality was removed due to a possible vulnerability. A reworking is underway.
## App Push
Added article for [new app push functionality](/docs/app-push/app-push).
## Ratings & Reviews
Updated article - [see it here](/docs/ratings-and-reviews).
## NPS article
Added article covering the [v3 NPS endpoint ](/docs/contacts/nps).
## Contact Data product expanded
The value\_json (VARIANT) field has now been expanded into [explicit, typed columns](/docs/data-access/delta-shares/contact-data-product).
## Added validFrom attribute
A GET request to `/api/v3/reward-vouchers` now returns the `validFrom` attribute in the payload.
## Web activity tracking
The [Web Activity Tracking](/docs/tracking/web-activity-tracking) article was updated, clarified and separated.
## Restructuring and getting started guide
The layout of developer has been refreshed and a new [initial setup guide](/docs/introduction/getting-started#initial-setup) was added.
## Search results page added to docs
Search results in developer can be viewed on [a page which can be linked to](/search?q=result).
## Message services data product expanded
Seven new datasets were added to the [message services data product](/docs/data-access/delta-shares/message-services-product).
## Point Shop for personalized offers
The Point Shop and its API allow you to create more flexible and personalized loyalty offers. [Read about it here.](/docs/loyalty/point-shop).
## Store location data
Support for longitude and latitude added to Engage stores, including API support, validation, admin Ul, and import/export flows. This lays the foundation for future location-based services.
## Value split in product purchases
Value Split for product purchases has additional attributes: brand, main category, product category, subcategory, and size, enabling more precise automations and segmentation.
## Receipt deletion
Added the ability to delete receipts (transactions ) via contact card and API, including reason capture and audit logging for traceability. Deleting a receipt will *not* remove any points or checkpoints that were previously created based on that transaction.
## New Delta Share data products
Articles added for new data Products [Reviews](/docs/data-access/delta-shares/reviews-product) and [Targeting](/docs/data-access/delta-shares/targeting-product).
## Improvements to data access articles
Data access articles (Delta Share and BI Exports) were [expanded and restructured](/docs/data-access/overview).
## New endpoint to confirm connection
Added information about the `/livez` endpoint. [See more here](/docs/api/the-api#liveness-check).
## Promotions payload
Updated example payload for getting promotions for a contact. [See the new payload here](/docs/loyalty/promotions#get-promotions-for-contact).
## New webhooks
New webhooks added for consents, contact changes and assignment of promotions. [See it here](/docs/webhooks/webhooks).
## XML import article updated
Expanded article about XML import of promotions to cover both creation and assignment. [See it here](/docs/file-based-transfer/promotions-xml-create-assign).
## New Delta Share product: Contact Data
A new Delta Share data product was added: Contact Data product. [Read about it here](/docs/data-access/delta-shares/contact-data-product).
## New docs portal
New developer documentation portal launched for current API version and other integration information. Legacy v2 docs (for now) are hosted separately [here](https://legacy.developer.voyado.com/) and partner integrations [now have their own portal](https://partner-integrations.voyado.com/).
## New BI exports
Three new [BI exports added](/docs/data-access/bi-export) for users of Design Studio: Email, Sendout, Marketing Group.
## Transaction XML change
Transaction XML import now supports the parameter `usedRewardVouchers` as well as `usedBonusChecks` making it consistent with the API.
## Integration logging
The logging for when an article is created due to missing SKUs was lowered from "warning" to "info" in the integration log.
## Move to Help Center
Moved [Double Opt-In article to Help Center](https://help.engage.voyado.com/hc/en-gb/articles/17253837916316-Double-opt-in) and expanded it.
## Delete in Delta Share
A
## Config Hub move
All [Config Hub articles](https://help.engage.voyado.com/hc/en-gb/sections/21844508239004-Config-Hub) were moved to the Engage Help Center.
## Embedded order action added
[Embedded order action](/docs/orders/orders-api-endpoints) added for creating or updating orders.
## Non-functional requirements article
Added an article outlining the [non-functional requirements for integrations](/docs/api/non-functional-requirements "Non-functional requirements").
## New reference material
Replaced the back-end and front-end packages lists (which were static pages) with a [link to a dynamically generated list.](/docs/introduction/reference-material "Packages and licenses")
## Value-added services moved
Integration documentation for value-added-services moved to the [Engage Help Center](https://help.engage.voyado.com/hc/en-gb/sections/19126553699740-Value-added-services).
## API timeouts change
API timeout updates. See here about timeouts [when creating a contact](/docs/contacts/create-contact "Create contact") and here for the [general information and API retry policy](/docs/api/the-api#retry-policy "API retry policy").
## Testfreaks become Trustvoice
Testfreaks changes name to Trustvoice and [docs were updated to reflect this](https://help.engage.voyado.com/hc/en-gb/sections/20141680550044-Trustvoice).
## Contact endpoint timeout changes
Timeout for requests made to the create contact endpoint (API v3) was made shorter. [Read in more detail here](/docs/api/timeout-changes#create-contact-endpoint "Timeout changes").
## Interaction segmentation
Segmentation based on individual properties in interactions [is now possible](/docs/loyalty/interactions#interaction-segmentation "Interaction segmentation").
## Cow Hills becomes Orisha
Cow Hills changes name to Orisha Commerce and docs were updated to reflect this.
## Centra back-in-stock
New back-in-stock functionality for the Centra accelerator.
# API integration
Source: https://developer.voyado.com/docs/onsite/api-integration
Voyado Onsite can be connected to different platforms and databases. Customer Engagement, of course, but also other CRMs / CXPs / CDPs as well as different e-com platforms.
Voyado Onsite does not provide a generic API. When using the generic API solution, you will be setting up a server-side API for Voyado Onsite to use as a client based on the specifications below.
## Configuration
Configuring a generic API integration is done in the Onsite manager. Follow these steps:
1. Log into the Onsite manager, then go to **Configuration** and **Sites**.
2. Pick the site you want to set up the generic API integration for and either click on its name or select "Edit" in the three-dots menu.
3. You should now be in **General settings** for that site. Scroll down to **Integrations**, locate the option **Generic** and click to expand it.
4. You'll now see the configuration for the generic API integration.
![The generic API integration]()
There are three authentication methods to choose from:
* Header
* HMAC
* API Key
The configuration is very similar for all three methods. The values to fill in are:
* **Get/Lookup Contact API Endpoint URL**: The URL for your API endpoint that will be used to check if a contact already exists.
* **Create/Update Contact API Endpoint URL**: The URL for your API endpoint that will be used for creating new contacts and updating existing contacts with new data, consents, and so on.
* **Email Key**: The variable name to be used for email address in API requests.
* **Phone number Key**: The variable name to be used for mobile phone number in API requests.
* **Name Key**: The variable name to be used for customer name (full name) in API requests.
* **Personal Identity Key**: The variable name to be used for social security number (personal number in Sweden, for example) in requests to your API.
* **Ignore HTTP response codes**: Here you list the HTTP error codes to ignore, which means no error will be logged if any of the listed response codes are received. Use this feature to ensure everything still functions in the case of the API responding with error codes. If this setting is *not* active, and an unexpected response code is returned from the API, the user flow will be blocked and/or aborted.
## The data
The same JSON structure is used for sending and receiving data (via POST and GET respectively). The fields in the JSON are determined by what the campaign is configured to collect:
```json Sending and receiving Onsite data theme={null}
{
"name": "John Doe",
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"phone": "+358123458394",
"custom": "customvalue",
"customoption": ["customoptionvalue1,customoptionvalue2"],
"redeal": ["ExistingAmbassador", "NewFriend", "FriendConverted"]
}
```
In this example, `customoption` might be "pet" and `customoptionvalue1` might be "Dog". You should configure the API to ignore anything that you don't recognize and/or can't handle. This is fully configurable and maps directly into what is collected from the user.
There is one special field redeal to tag the type of contact, which is used for conversion tracking. You can choose to store this or just ignore it. The current tags in use are:
* **NewAmbassador**: A new contact who acted as an ambassador by referring friends
* **NewFriend**: A new contact from a friend referral
* **NewSignup**: A new contact without a referral
* **ExistingAmbassador**: An existing contact who acted as an ambassador
* **ExistingFriend**: An existing contact who acted as a friend
* **ConvertedAmbassador**: A contact acting as an ambassador who has converted
* **ConvertedFriend**: A contact acting as a friend who has converted
## Receiving data
The API call to fetch data is:
```http theme={null}
GET {Get/Lookup Contact API Endpoint URL}?company={company}&email={email}
```
"Get/Lookup Contact API Endpoint URL" is the value you configured in Onsite Manager above.
Expected return codes are:
* *200 OK*
* *404 Not found*
The reason this GET is called is to avoid asking the user for information that is already known, and to set the correct redeal tags. You should make it optional to use the GET call.
## Sending data
The API call used to send data is one of the following:
```http theme={null}
POST {Create/Update Contact API Endpoint URL}?company={company}
```
```http theme={null}
POST {Create/Update Contact API Endpoint URL}?company={company}&email={email}
```
```http theme={null}
POST {Create/Update Contact API Endpoint URL}?company={company}&phone={phone}
```
"Create/Update Contact API Endpoint URL" is the value you configured in Onsite Manager above.
Expected return codes here are:
* *200 OK*
* *201 Created*
# Configuring onsite messaging
Source: https://developer.voyado.com/docs/onsite/configuring-onsite
Onsite uses pop-ups, banners, and referral widgets on your website to capture leads, to segment visitors, and to activate offers It taps into real-time behavior to make your site more dynamic and personal.
Here is how you configure and work with onsite messaging in Customer Engagement.
## Prerequisites
Before you start you will need these things to be in place:
If your're using Google Tag Manager (GTM) you'll need to have it correctly installed on your website.
You'll need access to your GTM container with publish permissions.
You'll also need access to your website's dataLayer or variables for:
* Order totals and revenue
* Customer email addresses
* Currency codes
* Discount/coupon codes
A test environment is needed to validate implementation
And, optionally, the [Voyado Chrome extension](https://chromewebstore.google.com/detail/voyado/lccnimeooniolaajpndmaichmjkcopdp) installed for testing
## Implementation paths
Here we will consider three ways to implement Onsite:
1. Via Google Tag Manager in SPAs (single page applications)
2. Via Google Tag Manager in traditional multi-page applications
3. Via direct implementation
## 1- Google Tag Manager - SPA
Single Page Applications require special handling because page navigation doesn't trigger traditional page loads. For example, if your trigger uses custom pageload events, your exceptions must also use custom pageload events. Mixing event types (e.g., history change with pageview exceptions) will cause failures.
Other aspects of SPAs:
* Navigation happens without full page reloads
* Scripts must trigger on virtual page views
* Open widgets persist during navigation and must be explicitly closed
* All triggers must use consistent event types
You'll need to create four tags. Suggested names are:
1. **Voyado Onsite Cornerwidget** - Displays messaging widgets across the website
2. **Voyado Onsite Hide** - Closes any open widgets on checkout/cart pages
3. **Voyado Onsite Purchase** - Tracks conversions and displays messages on order confirmation page
4. **Voyado Onsite Login** - Identifies user and enables personalized messaging onsite
### Tag 1: Voyado Onsite Cornerwidget
**Purpose:** This loads and displays messaging widgets on landing pages and virtual page views.
**Trigger:** All pageviews EXCEPT checkout, cart, and order confirmation pages. Should also be excluded when the login script is called instead.
```javascript Voyado Onsite Cornerwidget Script theme={null}
```
The (typeof redeal !== 'function') check prevents the script from being loaded multiple times on SPAs. The script loader only runs once, but redeal('cornerwidget') can be called on each virtual page load.
**Configuration in GTM:**
* Tag Type: Custom HTML
* Trigger: Custom Event on page load
* Exceptions: Checkout page, Cart page, Order confirmation page and Login event
**Alternative tag names:**
Replace "cornerwidget" with any tag name configured in Onsite Manager. Use multiple tags with different conditions to trigger different onsite messages.
### Tag 2: Voyado Onsite Hide
**Purpose:** Close open widgets when users navigate to pages where widgets shouldn't appear (checkout, cart).
On SPAs, excluding pages from the "Voyado Onsite Cornerwidget" tag only prevents NEW widgets from loading; it doesn't close widgets that are already open. This tag explicitly closes them.
**Trigger**: Pageview on checkout and cart pages.
```javascript Voyado Onsite Hide script theme={null}
```
**Configuration in GTM:**
* Tag Type: Custom HTML
* Trigger: Custom Event on page load when Page Path contains “/checkout” or “/cart”
### Tag 3: Voyado Onsite Purchase
**Purpose**: Track conversions and optionally trigger post-purchase onsite messages.
**Trigger**: Order confirmation page load (immediately after purchase).
```javascript Voyado Onsite Purchase script theme={null}
```
| Variable Name | Type | Example value | Description |
| - | - | - | - |
| sumtotal | Data Layer Variable | "113.75" | Total amount paid by customer (string) |
| sumrevenue | Data Layer Variable | "93" | Revenue excluding tax and shipping (string) |
| currencycode | Data Layer Variable | "SEK" | ISO currency code |
| userEmail | Data Layer Variable | "[john@doe.com](mailto:john@doe.com)" | Customer email address |
| discountcode | Data Layer Variable | "aJ7q54JU" | Coupon/discount code used (can be array) |
Expected output:
```javascript theme={null}
redeal('checkout', {
total: "113.75",
revenue: "93",
currency: "SEK",
email: "john@doe.com",
coupons: ["aJ7q54JU"]
});
```
Important notes:
* total = full amount paid by customer (including tax, shipping, fees)
* revenue = amount excluding tax, shipping, and fees
* coupons should be an array even if there is only one code
* Missing or null values won't break functionality but will limit tracking and reporting
* Optional fields: name, phone (useful for prefilling onsite messages and automatically identifying visitors)
**Configuration in GTM:**
* Tag Type: Custom HTML
* Trigger: Custom Event associated with reaching the order confirmation page, for example “purchase”, or when Page Path contains “/order-confirmation” or “/thank-you”
### Tag 4: Voyado Onsite Login
**Purpose**: Identifying unidentified visitors and triggering personalized onsite messages
**When to trigger:**
* When a user actively logs in (login button click)
* On page load if user is already logged in (“soft login”)
**Trigger**: Login event OR pageview when user is authenticated
The login script should only be called *once per session*, and not on any subsequent page views after the login event occurs. On subsequent page views, calling the cornerwidget script instead is expected.
```javascript Voyado Onsite Login script theme={null}
```
**Required GTM Variables:**
* userEmail - User's email address (unhashed string)
**Optional fields**:
* phone: userPhone – User's phone number
* contactId: contactID – User's contact ID in Voyado Customer Engagement
**Configuration in GTM**:
* Tag Type: Custom HTML
* Trigger: Custom Event **user\_login** OR first page view when User State = “logged\_in”, expected to fire only once per session
**Benefits**:
* Enables automated consent updates via Reach Ability feature
* Triggers onsite messages to complete missing profile data
* Improves contact data quality
* Improves onsite scripts user identification
## 2 - Google Tag Manager (traditional)
For traditional multi-page applications (non-SPAs), the implementation is simpler because each page navigation is a full page load.
The main differences from the SPA implementation are:
* No need for the if (typeof redeal !== 'function') check
* No need for the Hide tag (widgets don't persist across page loads)
### Tag 1: Cornerwidget (Traditional Sites)
```javascript Cornerwidget (Traditional Sites) script theme={null}
```
**Trigger:** All Pages EXCEPT checkout and order confirmation.
### Tag 2: Purchase (Traditional Sites)
```javascript Purchase (Traditional Sites) script theme={null}
```
**Trigger**: Order Confirmation Page
### Tag 3: Login (Traditional Sites)
```javascript Login (Traditional Sites) script theme={null}
```
**Trigger**: Login success event OR first page view when user is authenticated
## 3 - Direct implementation
For sites without GTM, or when you want full control, you can add the script directly to your HTML.
Place this code immediately after the opening \ tag on all pages where messaging should appear:
```javascript Direct implementation script theme={null}
```
This loads the script asynchronously without blocking page rendering.
The individual tag types are implemented like this:
### Cornerwidget (landing pages)
```javascript Cornerwidget (landing pages) script theme={null}
```
With user prefill (when user data is available) you will use:
```javascript Cornerwidget (landing pages) with refill script theme={null}
```
### Checkout (order confirmation page)
```javascript Checkout (order confirmation page) script theme={null}
```
### Login (login page or when user is authenticated)
```javascript Login script theme={null}
```
### Hide function (SPAs only)
```javascript Hide function script theme={null}
// Call this when navigating to pages where widgets should be hidden
if(typeof redealHide === 'function') {
redealHide();
}
```
### Script reference
**Standard tag names**
| Tag name | When to use | Recommended data |
| - | - | - |
| cornerwidget | Landing pages, general browsing | None (optional/if available: email, name, phone, contact ID) |
| checkout | Order confirmation/thank you page | total, revenue, currency, email, coupons |
| login | After user login or when authenticated | email (optional/alternative: phone, contact ID) |
| custom | Any custom trigger defined in Onsite Manager | Varies by onsite message |
### Data field specifications
```javascript Checkout fields theme={null}
{
total: "113.75", // String: Total amount paid (including tax, shipping)
revenue: "93", // String: Revenue excluding tax and fees
currency: "SEK", // String: ISO 4217 currency code
email: "user@example.com", // String: Customer email
coupons: ["CODE123"], // Array: Discount codes used
name: "John Doe", // Optional String: Customer name
phone: "+46701234567", // Optional String: Customer phone
contactId: "b9a02dc6-52b8-4e11-b929-b37500f002f1" // Optional String: User's Contact ID in Engage
}
```
```javascript Cornerwidget fields (all optional) theme={null}
{
email: "user@example.com",
name: "John Doe",
phone: "+46701234567",
contactId: "b9a02dc6-52b8-4e11-b929-b37500f002f1"
}
```
```javascript Login fields theme={null}
{
email: "user@example.com", // Optional: User email
phone: "+46701234567", // Optional: User phone
contactId: "b9a02dc6-52b8-4e11-b929-b37500f002f1" // Optional: User's Contact ID in Engage
}
```
It is optional which of the above field(s) to pass in the script call, but at least one needs to be passed for script identification upon login to work.
### Custom trigger tags
You can define custom tags in Onsite Manager and trigger them:
```javascript Trigger custom tag theme={null}
redeal('custom-tag-name');
```
Use case: Trigger different onsite messages based on user actions:
```javascript theme={null}
```
A/B Testing: If multiple onsite messages use the same script tag and fulfil any additional targeting criteria needed to be displayed, one will be randomly selected and displayed to the user.
### Hide function
**Basic usage (hide all open widgets):**
```javascript Hide all open widgets theme={null}
redealHide();
```
### Onsite message URL links
Each onsite message in Onsite Manager generates an onsite message URL link as well as a QR code. Use these links in emails or social media to drive traffic to your website and trigger the appropriate onsite messages automatically.
With personalization variables (for email marketing):
```http theme={null}
https://yoursite.com/onsite-message-url?email=*|EMAIL|*&name=*|NAME|*
```
Replace *|EMAIL|* and *|NAME|* with the merge tag format from your email service provider.
### Domain matching
Onsite messages only trigger on domains configured in Onsite Manager.
**Use these:**
Production domain: [www.example.com](http://www.example.com)
Test subdomain: [test.example.com](http://test.example.com)
**Do not use these:**
Local development: [localhost](http://localhost) or 127.0.0.1
IP addresses: 192.168.1.100
For testing on non-production domains, add the test domain to your site configuration in Onsite Manager.
# Testing and performance
Source: https://developer.voyado.com/docs/onsite/testing-and-performance
Below you'll find diverse information to help you with testing, valiadtion, touble-shooting and measureing performance of your Onsite set-up.
## Testing and validation
Here is some useful information to help you with testing and validation.
### Using the Chrome Extension
1. Install the Voyado Chrome Extension
2. Navigate to your website
3. Wait for the page to fully load
4. Click the Voyado extension icon
5. Verify that the script is detected
The extension only detects if the script is loaded on the current page. It doesn't validate triggers or data.
### Browser Console Checks
Use this URL parameter to activate debug mode:
```http theme={null}
https://yoursite.com/?voyado-debug
```
Open your browser's developer console (F12) and check:
* The script loaded successfully: typeof redeal === 'function' — Should return: true
* The widget is open: typeof IsRedealOpen === 'function' && IsRedealOpen('cornerwidget') — Should return: true if cornerwidget is open
* There are script errors: Look for red errors in the console. Common issues:
* Failed to load resource: [https://static.redeal.se/widget/js/redeal.js](https://static.redeal.se/widget/js/redeal.js) - Script blocked by firewall/CSP
* redeal is not a function – Script not loaded or loaded after trigger call
### Clear testing session
Use this URL parameter to reset your test session:
```http theme={null}
https://yoursite.com/?voyado-clear
```
This clears local and session storage, allowing you to test onsite messages as an unidentified/new visitor.
### Testing checklist
* Script loads on all intended pages
* Only one script call loads per pageview
* Cornerwidget appears on landing pages
* Cornerwidget does NOT appear on checkout/cart pages
* Open widgets close when navigating to checkout (SPAs only)
* Checkout tag fires on order confirmation with correct data
* Login tag fires when user logs in
* Console shows no JavaScript errors
* All GTM variables return expected values
* Onsite message URL links work and trigger onsite messages
* Onsite messages only trigger on configured domains
* Test with ?voyado-clear to simulate new visitors
For implementations using Google Tag Manager, using GTM's Preview mode to ensure the tags are correctly installed and that triggers are firing appropriately with complete and correctly formatted variables is highly recommended.
### Network tab verification
In browser **DevTools > Network** tab:
1. Filter by “redeal”
2. Verify redeal.js loads successfully (Status: 200)
3. Check that POST requests to Voyado API return 200 status
4. Verify request payloads contain expected data
## Troubleshooting
Here are some tips to help with trouble-shooting of onsite messaging.
### Script not loading
**Symptoms:**
* Chrome extension shows no detection
* typeof redeal returns undefined
* No network requests to static.redeal.se
**Possible causes:**
1. Content Security Policy (CSP) blocking the script
**Solution**: Add [https://static.redeal.se](https://static.redeal.se) to your CSP script-src directive
2. Ad blocker or privacy extension
**Solution**: Disable extensions for testing or whitelist your domain
3. Firewall blocking external scripts
**Solution**: Whitelist [static.redeal.se](http://static.redeal.se) in your firewall rules
4. Incorrect GTM trigger configuration
**Solution**: Check trigger fires on page load using GTM Preview mode
5. Script tag syntax error
**Solution**: Validate HTML, ensure no extra characters in script tag
### Widget not appearing
**Symptoms:**
* Script loads but no widget visible
* Console shows no errors
**Possible causes:**
1. Domain not configured in Onsite Manager
**Solution**: Verify your domain is added to the onsite message configuration
2. Onsite message not active
**Solution**: Check onsite message status in Onsite Manager
3. Onsite message already shown to this user
**Solution**: Test with ?voyado-clear URL parameter
4. Wrong tag name
**Solution**: Verify tag name in code matches Onsite Manager configuration
5. Z-index conflict
**Solution**: Check if widget is rendering but hidden behind other elements
### Conversion not tracking
**Symptoms:**
* Checkout tag fires but conversions don't appear in reports
**Possible causes:**
1. Variables returning null or undefined
**Solution**: Use GTM Preview to verify variable values
2. Incorrect data types
**Solution**: Ensure total, revenue are strings, coupons is array
3. Currency code format
**Solution**: Use ISO 4217 codes (SEK, USD, EUR, etc.)
4. Race condition (script triggers before GTM variables populate)
**Solution**: Add a small delay or ensure dataLayer pushes before tag fires
### GTM variables not populating
**Symptoms:**
* GTM Preview shows undefined or null variable values
**Solutions:**
1. Verify dataLayer structure matches your variable configuration
2. Check that dataLayer.push() happens before page load events
3. Use “Data Layer Variable” type (not “JavaScript Variable”) in GTM
4. Test dataLayer in console: console.log(dataLayer)
### SPA issues
**Widget persists on checkout page:**
* Ensure Hide tag is implemented and triggering correctly
* Verify Hide tag trigger uses same event type as other triggers
* Check GTM Preview to confirm Hide tag fires
**Widget not appearing after navigation:**
* Confirm Cornerwidget tag triggers on virtual pageviews
* Verify history change events are captured in GTM
* Check that custom events fire consistently
**Script loaded multiple times:**
* Ensure if (typeof redeal !== 'function') wrapper is present
* Check GTM Preview for duplicate tag fires
### Console error messages
**Common errors and solutions:**
| Error | Cause | Solution |
| - | - | - |
| Failed to load resource: [https://static.redeal.se/…](https://static.redeal.se/…) | Script blocked | Check CSP, firewall, ad blockers |
| redeal is not a function | Script not loaded before call | Ensure script loader runs first |
| IsRedealOpen is not defined | Script not fully initialized | Add conditional check: typeof IsRedealOpen === 'function' |
| Cannot read property 'email' of undefined | Missing data object | Verify GTM variables are defined |
## Performance & security
Performance and security can be improved by following these tips.
### Content Security Policy (CSP)
If your site uses CSP headers, add these directives:
```yaml theme={null}
Content-Security‐Policy:
script-src 'self' https://static.redeal.se;
connect-src 'self' https://*.redeal.se;
```
Without these directives, the script will be blocked by the browser.
### Script loading strategy
The Voyado script uses async loading to minimise performance impact:
```javascript theme={null}
a.async=1; // Script loads asynchronously
```
**Benefits:**
* Non-blocking: Page rendering continues while script loads
* Fast: Script hosted on CDN with global distribution
* Cached: Browser caches script for subsequent visits
**Performance Impact:**
* Initial load: \~15-25 KB (minified and gzipped)
* Subsequent loads: 0 KB (cached)
* Page load delay: \<50 ms on average
### Best practices
**Do:**
* Load script on all relevant pages (cornerwidget is reusable)
* Use async loading (included in implementation)
* Implement proper CSP directives
* Test on staging before production
* Monitor console for errors after deployment
**Don't:**
* Block page rendering waiting for script
* Load script multiple times on same page (use conditional checks for SPAs)
* Hardcode customer data in JavaScript (security risk)
* Skip testing on different browsers
* Forget to update CSP when implementing
### Data privacy
**Email handling:**
* Emails are transmitted over HTTPS
* Never expose emails in URLs (use POST data)
* Comply with GDPR/privacy regulations in your region
* Inform users about data collection in your privacy policy
**Session data:**
* Script uses local storage and session storage
* Data is stored client-side only
* Use ?voyado-clear to manually clear stored data
### Browser compatibility
The script is compatible with:
* Chrome (latest)
* Firefox (latest)
* Safari (latest)
* Edge (latest)
* Mobile browsers (iOS Safari, Chrome Mobile)
Not supported:
* Internet Explorer 11 and earlier
## Additional resources
Onsite Manager: Configure onsite messages, sites/domains and view analytics
Chrome Extension: [Download here](https://chromewebstore.google.com/detail/voyado/lccnimeooniolaajpndmaichmjkcopdp)
GTM Documentation: [Google Tag Manager Help](https://support.google.com/tagmanager/answer/6103696)
Voyado Support: Contact your Voyado representative for technical assistance
If you have questions or encounter issues not covered in this guide, reach out to Voyado support or your Voyado representative.
# Tracking cart changes
Source: https://developer.voyado.com/docs/tracking/tracking-cart-changes
How to send shopping cart updates to Customer Engagement with cart() and emptyCart(), and what abandoned cart automations require.
Tracking cart changes is what makes abandoned cart automations possible. For Customer Engagement to trigger one, it needs to know **every state of every cart** and, eventually, **which contact the cart belongs to**.
You can send cart data either with the [tracking script](/docs/tracking/tracking-script) or with the tracking API.
## How it works
1. Your site submits every cart change, via the tracking script or the tracking API.
2. A cart that still contains products and hasn't been touched for 30 minutes is treated as abandoned. If it is connected to a contact, it is sent to Customer Engagement. All other carts are filtered out.
3. Customer Engagement enriches the products from the product feed and triggers the automation matching the cart's locale.
## What an abandoned cart automation requires
An abandoned cart automation triggers only when all of these are true:
* The cart's `locale` matches a product feed in Customer Engagement, and an active automation is set to that language.
* At least one SKU matches a product in that feed (usually via `g:id`). Products that don't match are left out of the email; if **no** SKUs match, the automation doesn't trigger at all.
* No product in the cart has been purchased since the cart was marked abandoned - that is, no transaction has reached Customer Engagement. This can be overruled in the trigger configuration.
Call `cart()` every time the cart changes: an item added, an item removed, or a quantity updated. Call it whether or not the visitor has been identified.
```javascript Adding two products to the cart theme={null}
va("cart", {
"cartRef": "354354",
"contactId": "afa7625d-2e97-4667-b4c1-ad3b01194bee",
"cartUrl": "https://www.store.se/cart?id=354354",
"locale": "sv-SE",
"items": [
{
"itemId": "456436",
"quantity": 2
},
{
"itemId": "456437",
"quantity": 2
}
]
});
```
Your reference for this cart. Must be unique per cart and must never change for the life of that cart.
The locale of the site the cart belongs to, as an IETF language tag such as `sv-SE`. Only locales with a product feed assigned in Customer Engagement can trigger an abandoned cart automation.
The full current contents of the cart.
The product identifier, matched against SKU in Customer Engagement.
The number of that item in the cart.
A link back to this cart on your site, for use in the abandoned cart email.
The Customer Engagement contact ID. If omitted, the `_vaI` cookie is used as a fallback.
Call `emptyCart()` when the cart has been emptied, either by the visitor or by a completed checkout. It is equivalent to calling `cart()` with no items.
Calling it after every successful checkout is important — otherwise the cart stays populated in Customer Engagement and may trigger an abandoned cart email to someone who has already bought.
```javascript theme={null}
va("emptyCart", {
"cartRef": "354354",
"contactId": "afa7625d-2e97-4667-b4c1-ad3b01194bee"
});
```
The same cart reference used for the cart's other events. Empty carts also need one.
The Customer Engagement contact ID. Adding this is highly recommended, but if omitted, the `_vaI` cookie will be used as a fallback.
## Using the tracking API
You can submit cart changes directly via the API instead of implementing the tracking script.
The API always requires a `contactId`, so it can only track **identified** visitors. Anonymous carts can only be tracked with the script. You are also responsible for identifying visitors who arrive from Customer Engagement email links yourself, by reading the `vtid` query parameter and passing it as `contactId`.
If you use abandoned browse as well as abandoned cart, you must also include a `sessionId` in every payload. See [sessions and sessionId](/docs/tracking/tracking-product-views#sessions-and-sessionid).
You can test the calls from your OpenAPI (Swagger) page:
```http theme={null}
[tenantname].voyado.com/api/v3/ui/index#/tracking
```
Send a cart event **only** when the cart actually changes. Firing events at other times — on page load, on navigation — pollutes your data in Customer Engagement.
* **Track anonymous carts too.** A cart belonging to an anonymous visitor is still linked to their contact once they are identified.
* **Every change means one event.** Customer Engagement always works from the cart's latest state, so the data you send must match what the site currently displays. Cart updates can happen in a product page, a popup, a mini-cart or the checkout — all of them need to fire an event.
* **`cartRef` must be unique and stable.** Never share a `cartRef` between carts or visitors, and never change it for an existing cart. Getting this wrong on remove-product and empty-cart events is a common bug.
* **Always send a `cartRef`, even for empty carts.**
* **`locale` must match a product feed.** Customer Engagement needs a feed for that locale to enrich products with article data, and an active automation using that locale.
* **Anything not emptied risks being marked abandoned.** If a visitor leaves or buys without your site calling `emptyCart()`, an active abandoned cart automation will trigger on that cart.
The reference of the cart this checkout belongs to. Must be the same `cartRef` you use in [cart events](/docs/tracking/tracking-cart-changes) for that cart.
Your reference for this checkout. Must be unique per checkout and must never change for the life of that checkout. Maximum 255 characters. `checkoutReference` is accepted as an alias in the tracking script.
The locale of the site the checkout belongs to, as an IETF language tag such as `sv-SE`.
The full current contents of the checkout.
A link back to the cart on your site.
A link back to this checkout on your site.
The Customer Engagement contact ID. Must be a valid GUID or short GUID, with a maximum of 36 characters. If omitted, the `_vaI` cookie is used as a fallback.
The coupon or discount code applied to the checkout. Maximum 100 characters.
The total amount of the checkout.
The total discount applied to the checkout.
The currency of all amounts, as a three-letter ISO 4217 code such as `SEK`. If provided, it must consist of exactly 3 letters.
Whether the visitor has selected a shipping method (`true` or `false`).
Whether the visitor has selected a payment method (`true` or `false`).
### Item fields
The product identifier, matched against SKU in Customer Engagement. Maximum 255 characters.
The number of that item in the checkout. Must be an integer of 1 or greater.
The position of the item in the checkout. Must be 0 or greater. If omitted, the item's position in the `items` array is used.
The unit price of the item.
The price of the item multiplied by its quantity, before discount.
The total discount applied to the item.
The total price of the item after discount.
The item's main category. Use `category2` to `category5` for deeper levels of the category hierarchy. Maximum 100 characters per category field.
The item's brand.
## Using the tracking API
You can submit checkout changes directly via the API instead of implementing the tracking script.
The API always requires a `contactId`, so it can only track **identified** visitors. Anonymous checkouts can only be tracked with the script. You are also responsible for identifying visitors who arrive from Customer Engagement email links yourself, by reading the `vtid` query parameter and passing it as `contactId`.
You must also include a `sessionId` in every payload. It is required to identify the winning abandoned signal when a session contains checkout, cart and product view events. Use the same `sessionId` across all three event types. See [sessions and sessionId](/docs/tracking/tracking-product-views#sessions-and-sessionid).
Send checkout events to the `tracking/checkouts` endpoint.
You can test the calls from your OpenAPI (Swagger) page:
```http theme={null}
[tenantname].voyado.com/api/v3/ui/index#/tracking
```
Send a checkout event **only** when the checkout actually changes. Firing events at other times, such as on page load or navigation, pollutes your data in Customer Engagement.
* **Every change means one event.** Customer Engagement always works from the latest state, so the data you send must match what the checkout currently displays. Send the full contents every time, not just what changed.
* **`checkoutRef` must be unique and stable.** Never share a `checkoutRef` between checkouts or visitors, and never change it for an existing checkout.
* **Use the same `cartRef` as your cart events.** This is what links the checkout to the cart.
* **Always send `locale`, `checkoutRef`, `cartRef` and `items`.** The script does not send the event if any of them is missing, and logs an error to the browser console.
* **Send valid items.** Every item needs an `itemId` (255 characters or fewer) and an integer `quantity` of 1 or greater.
* **Use consistent currency and amounts.** Send all amounts in the same currency, and set `currencyCode` to a 3-letter ISO 4217 code.
* **Use one `sessionId` per session across checkout, cart and product view events.** This ensures a single Abandoned Checkout signal per abandoned session. With the tracking script this is handled for you; with the API you must send it yourself.
* **Call `emptyCart()` after a completed purchase.** A checkout event does not clear the cart. If a visitor buys without your site calling `emptyCart()`, an active abandoned automation may still trigger for someone who has already bought. See [tracking cart changes](/docs/tracking/tracking-cart-changes).
1. Your site submits product views, which belong to a session.
2. A session with no activity for 30 minutes is treated as abandoned. If it contains **no cart event** and the product views are connected to a contact, it is sent to Customer Engagement. All other sessions are filtered out. A session can only be sent to Customer Engagement once.
3. The product views are enriched with data from the product feed.
4. Customer Engagement triggers the automation matching the trigger configuration. Email activities in that automation can include dynamic product data from the feed.
From the recency, frequency and pattern of product views over the last 90 days, Customer Engagement calculates up to **25 products** each contact is most likely interested in, based purely on their onsite behavior.
The list is refreshed by a scheduled job and enriched from the article register — note that products of interest are connected to the **article register**, not the product feed. It can then be used in segmentation and as part of a scheduled selection in an automation.
If a contact has products of interest, that data feeds the calculation of their personal recommendations. Customer Engagement combines their onsite behavior with their full purchase and return history to produce a personalized set of recommendations for use in emails.
## What an abandoned browse automation requires
* The `locale` must match a product feed in Customer Engagement. Events without a matching feed are filtered out.
* At least one SKU must match a product in that feed (usually via `g:id`). Products that don't match are left out of the email; if **no** SKUs match, the automation doesn't trigger at all.
* The session must contain no cart events. See [sessions and sessionId](#sessions-and-sessionid) below.
## Sessions and sessionId
Every session has a unique `sessionId`. Customer Engagement uses it to make sure abandoned cart and abandoned browse never both trigger for the same session:
* If `cart` and `productView` events share a `sessionId`, only the **abandoned cart** automation triggers.
* **Abandoned browse** triggers only when no cart event was recorded for that `sessionId`.
The tracking script adds `sessionId` automatically. When you use the tracking API, you must add it to every payload yourself.
The `sessionId` is not strictly mandatory for cart events, but it is required if you use abandoned browse and abandoned cart together. Not using it can result in both automations firing for the same session.
## Using the tracking script
Call `productview()` every time a product is shown to the visitor, whether or not they have been identified. It sends an HTTP POST to the Collect endpoint.
```javascript theme={null}
va("productview", {
"categoryName": "Women / Armour / Greaves",
"itemId": "123XYZ",
"contactId": "afa7625d-2e97-4667-b4c1-ad3b01194bbb",
"locale": "sv-SE"
});
```
The product's category, for example `Men / Sweaters / Cardigan`.
The product identifier, matched against SKU in Customer Engagement.
The locale of the site, as an IETF language tag such as `sv-SE`. Must match a product feed locale in Customer Engagement, otherwise abandoned browse cannot trigger.
The Customer Engagement contact ID. If omitted, the `_vaI` cookie is used as a fallback.
## Using the tracking API
You can submit product views directly via the API instead of implementing the tracking script. Be aware that a lot of what the script handles out of the box then becomes your responsibility:
* **Identification.** The API requires a `contactId`, so only identified product views can be registered. You must identify visitors arriving from Customer Engagement email links yourself, by reading the `vtid` query parameter and passing it as `contactId`.
* **Sessions.** You must include a `sessionId` in every payload. Abandoned browse will not work without it.
The link from the Customer Engagement email carries `vtid`, so the script identifies the visitor before the product view is sent.
Populate the event like this:
* `categoryName` — the current product category, e.g. `Computer accessories > Printers > Toners`
* `itemId` — the current product SKU, e.g. `549852`
* `locale` — the site's current language/market, e.g. `sv-SE`
* `contactId` — the visitor's Customer Engagement contact ID (`vtid` is used as a fallback)
Send the event exactly as above, with one difference:
* Do **not** populate `contactId`
The view is recorded against the browser's client ID and connected to a contact later, if and when the visitor is identified.
A product display page covering several sizes, colours or variants needs a decision about what counts as a view.
* **Preferred:** send one `productview()` when a specific variant is selected, rather than one per size.
* If you want to record the view regardless of variant, send a single representative SKU from the page.
* As a last resort, send all variants — but be aware this risks abandoned browse emails filled with many variants of the same product.
![The _vaI cookie]()
![Tracking script used]()
## Verify product views
1. Go to your e-com site.
2. Open the developer console, go to **Network** and select the **Fetch/XHR** tab.
3. Visit any product on the site.
4. You should see a call to the Collect endpoint.
5. In the payload, `te` should be your tenant/account name.
6. `t` (type) should be `productview`.
7. If you are identified, check that `ci` holds the same ID as the `_vaI` cookie — and nothing else.
The `locale` in a product view payload does not have to match the locale in your cart payloads, and it is not used to identify anything. It does, however, need to match a product feed for abandoned browse to trigger.
![Finding the payload]()
## Verify cart changes
1. Go to your e-com site.
2. Open the developer console, go to **Network** and select the **Fetch/XHR** tab.
3. Place an item in the cart.
4. You should see a call to the Collect endpoint.
5. In the payload, `t` (type) should be `cart`. Check the `items[]` array against what's actually in your cart.
6. If possible, complete the purchase.
7. A new Collect event should fire with an empty cart, confirming the purchase was registered.
![Verify tracking cart changes 1]()
![Verify tracking cart changes 2]()
## Checklist: script and identification
The script must load on landing pages, category pages and any other non-product page. If an email link lands on a page without the script, identification fails.
Confirm that simply loading or navigating between pages sends no events.
Events should be sent when no `_vaI` cookie exists. Customer Engagement connects anonymous events to a contact once they are identified.
Arrive via an email link and confirm events are sent and `_vaI` is set correctly. A visitor can be identified without being logged in.
Log in and confirm that `setContactId()` sets `_vaI` correctly and that events are sent with the identification in place.
`_vaI` should be set whether or not the URL has a trailing slash.
* With: `www.site.se/?vtid=LTq-P1eRKU2s8CWc5KPe5w`
* Without: `www.site.se?vtid=LTq-P1eRKU2s8CWc5KPe5w`
Then navigate further into the site and confirm `_vaI` is not cleared.
`_vaI` should update when a different `vtid` is used. Set `vtid` to `a4fa7a46-23b0-4523-b09c-5462053e7627`, then change it to `3fbe3a2d-9157-4d29-acf0-259ce4a3dee7` and confirm the cookie follows.
Abandoned browse will not trigger without it. The script adds it automatically; if you use the tracking API, you must add it yourself.
Running the production script in staging, or the staging script in production, means no tracking at all.
## Checklist: cart tracking
The cart's locale must match both a product feed in Customer Engagement and the language version of the site, if you run a multimarket site.
Try every way of changing the cart: add an item, remove an item, change quantity, empty it. Does the quantity update when the same item is added a second time? What happens when you remove the last item? Carts can usually be updated from the product page and a popup as well — and sites built as SPAs tend to behave inconsistently.
Checkout usually behaves differently from the rest of the site. Is there a difference between setting quantity to zero and removing the item? What happens when all items are removed? Can you add new items from checkout? Does any of it differ with and without `vtid`?
Update the cart on both the checkout page and elsewhere, moving back and forth. Confirm no incorrect or duplicate events are sent.
Without this, the cart stays populated in Customer Engagement and can trigger an abandoned cart email to someone who already bought.
## Checklist: product views and products of interest
To detect whether a purchase followed a product view, Customer Engagement matches the `itemId` from the view against the SKU in the article register on the receipt.
A product page should fire one `productview` per unique `itemId`/SKU. Several events on one page are fine only if they are for different SKUs.
Product pages can be reached from the landing page, checkout, another product page, the menu or the cart. Test each route. Sites built as SPAs don't do full page loads, which frequently causes events to be missed.
## Common implementation errors
* **A cart event isn't sent for every update.** Every change — add, remove, quantity change, empty — must generate a cart event to the Collect endpoint. These changes happen in different contexts (product page, cart popup or sidebar, checkout) that often behave differently.
* **The `cartRef` changes for the same cart.** `cartRef` must be unique per cart and identical across all of that cart's events. Invalid or changed `cartRef` values on remove-product and empty-cart events are a frequent cause of missing abandoned cart emails.
* **Duplicate cart or product view events.** One cart update should produce exactly one cart event, and actions that aren't cart updates (such as page loads) should produce none. A product page should produce no more than one `productview` per unique SKU.
## Common identification errors
* **The `_vaI` cookie is cleared after being set by `vtid`.** A visitor identified by an email link is identified without being signed in. Calling `setContactId()` with an empty or null value in that state wipes the identification. Only call it when your site has actually identified someone.
* **No cart or product view events before checkout or sign-in.** Don't limit events to the checkout page, or to signed-in visitors. Anonymous events are connected retroactively.
* **`_vaI` isn't set when the email link ends in a slash.** Some websites strip trailing slashes without preserving the query string, so `vtid` is lost. For example `www.mysite.com/myproduct/?vtid=uaz2QuT9NEez_eAsr8hEeQ` becomes `www.mysite.com/myproduct`.
\_change\_type value for Delta Share named “delete” [was added](/docs/data-access/delta-share). A delete record will now be generated for any row where the import\_date\_time is older than 30 days. This serves as a technical log entry indicating that the row will be removed.