Changes in API v3

The current version of the Engage API has been upgraded to 3 to introduce new functionality, to make it easier to expand the API in the future, and to introduce more consistency.

Here is a summary of the changes going from v2 to v3:

• Consolidated and renamed endpoints for 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

All existing usage of API v2 and v1 are not affected by these changes as those versions will 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.

Generally, new endpoints are only added in new API versions, as well as breaking changes. Non-breaking changes to existing endpoints may however 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 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 /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 is changed to asynchronous, meaning you will be able to store data to be acted on independantly from the order data.

Using the new /orders endpoint

New endpoint /orders. Use GET to all stored orders for a contact and POST to register a new order.

New endpoint **/orders/ **. Use GET to retrieve a single order, PUT to update an existing order and DELETE to delete the order permanently.

New endpoint /orders//action, used to trigger an automation and send order communication by email or SMS.

How to trigger order communication

New endpoint /orders/jobs/ used to check the status of an order registration or update.

Contacts

Changes to the /contacts endpoints were done for better experience and consistency, moving some to other groups or changing the terminology for clarification of its function.

The names of the /contacts//bonuschecks endpoints (four of them) changed to /reward-vouchers and some parameters and payload values have changed. See the “Reward vouchers (bonus checks)” section below.

Endpoint /contacts//bykey/ removed in v3. The same functionality is available from the /contacts//bykey endpoint.

Endpoint /contacts/count removed in v3 (but is still available in v2).

Endpoint /contacts//count removed (but is still available in v2).

Endpoint /contacts//bonuspointtransactions removed in v3. Now point transactions for contacts are fetched by first getting point account ID using /point-accounts and then using this ID in /point-transactions to get the actual point transactions.

The header parameters when creating a contact with /contacts are now query parameters.

The header parameters when deleting a contact with /contacts are now also query parameters.

Method when updating contact with /contacts/ changed from POST to PATCH.

The endpoint /contacts//transactions changed to its own resource /transactions and the contactId is now sent in the query string. More article data is returned in the response in v3.

Contact overview

Changes made to the payload for /contactoverview. The property “bonusPoints” changes name to “points” and “checkNumber” changes to “voucherNumber”.

In v3 a contact’s total points (bonus points) are no longer returned from /contactoverview. This must now be done with a separate GET request to the already existing (but slightly changed) endpoint /point-accounts.

Promote to member

Endpoint /contacts//promoteToMember is removed. Logic now handled by /contacts//updateContactType.

Preferences

The individual endpoints used to update preferences were consolidated to the contact update.

Endpoints /contacts//preferences/acceptsEmail, /contacts//preferences/acceptsPostal and /contacts//preferences/acceptsSms removed in v3. Logic now handled by the update endpoint /contacts/.

Posoffers

The /posoffers endpoints are obsolete and will be deprecated. Promotions should now be handled by the /promotions endpoint.

Endpoint /contacts//posoffers/all removed in v3.

Endpoint /contacts//posoffers//redeem removed in v3.

Endpoint /contacts//posoffers/available removed in v3.

Endpoint /contacts//bykey//posoffers//redeem removed in v3.

Endpoint /contacts//bykey//posoffers/all removed in v3.

Endpoint /contacts//bykey//posoffers/available removed in v3.

Endpoint /contacts/bykey//posoffers//redeem removed in v3.

Endpoint /contacts/bykey//posoffers/all removed in v3.

Endpoint /contacts/bykey//posoffers/available removed in v3.

Promotions

Changes were made to the /promotions endpoints;

Endpoint contacts//promotions removed. To fetch a contact’s promotions you can now use /api/v3/promotion-assignments.

Endpoint /contacts//promotions//redeem removed in v3. For the same functionality use /api/v3/promotions/codes//redeem.

Endpoint /contacts//promotions//assign removed and functionality replaced by /api/v3/promotion-assignments.

Points

Changes were made to the /point-accounts section to clarify usage and consolidate endpoints.

Parameters sent to /point-accounts in order to get a contact’s points have changed. Note that, because of the changes to /contactoverview, the /point-accounts endpoint is now the only way to fetch a contact’s points.

The Points API

Endpoints /point-accounts/definitions and /point-accounts/definitions are deprecated and should no longer be used.

Endpoint /contacts/rewardpointtransaction no longer used, replaced by /api/v3/point-accounts/transactions.

Endpoint /point-accounts/transactions is not to be used and is replaced by /api/v3/point-transactions.

Endpoint /point-accounts/transactions/ is not to be used and is replaced by /api/v3/point-transactions/.

Reward vouchers (bonus checks)

Endpoint /promotions/reward-vouchers//reactivate becomes /reward-vouchers//reactivate.

Endpoint /contacts//bonuschecks//redeem becomes /reward-vouchers//redeem.

Endpoint /contacts//bonuschecks changed to /reward-vouchers.

Endpoint /contacts//bonuschecks/available becomes /reward-vouchers/available.

Endpoint /contacts//bonuschecks/redeemed becomes /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 supports multiple items in a single request.

Endpoint /tracking/carts/batch removed.

Endpoint /tracking/carts enhanced to /tracking/carts and can accept multiple items.

Endpoint /tracking/productviews removed.

Endpoint /tracking/productview enhanced to /tracking/productview and can accept multiple item.

Endpoint inventory/stock-levels/batch removed. Batch functionality now handled by enhanced version of /inventory/stock-levels.

Transactions / Receipts

Endpoint /transactions used to import receipts is deprecated. In v3 use /receipts instead.

The attribute usedBonusChecks is replaced by usedRewardVouchers.

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//messages/latest is replaced by three endpoints:

• /api/v3/contacts//emailmessages
• /api/v3/contacts//smsmessages
• /api/v3/contacts//postalmessages

Other changes

Endpoint /memberstatus removed in v3.