Order Transfer Using the Generate event API Method

Order data is transmitted to our system via the resource Add orders that has a number of limitations:

• Fixed fields that are determined by the specification;
• Impossible to add custom fields;
• Order parameters cannot be used to build segments.

You can overcome them with the resource Generate event that can be used to replace or complement Add orders API method. By using it, you’ll be able to:

• Transmit more data with additional fields;
• Use segmentation by events and their parameters, for example, sort out contacts who bought a particular item within a week;
• Expand/receive RFM segmentation by order without additional usage of Add orders.

🚧

To save orders in the system, you need to set up segmentation by events as the event contains a contact identifier. It can be determined based on the default or conditional parameters.

How to Send Orders

For example, you can set up identification by unique token. The order will not be saved until these parameters are transmitted to the system. If you don’t set your own parameters, the system will search the identifier based on default parameters (email, phone, etc.).

You can use Generate event only for the existing contact. To send the order for a new contact, first import this contact into the system via:

• Add/update a contact;
• Add orders.

To send an order, you need to specify the event type. Choose the type from the below table based on the order status.

orderCreated

To create an order, name the parameters as indicated here and fill in the required parameters. If any of the required parameters isn’t filled, the event is ignored and the order will not be sent.

• ${eventKey} - event unique key transferred in externalOrderId. Used as an order identifier;
• ${orderId} - event ID in our system. Required to assign the event to a workflow.

The contact ID must be one of the following:

• ${externalCustomerId} - external contact ID;
• ${email} - contact’s email address;
• ${phone} - contact’s phone number.

To substitute parameter values in messages, send the fields with event parameters as an array.

• Required parameters for the order array: externalOrderId, totalCost, status, date, externalCustomerId / email / phone.
• Required parameters for the items array: externalItemId, name, quantity, cost, url, imageUrl.

📘

Note

The price of the products transferred in an order must match the totalCost value (total order amount). If a customer buys an item with a discount, it should be placed in the items.cost field for each product.

Example:

{
    "eventTypeKey": "orderCreated",
    "keyValue": "380501234567",
    "params": [
        {
            "name": "phone",
            "value": "380501234567"
        },{
            "name": "externalOrderId",
            "value": "12345679"
        }, {
            "name": "externalCustomerId",
            "value": "AV13760"
        }, {
            "name": "totalCost",
            "value": "258.0"
        }, {
            "name": "currency",
            "value": "USD"
        }, {
            "name": "status",
            "value": "INITIALIZED"
    }, {
        "name": "date",
        "value": "2020-05-14T10:11:00"
    }, {
        "name": "items",
        "value": [{
            "externalItemId": "200600",
            "name": "Super Device",
            "category": "devices",
            "quantity": 1,
            "cost": 990,
            "url": "http://example.com/item/200600",
            "imageUrl": "http://example.com/item/200600/image.png",
            "description": "High quality"
        }]
    }]
}

📘

Important

To save the event assigned to the contact, you need to know what event parameter contains the identifier. By default, the system searches for the following parameters excluding the register: ContactId, Contact_id, Email, EmailAddress, UserEmail, ContactEmail, Phone, SMS, PhoneNumber, PushToken, ContactKey, Contact_key. All values, except for the email address, are mapped including the register.

📌 Pay attention
If you want to show product data in an email, you need to use products in the event.

{
    "eventTypeKey": "orderCreated",
    "keyValue": "380501234567",
    "params": [
        {
            "name": "phone",
            "value": "380501234567"
        },{
            "name": "externalOrderId",
            "value": "12345679"
        }, {
            "name": "externalCustomerId",
            "value": "AV13760"
        }, {
            "name": "totalCost",
            "value": "258.0"
        }, {
            "name": "currency",
            "value": "USD"
        }, {
            "name": "status",
            "value": "INITIALIZED"
        }, {
            "name": "date",
            "value": "2020-05-14T10:11:00"
        }, {
            "name": "items",
            "value": [{
                "externalItemId": "200600",
                "name": "Super Device",
                "category": "devices",
                "quantity": 1,
                "cost": 990,
                "url": "http://example.com/item/200600",
                "imageUrl": "http://example.com/item/200600/image.png",
                "description": "High quality"
            }]
        },
        {
            "name": "products",
            "value": [{
                "array": [{
                    "externalItemId": "200600",
                    "name": "Super Device",
                    "category": "devices",
                    "quantity": 1,
                    "cost": 990,
                    "url": "http://example.com/item/200600",
                    "imageUrl": "http://example.com/item/200600/image.png",
                    "description": "High quality"
                }]
            }]
        }
    ]
}

orderUpdated

Updates the order that has the parameter externalOrderId filled.
If the transmitted order doesn’t exist in the system, it’s created anyway.

The parameters must be named as indicated in BODY PARAMS. If the order is to be created, the orderCreated requirements apply.

orderDelivered

Changes the order status to DELIVERED.
If the order does not exist, it is ignored.

📘

Note

Only orders with the DELIVERED status are used to build the RFM table and calculate revenue from campaigns on the Report tab.

Exceptions are orders received from the mobile SDK, in which case the statuses INITIALIZED and DELIVERED are taken into account by default in the revenue visualization. If necessary, the INITIALIZED statuses can be disabled — for this, contact our support service [email protected]

orderCancelled

Changes the order status to CANCELLED.