Skip to content

Reports – recommendation attribution

This method returns the products that customers purchased through ECDP recommendations within a selected date range. Each record is one purchased product attributed to a recommendation shown in an email, a pop-up, or a banner.

Each record identifies the order, the customer, the channel and the message or campaign that delivered the recommendation, and the value of the product. You can optionally add descriptive fields of the attributed product and the full list of products from the same order.

Use this method to audit the performance of recommendations.

Endpoint

GET /reports/attribution/recommendations

Host: https://api.ecdp.app

Request parameters

ParameterLocationTypeRequiredDescriptionAllowed values / Notes
x-api-keyheaderstringyesAPI key for authenticationAvailable in Settings > API
startDatequerystringyesStart of the reporting windowFormat: YYYY-MM-DD. Interpreted in the business unit’s time zone. Must be earlier than or equal to endDate.
endDatequerystringyesEnd of the reporting windowFormat: YYYY-MM-DD. Interpreted in the business unit’s time zone. The whole end date is included.
websitequerystringnoFilters results by website ID or website nameWebsite ID (integer)
channelqueryenumconditionalLimit results to a single channelEmail, PopUp, Banner, Sms, WebPush. Values are not case-sensitive. Required when messageType, messageId, or campaignId is provided. Sms and WebPush are accepted, but recommendations are not available for these channels, so the response is empty.
messageTypequeryenumnoLimit results to a single message typeNewsletter, Scenario, Confirmation. Requires channel=Email, Sms, or WebPush. Confirmation is available for Email only.
messageIdqueryintegernoLimit results to a specific messageRequires channel=Email, Sms, or WebPush.
campaignIdqueryintegernoLimit results to a specific pop-up or banner campaignRequires channel=PopUp or Banner.
includeProductDetailsquerybooleannoInclude descriptive fields of the attributed productTrue or false. Default: false
includeOrderDetailsquerybooleannoInclude all products from the order of each recordTrue or false. Default: false

Response

The response contains a data array. Each element represents one purchased product attributed to a recommendation.

Recommendation attribution report data

FieldTypeDescription
dateTimestringDate and time of the record, in the business unit’s time zone. Format: YYYY-MM-DDThh:mm:ss, without a UTC offset.
websiteIdintegerWebsite the order originated from
channelstringChannel that delivered the recommendation: Email, PopUp, or Banner
messageTypestringType of message: Newsletter, Scenario, or Confirmation. Omitted for PopUp and Banner.
messageIdintegerIdentifier of the attributed message. Omitted for PopUp and Banner.
campaignIdintegerIdentifier of the attributed pop-up or banner campaign. Omitted for Email.
orderIdstringIdentifier of the order that contains the attributed product
customerobjectSee Customer data. Omitted when the order is not linked to a customer.
productIdstringIdentifier of the attributed product, as provided by the e-commerce source
productValueConvertednumberValue of the attributed product converted to the tenant’s reporting currency
productDetailsobjectPresent when includeProductDetails=true. Has the structure described in Product details.
orderDetailsarrayPresent when includeOrderDetails=true. Each item has the structure described in Product details.

Customer data

The customer object contains the following fields.

FieldTypeDescription
idintegerECDP internal customer ID
emailstringCustomer email address
phonestringCustomer phone number
crmIdstringCustomer CRM identifier

Product details

When includeProductDetails=true, each record includes a productDetails object that describes the attributed product. When includeOrderDetails=true, each record includes an orderDetails array with all products from the order. Both use the same structure, the same as order details in the order attribution report. If you set both parameters to true, the attributed product appears in both productDetails and orderDetails.

FieldTypeDescription
idstringProduct identifier as provided by the e-commerce source
namestringProduct name
pricenumberUnit price in the original transaction currency
quantityintegerQuantity purchased
returnedintegerQuantity returned. Omitted if not set
categorystringProduct category. Omitted if not set
productAttributesarrayArray of { name, value } pairs with product-level custom attributes. Omitted if none
recommendationAttributionobjectPresent when the product was added via an ECDP recommendation. See structure below

Recommendation attribution object

FieldTypeDescription
scopestringAttribution scope: Channel (Email) or Onsite (PopUp, Banner)
typestringRecommender type: Personalized, Complementary, Bestsellers, Popular, SimilarProducts, CrossSell, VisuallySimilar, SimilarProperties, Emailing, or RecentlyViewed
idintegerIdentifier of the message (Email) or campaign (PopUp, Banner) that delivered the recommendation
channelstringRecommendation surface: Email, PopUp, or Banner

