Skip to main content

Transactional communication flow

Transactional communication are all the email and SMS messages sent out to end-users to update them on the state of their order or their account: shipping, returns, payment confirmation, password changes, etc. Basically, this includes every communication sent out that is not purely marketing.

All the communication designed to entice the customer into making a purchase - general marketing, abandoned cart, recommendations, voucher expiration reminders - are not transactional and are not covered here.

Prerequisites

Along with the basic prerequisites some other things need to be done before transactional communication will work properly.

  • Order statuses must be set up in Engage (order confirmation, order shipped etc).

  • Payment statuses must be set up in Engage (processing, complete etc).

  • Active locales (all languages you'll communicate in) need to be configured and active.

  • An active automation (for new or updated orders) is required so can process the order.

  • The automation must have an email / SMS activity to send the communication.

  • Order email modules need to be set up in Engage (order items T03, order header T01 etc).

The endpoints

GET /api/v2/contacts/id

POST /api/v2/contacts

POST /api/v2/orders

Case1 - New customer places an order

  1. The contact must exist in Engage for it to send out the order communication. First check if the user exists in your systems (you should be saving contact IDs in your systems). If not, use this endpoint, along with the identifying information you have, to check if they exist in Engage:

    GET /api/v2/contacts/id

  2. If the contact does not exist in Engage, you'll need to create them. In the payload, send whatever data is required to create a new contact, which they'll have entered when they placed their order:

    POST /api/v2/contacts

    Save the contact's ID that's returned in your systems to simplify lookup in the future.

  3. Now send the order information that is needed to this endpoint. This triggers the automation you've built and sends out the customer's order confirmation email.

    POST /api/v2/orders

Case 2 - Existing customer places an order

  1. The customer places an order and, using the data they give, you find their contact ID in your local system (at some point you saved it after having it returned from Engage - good job!). Therefore you don't need to contact Engage to see if they exist there. Proceed to the next step.

  2. All that remains now is to send the order to this endpoint. This triggers the automation you've built (assuming you've built it correctly) and send out the customer's order confirmation email.

    POST /api/v2/orders

In this section: