Skip to main content
The current version of the Customer Engagement API has been upgraded to 3 to introduce new functionality, to make it easier to expand the API in the future, and to improve consistency. Here is a summary of the changes going from v2 to v3:
  • Consolidated and renamed endpoints for a better experience and consistency
  • Moved some endpoints to the part of the API where they make more sense
  • Added the use of PATCH (update resource) and PUT (replace resource) methods
  • Corrected some field names that reflected legacy usage
  • Shifted more from header parameters to query parameters
  • New version of /orders endpoint with expanded functionality for storing, updating and segmenting on order data
Existing usage of API v2 and v1 is not affected by these changes, as those versions now enter Active LTS (Long-Term Support). The v2 and v1 endpoints continue to be supported and may be used as before until further notice. Any errors found in these versions will be corrected as needed. Client developers are encouraged to use the current version of the API, version 3, for all new development and to upgrade existing functions, when possible, to make better use of all new functionality when it is released. New endpoints and breaking changes are only added in new API versions. Non-breaking changes to existing endpoints may still be released within an existing version. See the API versioning model for details on how new API versions are released, how older versions are deprecated, and exactly how breaking and non-breaking changes are defined.

The API versioning model

Below are the detailed changes moving from v2 to v3.

Orders

The new orders endpoints /api/v3/orders offer functionality to trigger an automation to send order communication (email or SMS) and also expanded functionality to store and update the order data which makes it possible to segment on order data. The v2 endpoint /api/v2/orders only supports triggering an automation and will therefore be deprecated. However it may still be used as long as the v2 status is Active LTS. The integration pattern for orders has also changed to asynchronous in v3 meaning that the data to be acted on when an order’s state changes can be stored independently from the order data. New endpoint /api/v3/orders
  • GET fetches stored orders for a contact
  • POST registers a new order.
New endpoint /api/v3/orders/{orderId}
  • GET retrieves a single order
  • PUT updates existing order
  • DELETE deletes an order permanently
New endpoint /api/v3/orders/{orderId}/action
  • POST is used to trigger an automation and send order email or SMS
New endpoint /api/v3/orders/jobs/{jobId}
  • GET is used to check the status of an order registration or update

Using the new /orders endpoint

How to trigger order communication

Contacts

Changes to the contacts endpoints were made for a better experience and consistency. Some endpoints moved to other groups, and some terms changed for clarity. The four endpoints /api/v2/contacts/{contactId}/bonuschecks have changed to /api/v3/reward-vouchers. Some parameters and payload values have also changed, see “Reward vouchers (bonus checks)” below. The following endpoints are removed in v3:
  • /api/v2/contacts/{contactType}/bykey/{keyValue}: Use /api/v3/contacts/{contactType}/bykey
  • /api/v2/contacts/count: (can still be used in v2)
  • /api/v2/contacts/{contactType}/count: (can still be used in v2)
  • /api/v2/contacts/{contactId}/bonuspointtransactions: replaced by a two-step process. Get the point account ID from /api/v3/point-accounts, then use it in /api/v3/point-transactions to fetch the point transactions.
Header parameters when creating a contact with /api/v3/contacts are now query parameters. The same applies when deleting a contact. Method for updating contact at /api/v3/contacts/{contactId} changed from POST to PATCH. /api/v2/contacts/{contactId}/transactions is now /api/v3/transactionsand:
  • The contact ID is now sent in the query string
  • More data is returned in the response in the v3 version.

Contact overview

Changes were made to the payload for /api/v3/contactoverview:
  • The property bonusPoints is renamed points
  • checkNumber is renamed to voucherNumber
  • In v3, a contact’s total points (bonus points) are no longer returned from /api/v3/contactoverview. Instead use a separate GET request to the existing (but slightly changed) endpoint /api/v3/point-accounts

Promote to member

The v2 endpoint /api/v2/contacts/{contactId}/promoteToMember is removed in v3. In v2 this was used to:
  • Update contact type to “member”
  • Set isApproved to true (triggering the “New Member” automation trigger)
Updating contact type is now handled by /api/v3/contacts/{contactId}/updateContactType. And setting isApproved to “true” must be done manually in v3 using:

Preferences

The individual endpoints used to update preferences were consolidated into the contact update endpoint. This means that the following endpoints are removed in v3:
  • /api/v2/contacts/{contactId}/preferences/acceptsEmail
  • /api/v2/contacts/{contactId}/preferences/acceptsPostal
  • /api/v2/contacts/{contactId}/preferences/acceptsSms