Example requests and responses

Get recommendation-attributed purchases for a date range

GET /reports/attribution/recommendations?startDate=2025-03-01&endDate=2025-03-07

Response (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-03T11:24:15",
      "websiteId": 1,
      "channel": "Banner",
      "campaignId": 310,
      "orderId": "100042",
      "customer": {
        "id": 981245,
        "email": "customer@example.com",
        "phone": "48123456789",
        "crmId": "778"
      },
      "productId": "SKU-225",
      "productValueConverted": 29.95
    }
  ]
}

Get purchases attributed to an email newsletter, with product details

GET /reports/attribution/recommendations?startDate=2025-03-01&endDate=2025-03-07&website=21&channel=Email&messageType=Newsletter&messageId=12045&includeProductDetails=true

Response (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-05T19:02:41",
      "websiteId": 1,
      "channel": "Email",
      "messageType": "Newsletter",
      "messageId": 12045,
      "orderId": "100057",
      "customer": {
        "id": 771100,
        "email": "customer@example.com",
        "phone": "",
        "crmId": "101"
      },
      "productId": "SKU-101",
      "productValueConverted": 39.90,
      "productDetails": {
        "id": "SKU-101",
        "name": "Canvas Tote",
        "price": 39.90,
        "quantity": 1,
        "returned": 0,
        "category": "Bags"
      }
    }
  ]
}

Get purchases attributed to a banner campaign, with product and order details

GET /reports/attribution/recommendations?startDate=2025-03-15&endDate=2025-03-15&website=21&channel=Banner&campaignId=310&includeProductDetails=true&includeOrderDetails=true

Response (200 OK):

{
  "data": [
    {
      "dateTime": "2025-03-15T09:41:06",
      "websiteId": 1,
      "channel": "Banner",
      "campaignId": 310,
      "orderId": "100063",
      "customer": {
        "id": 332100,
        "email": "customer@example.com",
        "phone": "",
        "crmId": "551"
      },
      "productId": "SKU-555",
      "productValueConverted": 51.40,
      "productDetails": {
        "id": "SKU-555",
        "name": "Insulated Mug",
        "price": 51.40,
        "quantity": 1,
        "returned": 0,
        "category": "Kitchen",
        "recommendationAttribution": {
          "scope": "Onsite",
          "type": "Bestsellers",
          "id": 310,
          "channel": "Banner"
        }
      },
      "orderDetails": [
        {
          "id": "SKU-101",
          "name": "Canvas Tote",
          "price": 39.90,
          "quantity": 1,
          "returned": 0,
          "category": "Bags",
          "productAttributes": [
            { "name": "color", "value": "natural" }
          ]
        },
        {
          "id": "SKU-555",
          "name": "Insulated Mug",
          "price": 51.40,
          "quantity": 1,
          "returned": 0,
          "category": "Kitchen",
          "recommendationAttribution": {
            "scope": "Onsite",
            "type": "Bestsellers",
            "id": 310,
            "channel": "Banner"
          }
        }
      ]
    }
  ]
}

Response codes

CodeStatusDescription
200OKRequest processed successfully. Response contains the list of attributed products. When nothing matches the query, the data array is empty.
400Bad RequestInvalid or missing parameters. The response contains the substatus and errors fields that identify the problem.
401UnauthorizedAPI key is missing, invalid, or expired. Verify your key in Settings > API.

Validation and behavior rules

  • startDate and endDate are required and must use the YYYY-MM-DD format. startDate must be earlier than or equal to endDate. Otherwise the request returns 400 Bad Request.
  • website must be an existing website ID. Otherwise the request returns 400 Bad Request.
  • channel is required when messageType, messageId, or campaignId is provided.
  • messageType and messageId can be used only with channel=Email, Sms, or WebPush. campaignId can be used only with channel=PopUp or Banner. A combination that does not match returns 400 Bad Request.
  • The messageType value Confirmation is valid only when channel=Email.
  • messageId and campaignId must point to an existing message or campaign. Otherwise the request returns 400 Bad Request.
  • Recommendations are available for the Email, PopUp, and Banner channels. A request with channel=Sms or channel=WebPush is valid, but always returns an empty data array.
  • When an order is not linked to a customer, the customer object is omitted from the record.

Reference documentation

Swagger – Reports attribution

https://api.ecdp.app/swagger/index.html

Privacy policy