Transaction flow
A transaction can be seen as the "receipt" showing what the contact has bought. A transaction can contain many items, those that were purchased as well as those being returned. Transaction are sent to Engage and saved there, using contactId to connect them to a specific contact. The endpoint used to save them is:
POST /api/v3/receipts
Note
Another endpoint exists called /orders which is used to trigger automation flows and transactional communication. Don't confuse these two.
Saving a transaction
First, check if the customer exists as a contact in Engage. See here for how that's done. If they don't exist, you'll need to create them. Save their contactId in your system for future use.
Now you're sure the contact exists, send the purchase information to the /receipts endpoint shown above. The payload data needs to be in the correct JSON format. Here is how that looks.
Saving transaction error handling
If no response is received from the Engage API, or when the response has error code 500, you'll need a plan in place to ensure that no data is lost until the connection is restored.
Retry: If your first call is unsuccessful, perform a retry. Follows the recommendations here.
Local file: If errors remain, or no response is received, you should be ready to save the transactions to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Engage via the FTP server. Data uploaded like this is placed in a queue and handled asynchronously.
If you've tried to create a contact during your transaction flow, or updated contact information, then you'll have to handle that too, in the case of the connection being down. See here for that.
Tip
When uploading XML files via the FTP, contact GUIDs will not be returned from Engage for any new contacts created. Therefore, the next time that contact is identified, you'll need to check if their GUID already exists in your systems, and save it there if it doesn't, to reduce unnecessary API calls and improve your flow.