Their logic is now handled instead by /api/v3/contacts/{contactId}.

Posoffers

The /api/v2/posoffers endpoints are obsolete and will be deprecated. Promotions should now be handled by /api/v3/promotions. The following “posoffers” endpoints are removed in v3:
  • /api/v2/contacts/{contactId}/posoffers/all
  • /api/v2/contacts/{contactId}/posoffers/{id}/redeem
  • /api/v2/contacts/{contactId}/posoffers/available
  • /api/v2/contacts/{contactType}/bykey/{keyValue}/posoffers/{id}/redeem
  • /api/v2/contacts/{contactType}/bykey/{keyValue}/posoffers/all
  • /api/v2/contacts/{contactType}/bykey/{keyValue}/posoffers/available
  • /api/v2/contacts/bykey/{keyValue}/posoffers/{id}/redeem
  • /api/v2/contacts/bykey/{keyValue}/posoffers/all
  • /api/v2/contacts/bykey/{keyValue}/posoffers/available

Promotions

Changes were made to the promotions endpoints. The following endpoints are removed in v3:
  • /api/v2/contacts/{contactId}/promotions: use /api/v3/promotion-assignments to fetch a contact’s promotions
  • /api/v2/contacts/{contactId}/promotions/{promotionId}/redeem: replaced by /api/v3/promotion-assignments/{assignmentId}/redeem
  • /api/v2/contacts/{contactId}/promotions/{promotionId}/assign: replaced by /api/v3/promotion-assignments

Points

Changes were made to the /api/v3/point-accounts section to clarify usage and consolidate endpoints. Parameters sent to /api/v3/point-accounts to get a contact’s points have changed. Because of the changes to /api/v3/contactoverview, /api/v3/point-accounts is now the only way to fetch a contact’s points.

The Points API

The following endpoints are deprecated and should no longer be used:
  • /api/v2/point-accounts/definitions
  • /api/v2/point-accounts/definitions/{id}
The following v2 endpoints are no longer used or not to be used, and are replaced as shown:
  • /api/v2/contacts/rewardpointtransaction: replaced by /api/v3/point-accounts/transactions
  • /api/v2/point-accounts/transactions: replaced by /api/v3/point-transactions
  • /api/v2/point-accounts/transactions/{id}: replaced by /api/v3/point-transactions/{id}

Reward vouchers (bonus checks)

The following endpoints are replaced in v3:
  • /api/v2/promotions/reward-vouchers/{id}/reactivate is replaced by /api/v3/reward-vouchers/{rewardVoucherId}/reactivate
  • /api/v2/contacts/{contactId}/bonuschecks/{bonusCheckId}/redeem is replaced by /api/v3/reward-vouchers/{rewardVoucherId}/redeem
  • /api/v2/contacts/{contactId}/bonuschecks is replaced by /api/v3/reward-vouchers
  • /api/v2/contacts/{contactId}/bonuschecks/available is replaced by /api/v3/reward-vouchers/available
  • /api/v2/contacts/{contactId}/bonuschecks/redeemed is replaced by /api/v3/reward-vouchers/redeemed
The attribute usedBonusChecks is replaced by usedRewardVouchers. The attribute checkNumber is replaced by voucherNumber.

Tracking and inventory

Changes were made to the tracking and inventory sections to support multiple items in a single request.
  • /api/v2/tracking/carts/batch: removed
  • /api/v2/tracking/carts is replaced by /api/v3/tracking/carts, which can accept multiple items
  • /api/v2/tracking/productviews: removed
  • /api/v2/tracking/productview is replaced by /api/v3/tracking/productview, which can accept multiple items
  • /api/v2/inventory/stock-levels/batch: removed. Batch functionality is now handled by the enhanced /api/v3/inventory/stock-levels

Transactions / Receipts

/api/v2/transactions, used to import receipts, is deprecated. In v3, use /api/v3/receipts instead. The attribute usedBonusChecks is replaced by usedRewardVouchers. The attribute awardsBonus is replaced by awardsPoints. The attribute checkNumber is replaced by voucherNumber.

Messages

Changes were made to how historical email, SMS and postal messages are fetched for a contact. The single endpoint /api/v2/contacts/{contactId}/messages/latest is replaced by three endpoints:
  • /api/v3/contacts/{contactId}/emailmessages
  • /api/v3/contacts/{contactId}/smsmessages
  • /api/v3/contacts/{contactId}/postalmessages

Other changes

The following endpoint is removed in v3:
  • /api/v2/memberstatus
Last modified on November 18, 2026