Common elements

Determines the format of the message. It should be one of the following:

• home
• category
• product
• basket
• checkout
• order
• searchresults
• wishlist
• other

[Optional]

If specified, the IP address can be used for a geolocation lookup to identify the approximate location of the visitor for a personalized online experience for Promote. IP address is not stored.

Use new if no session was established with Episerver yet.

On a successful response, the allocated session is returned. Use that session ID for subsequent requests for this cuid and session.

Sessions should expire after a period of user inactivity (such as 4 hours). So, any requests after this period should revert to new.

Use new if the cuid is unknown.

On a successful response, the cuid value is returned. Store the cuid in persistent storage and send it back in future requests so you can track the same customer across multiple sessions (see Storing customer IDs).

Note: Use the same cuid for subsequent requests related to the same user/device.

Identifies the retailer's site with the site code provided by Episerver.

A token provided to the Episerver customer that must be included as part of the JSON data in every API call.
A separate clientToken is issued for each channel.
Ensure that you are using the correct token for your channel.

Note: Any clientToken provided by Episerver to access the RESTful service hosted on our UAT server is different from the one provided for the service on our live server. Make sure you are using the appropriate clientToken.

[Optional] 

It should be one of the following:

• web
• mobileweb
• mobileapp
• tv
• callcenter
• facebook

If omitted, web is assumed.

Contact Episerver if you need more channels. A separate clientToken is issued for each channel. Ensure that you are using the correct token for your channel.

For example, for web customers, this is the referrer header.

[Optional]

This identifies the user in the Personalization system.

Use the user ID to improve tracking and recommendations; you can use it also in other Episerver products, such as Mail and Triggers.

You can pass the user element on any page. Do this once per session; you typically supply it on the next page load following a customer login.

Information about the site visitor’s browser and operating system.

Mandatory from v1.3 of the Server-to-Server API.

[Optional]

Available values are:

• summary Only the test name and A/B group are returned in the response.
• full All available A/B group information is returned in the response.

If this attribute is omitted, no A/B Testing information is returned.

See A/B testing for more information.

[Optional]

Available values:

• full Returns full product details (such as, price, image, title, URL). This is the default behavior if recContent property is omitted.
• refCodeOnly Returns a list of elements containing only product reference codes and recommendation IDs.

Only applicable if you are using multiple Episerver products on a page. It overrides the configuration for a page, letting you switch off the generation of Episerver products for this request.

If smartProducts is not defined, the content for all Episerver products defined for the page is returned as normal.

[Optional]

An array of strings listing the Episerver products to include in the response for this page. Available values are smartRecs for Recommendations and smartContent for Promote.

For example, if Recommendations and Promote are configured for a page, but you only want results returned for Promote, not Recommendations, then include the smartProducts property in the request as follows:

smartProducts: [ “smartContent” ]

To return no Episerver product information on a page, use smartProducts as follows:

smartProducts: []

[Optional]

See Click tracking and A/B testing.

[Optional]

A comma-separated list of attribute names and values. Attribute names must contain no spaces.

"customAttributes" : { 
    "customerType": "XL",
    "userLocale"  : "en_GB", 
    "userSegment" : "gold"
}

Custom attributes are only used in real-time; they are not stored in the system.