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 reflect 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
Important
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.
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 independently from actinging on the order data. See here for how to use 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/{orderId} . Use GET to retrieve a single order, PUT to update an existing order and DELETE to delete the order permanently.
New endpoint /orders/{orderId}/action, used to trigger an automation and send order communication by email or SMS. See in more detail here about how to trigger order communication using this endpoint.
New endpoint /orders/jobs/{jobId} 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/{contactId}/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/{contactType}/bykey/{keyValue} removed in v3. The same functionality is available from the /contacts/{contactType}/bykey endpoint.
Endpoint /contacts/count removed in v3 (but is still available in v2).
Endpoint /contacts/{contactType}/count removed (but is still available in v2).
Endpoint /contacts/{contactId}/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 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/{contactId} changed from POST to PATCH.
The endpoint /contacts/{contactId}/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". See here.
Important
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/{contactId}/promoteToMember is removed. Logic now handled by /contacts/{contactId}/updateContactType.
Preferences
The individual endpoints used to update preferences were consolidated to the contact update.
Endpoints /contacts/{contactId}/preferences/acceptsEmail, /contacts/{contactId}/preferences/acceptsPostal and /contacts/{contactId}/preferences/acceptsSms removed in v3. Logic now handled by the update endpoint /contacts/{contactId}.
Posoffers
The /posoffers endpoints are obsolete and will be deprecated. Promotions should now be handled by the /promotions endpoint.
Endpoint /contacts/{contactId}/posoffers/all removed in v3.
Endpoint /contacts/{contactId}/posoffers/{id}/redeem removed in v3.
Endpoint /contacts/{contactId}/posoffers/available removed in v3.
Endpoint /contacts/{contactType}/bykey/{keyValue}/posoffers/{id}/redeem removed in v3.
Endpoint /contacts/{contactType}/bykey/{keyValue}/posoffers/all removed in v3.
Endpoint /contacts/{contactType}/bykey/{keyValue}/posoffers/available removed in v3.
Endpoint /contacts/bykey/{keyValue}/posoffers/{id}/redeem removed in v3.
Endpoint /contacts/bykey/{keyValue}/posoffers/all removed in v3.
Endpoint /contacts/bykey/{keyValue}/posoffers/available removed in v3.
Promotions
Changes were made to the /promotions endpoints;
Endpoint contacts/{contactId}/promotions removed. To fetch a contact's promotions you can now use /api/v3/promotion-assignments.
Endpoint /contacts/{contactId}/promotions/{promotionId}/redeem removed in v3. For the same functionality use /api/v3/promotions/codes/{promotionId}/redeem.
Endpoint /contacts/{contactId}/promotions/{promotionId}/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. See here for more about the points API.
Endpoints /point-accounts/definitions and /point-accounts/definitions{id} 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/{id} is not to be used and is replaced by /api/v3/point-transactions/{id}.
Reward vouchers (bonus checks)
Endpoint /promotions/reward-vouchers/{id}/reactivate becomes /reward-vouchers/{rewardVoucherId}/reactivate.
Endpoint /contacts/{contactId}/bonuschecks/{bonusCheckId}/redeem becomes /reward-vouchers/{rewardVoucherId}/redeem.
Endpoint /contacts/{contactId}/bonuschecks changed to /reward-vouchers.
Endpoint /contacts/{contactId}/bonuschecks/available becomes /reward-vouchers/available.
Endpoint /contacts/{contactId}/bonuschecks/redeemed becomes /reward-vouchers/redeemed.
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.
Other changes
Endpoint /memberstatus removed in v3.