Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.voyado.com/llms.txt

Use this file to discover all available pages before exploring further.

The Engage Point Shop allows you to embed point shop offers directly into your web shop, native apps, or POS systems. You can fetch available point shop offers for a member, allow them to purchase an offer using their points, and track purchases. The API ensures your customer experience stays in sync with the Engage backend, handling redemptions and point deductions seamlessly.

​
How it works

When you create a point shop offer in Engage, two entities are generated:
This represents the shop-facing item, and includes:
  • Point cost
  • Availability window
  • Presentation data
This is the actual reward the member receives after purchase (discount, ticket, pre-sale access). This includes:
  • Presentation data
Presentation data (including title, description, image, link) is stored both for point shop item and for multichannel promotions.
From an integration perspective you will:
  1. Fetch and display available point shop items
  2. Let the member purchase a point shop offer
  3. Retrieve and redeem the reward via Multichannel APIs
The relevant API endpoints are presented here.

​
1. Get point shop items

This endpoint fetches all point shop items that a specific member can purchase. 
GET /api/v3/point-shop-items?contactId=[contactId]
​
contactId
GUID
required
Unique identifier of the contact.
[
  {
    "id": "GUID",
    "name": "string",
    "cost": 0,
    "pointDefinitionId": 0,
    "promotionId": "GUID",
    "validFrom": "2026-03-20T13:53:08.003Z",
    "validTo": "2026-03-20T13:53:08.003Z",
    "presentation": {
      "title": "string",
      "description": "string",
      "imageUrl": "string",
      "link": "string"
    }
  }
]
​
cost
int
The points required for this item.
​
promotionId
GUID
The ID of the reward.
Items are filtered based on:
  • Member eligibility
  • Point cost
  • Active time window (validFrom, validTo)
400 Bad Request is received if contactId is empty or not a valid GUID.

​
2. Purchase point shop item

Use this endpoint to purchase a point shop item for a specific contact and assign the promotion purchased to them. 
POST /api/v3/point-shop-items/purchase
The following payload is sent in the body:
Purchase item payload structure
{
  "pointShopItemPurchaseId": "00000000-0000-0000-0000-000000000000",
  "pointShopItemId": "00000000-0000-0000-0000-000000000000",
  "contactId": "00000000-0000-0000-0000-000000000000"
}
​
contactId
GUID
required
Standard identifier for the contact.
​
pointShopItemPurchaseId
GUID
required
This, the unique ID for this purchase, is a value that you have to generate in your system for each purchase attempt. This endpoint is therefore idempotent, and this is enforced based on the combination of pointShopItemPurchaseId and contactId. See below for more.
​
pointShopItemId
GUID
required
This is the same value as the id returned in the Get point shop items endpoint above.

​
Idempotency

Idempotency here is based on the combination of pointShopItemPurchaseId and contactId. In practice, if a request is retried using the same values of these two attributes, the API will just return the existing purchase instead of creating a new one. This ensures that:
  • A purchase ID cannot be reused across different contacts
  • No duplicate point deductions will occur
  • Retries are safe in case of network issues

​
Handling the request

When a POST has been made to this endpoint, the systems first validates that pointShopItemPurchaseId and contactId belong together, preventing duplicate purchases and cross-user reuse of purchase IDs. If validated, then:
  • The purchase operation identified by pointShopItemPurchaseId is created or, if it already exists, reused
  • Points are deducted from the contact
  • The linked promotion is assigned to the contact
In the case of a request to the endpoint being repeated:
ScenarioResult
Same purchaseId + same contactId✅ Returns existing purchase (idempotent)
Same purchaseId + new contactId❌ Rejected (invalid request)
New purchaseId + same contactId✅ New purchase created
{
  "id": "00000000-0000-0000-0000-000000000000",
  "pointShopItemId": "00000000-0000-0000-0000-000000000000",
  "pointAccountId": "00000000-0000-0000-0000-000000000000",
  "pointTransactionId": "00000000-0000-0000-0000-000000000000",
  "promotionAssignmentId": "00000000-0000-0000-0000-000000000000",
  "pointShopItemCost": 0,
  "status": "Processing",
  "purchasedOn": "2026-04-14T13:23:28.458Z"
}
See response errors:
The generic PromotionAssignmentError (HTTP 400) is split into specific error codes: - PromotionAssignmentContactNotFound (400) — the contact doesn’t exist  - PromotionAssignmentPromotionNotFound (400) — the linked promotion was removed  - PromotionAssignmentPromotionExpired (400) — the linked promotion has ended  - PromotionAssignmentError (400 → 500) — internal server error, safe to retry
This can have one of the following error codes:
  • Item does not exist
This can have one of the following error codes:
  • PointShopItemPurchaseProcessingTimedOut
  • PointShopItemPurchaseFailed
{
  "message": "string",
  "validationErrors": [
    {
      "validationErrorCode": "string",
      "field": "string",
      "errorDescription": "string"
    }
  ]
}
  • Unknown error

​
Integration guidance

Clients should:
  1. Generate a new pointShopItemPurchaseId for each new purchase
  2. Reuse the same ID only when retrying the same request
  3. Never reuse a purchase ID across different users (different contactId values)

​
3. Get point shop item purchases

Use this endpoint to fetch all purchases made by a specific contact. 
GET /api/v3/point-shop-item-purchases?contactId=[contactId]
​
contactId
GUID
required
Standard identifier for the contact.
The response payload looks like this:
Point shop item purchases response
[
  {
    "pointShopItemPurchaseId": "GUID",
    "pointShopItemId": "GUID",
    "promotionAssignmentId": "GUID",
    "pointShopItemCost": 0,
    "status": "Processing",
    "purchasedOn": "2026-03-20T13:41:01.840Z"
  }
]

​
Uses for this endpoint

This data from this endpoint is useful for:
  • Seeing the full purchase history
  • Order tracking
  • UI confirmation flows
  • Understand the purchase state withstatus (for example Processing)
See response errors:
  • InvalidContact
  • No purchases found or invalid reference

​
Purchase flow

A point shop item purchase flow looks like this:
  1. Call GET /point-shop-items
  2. Display available offers
  3. User selects an item
  4. Call POST /point-shop-items/purchase (with pointShopItemPurchaseId)
  5. Retry safely if needed using the same purchase ID
  6. Optionally track via GET /point-shop-item-purchases
  7. Fetch reward via the multichannel promotion API

​
Multichannel promotion

While the point shop API handle this:
  • Listing items
  • Purchasing items
The actual reward purchased is handled by the multichannel promotion endpoints. You must integrate with those endpoints in order to:
  • Display reward details (title, description, barcode, expiry)
  • Allow redemption (in-store or online)
See the multichannel promotion API documentation for how to retrieve, present, and validate assigned offers.
https://mintcdn.com/voyado/Ns4bBcK3LNctK_Un/icons/developer-link.png?fit=max&auto=format&n=Ns4bBcK3LNctK_Un&q=85&s=fbd08f956358ab12f664a7158e1a1399

Learn about the multichannel promotion API