Headless loyalty API
Tip
Go here for a more detailed description of the API.
This API has been created for headless merchants who wish to use the loyalty functionality in Voyado Engage. Using this API, you can seamlessly synchronize active promotions and vouchers between Shopify and Voyado Engage, as well as display a customer's loyalty data in your own front-end.
Authorization method
The authorization method Bearer is used as part of a HTTPS header.
Important
The key is generated in the app settings section called “Headless API keys“.
Request
This is the request URL you will use:
https://live.voyado.eastsideapps.io/api/v1/contact-details
With these request headers:
Authorization: Bearer {YOUR_AUTH_KEY}
Content-Type: application/json
Accept: application/json
And one of these request body parameters:
shopify_customer_id: This is required if none of the other parameters (voyado_contact_id, email) are present.
voyado_contact_id: This is required if none of the other parameters (shopify_customer_id, email) are present.
email: This is required if none of the other parameters (shopify_customer_id, voyado_contact_id) are present.
This is a body payload example:
{
"shopify_customer_id" : "7253944860994"
}Responses
This is a response payload example:
{
"contact": {
"shopifyCustomerId": 7253944860994,
"voyadoContactId": "d07f7b26-f6e8-4bac-bc16-b0a4008c1ba6",
"attributes": {
"firstName": "John",
"lastName": "Doe",
"street": "Street 1",
"careOf": null,
"city": "Stockholm",
"zipCode": "123 45",
"countryCode": "SE",
"country": "Sweden",
"email": "john.doe@voyado.com",
"mobilePhone": "+46123456789",
"age": null,
"birthDay": null,
"externalId": "7253944860994",
"socialSecurityNumber": null,
"gender": null,
"rfm": 79,
"discoveryKey": null,
"memberNumber": "326",
"language": "en",
"lang": null,
"annualBirthDay": null,
"isRegistrationCompleted": false,
"registrationDate": "2023-10-23T10:30:07+02:00",
"bonusPoints": 208,
"secrecyMarked": false,
"currentStore": {
"id": "c26c0876-434e-42d3-b87c-b08100e15a8c",
"name": "test",
"externalId": "43"
}
},
"bonusPoints": 208,
"memberLevel": {
"expires": "2024-10-23T00:00:00+02:00",
"levelName": "Silver",
"remainingToUpgrade": 139,
"basedOnRewardPoints": 1708,
"levelId": "silver"
},
"activeLoyaltyVouchers": [
{
"expiresOn": "2023-12-31T23:59:59+01:00",
"id": "6f0e82ce-b985-488b-a603-132607267adb",
"checkNumber": "0000000001731",
"name": "Voucher",
"value": {
"currency": "EUR",
"amount": 20
},
"localValues": [
{
"currency": "SEK",
"amount": 204.4
},
{
"currency": "GBP",
"amount": 22.68
}
],
"bonusPoints": 500,
"redeemed": false,
"redeemedOn": null
}
],
"syncFailedActiveLoyaltyVouchers": [],
"activePromotions": [
{
"id": "f0f58414-0b56-4b8a-9d83-b0a400af3145",
"promotionId": "f30a8f6e-0cfd-458d-bea6-b0a400aee0d3",
"externalId": null,
"type": "Multichannel",
"name": "20% off next order (Online discount)",
"expiresOn": null,
"heading": null,
"description": null,
"redeemed": false,
"redeemedOn": null,
"imageUrl": null,
"link": null,
"redemptionChannels": [
{
"type": "POS",
"valueType": "PERCENT",
"value": "20",
"instruction": null
},
{
"type": "ECOM",
"valueType": "EXTERNALOFFER",
"value": "RSX78CVHCX6X",
"instruction": null
}
]
}
],
"syncFailedActivePromotions": []
}
}This is an example response for a failed sync of active promotions (in this case the promotion is not found as a discount in Shopify):
"syncFailedActivePromotions": [
{
"id": "323a23f6-84cd-4d23-b733-b0ac0087a168",
"promotionId": "113da8d2-3ffc-44d9-bf9f-b0ac00877ea1",
"externalId": null,
"type": "Multichannel",
"name": "Discount test",
"expiresOn": null,
"heading": null,
"description": null,
"redeemed": false,
"redeemedOn": null,
"imageUrl": null,
"link": null,
"redemptionChannels": [
{
"type": "ECOM",
"valueType": "EXTERNALOFFER",
"value": "143513531",
"instruction": null
}
],
"error": "DiscountCodeNotFoundInShopify",
"errorCode": 409,
"errorDescription": "Voyado contact ID: d07f7b26-f6e8-4bac-bc16-b0a4008c1ba6. Discount code '143513531' is not found in Shopify."
}
]This is an example of a failed sync of active reward vouchers (in this case currency conversion is missing):
"syncFailedActiveLoyaltyVouchers": [
{
"expiresOn": "2023-12-31T23:59:59+01:00",
"id": "6f0e82ce-b985-488b-a603-132607267adb",
"checkNumber": "0000000001731",
"name": "Voucher",
"value": {
"currency": "EUR",
"amount": 20
},
"localValues": [
{
"currency": "SEK",
"amount": 204.4
}
],
"bonusPoints": 500,
"redeemed": false,
"redeemedOn": null,
"error": "CurrencyMissing",
"errorCode": 409,
"errorDescription": "Missing currency 'GBP' for voucher '0000000001731'. Contact ID: d07f7b26-f6e8-4bac-bc16-b0a4008c1ba6."
}
]