Buy with Prime | Developer Documentation
Documentation

Get User Engagement Data

📘

Important

The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.

The Buy with Prime API offers a User Events report to help you track user engagement such as numbers of shoppers browsing a detail page, page loads, Prime badge views, checkout started, checkout completed, and so on. You can use the report to find insights such as clickthrough rates, conversion uplift, and drop-off rates.

To produce a User Events report, you first must send the user events that represent the data you want to track to your Buy with Prime account. User events are processed and stored in your account within fifteen minutes of receiving the event.

There are two ways to track user events:

  • Server-side [Recommended]
    In this method, your server sends user events to your Buy with Prime account by using the Buy with Prime API. This approach is the most reliable and the easiest to maintain, because the server is an environment that you control. As such, you can add tracking in one place (your servers) rather than in diverse places (web, iOS, Android).
    However, server-side tracking has limitations with respect to capturing certain shopper interactions. A server-side user event can be captured when a page loads, but it might not be able to determine if the page was actually rendered. Similarly, not every click, hover, or scrolling action leads to a back-end service call, and therefore can’t be captured with server-side tracking alone.
  • Client-side
    In this method, user events are generated on the shopper's desktop or mobile device and sent to your Buy with Prime account by using the Buy with Prime API. It can capture granular interactions like clicks, hovers, and scrolling. Client-side tracking is less reliable than server-side because it might be obstructed by ad blockers, browser settings, and network issues. It's also harder to maintain across multiple platforms, because it might involve redeploying your app to web and mobile clients.
    We therefore recommend that you track everything you can by using your servers, and only supplement that with client-side tracking when necessary.

Regardless of whether you send server-side or client-side user events, we recommend that you call the sendUserEvents mutation asynchronously so that you can track user events in a non-blocking way.

Once you've set sent user events to Buy with Prime, you can generate the report. When the report is ready, you download it from the report download link.

Step 1: Send user events to your Buy with Prime account

The following examples show how to track user engagement by generating user events such as clicks and page loads with the sendUserEvents mutation.

Send a non-blocking API call

The following example shows a non-blocking API call.

JavaScript 
// Async client
sendUserEventsMutation = async(mutation) => {
   const res = await fetch(buyWithPrimeUrl,  {
    method: "POST",
    headers: buyWithPrimeHeaders,
    mutation
   });
   return res.json();
}

Send a page load user event for the pre-order checkout page

Send the page-load user event when the shopper views the order review page before they check out, but after they successfully sign in using their Amazon credentials.

Request 
// GraphQL mutation
mutation sendEvents {
  sendUserEvents(
    input: {
      events: [
        {
          eventType: "page-load",
          eventId: "example-event-id",
          eventTime: "2024-05-31T13:15:30Z",
          clientType: WEBSITE_CLIENT,
          clientVersion: "1.0",
          schemaName: "sfcc-schema",
          schemaVersion: "1",
          additionalProperties: {
            additionalProperties: [
              { 
                property: "ubid", 
                value: "example-ubid" 
              },
              {
                property: "userAgent",
                value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
              },
              {
                property: "currentUrl",
                value: "https://example.com/products/example-product?referrer_domain=www.google.com",
              },
              {
                property: "referrer",
                value: "https://example.com/"
              },
              {
                property: "product_sku",
                value: "example-sku"
              },
              {
                property: "prime_promise_timestamp",
                value: "1709882221"
              },
              {
                property: "page_type",
                value: "checkout" 
              }
            ]
          }
        }
      ]
    }
    ) {
        status
    }
}
Response 
{
  "data": {
    "sendUserEvents": {
      "status": "successful"
    }
  }
}

Send a page load user event for the post-order confirmation page

You can also send the page-load user event when the shopper views the order confirmation page after they place their order.

Request 
// GraphQL mutation
mutation sendEvents {
  sendUserEvents(
    input: {
      events: [
        {
          eventType: "page-load",
          eventId: "example-event-id",
          eventTime: "2024-05-31T13:15:30Z",
          clientType: WEBSITE_CLIENT,
          clientVersion: "1.0",
          schemaName: "sfcc-schema",
          schemaVersion: "1",
          additionalProperties: {
            additionalProperties: [
              { 
                property: "ubid", 
                value: "example-ubid" 
              },
              {
                property: "userAgent",
                value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
              },
              {
                property: "currentUrl",
                value: "https://example.com/products/example-product?referrer_domain=www.google.com",
              },
              {
                property: "referrer",
                value: "https://example.com/"
              },
              {
                property: "product_sku",
                value: "example-sku"
              },
              {
                property: "page_type",
                value: "checkout" 
              },
              {
                property: "example-order-id",
                value: "234454545"
              }
            ]
          }
        }
      ]
    }
    ) {
        status
    }
}
Response 
{
  "data": {
    "sendUserEvents": {
      "status": "successful"
    }
  }
}

Send a click user event

Send the click user event when the shopper adds a Buy with Prime product to their cart or they click the Buy with Prime button to start checkout.

Request 
// GraphQL mutation
mutation sendEvents {
  sendUserEvents(
    input: {
      events: [
        {
          eventType: "click",
          eventId: "example-event-id",
          eventTime: "2024-05-31T13:15:30Z",
          clientType: WEBSITE_CLIENT,
          clientVersion: "1.0",
          schemaName: "sfcc-schema",
          schemaVersion: "1",
          additionalProperties: {
            additionalProperties: [
              { 
                property: "ubid", 
                value: "example-ubid" 
              },
              {
                property: "userAgent",
                value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
              },
              {
                property: "currentUrl",
                value: "https://example.com/products/example-product?referrer_domain=www.google.com",
              },
              {
                property: "referrer",
                value: "https://example.com/"
              },
              {
                property: "product_sku",
                value: "example-sku"
              },
              {
                property: "page_type",
                value: "cart" 
              },
              {
                property: "prime_promise_timestamp",
                value: "1709882221"
              },
              {
                property: "page_action",
                value: "add-to-cart"
              }
            ]
          }
        }
      ]
    }
    ) {
        status
    }
}
Response 
{
  "data": {
    "sendUserEvents": {
      "status": "successful"
    }
  }
}

Send a buyability user event

Buyability is a determination of whether a product is eligible for Buy with Prime. Buyability depends on multiple factors, such as whether you correctly configured the product for Buy with Prime. Send the widget-viewed user event when the product is buyable, meaning the Prime badge is rendered on a page.

Request 
// GraphQL mutation
mutation sendEvents {
  sendUserEvents(
    input: {
      events: [
        {
          eventType: "widget-viewed",
          eventId: "example-event-id",
          eventTime: "2024-05-31T13:15:30Z",
          clientType: WEBSITE_CLIENT,
          clientVersion: "1.0",
          schemaName: "sfcc-schema",
          schemaVersion: "1",
          additionalProperties: {
            additionalProperties: [
              { 
                property: "ubid", 
                value: "example-ubid" 
              },
              {
                property: "userAgent",
                value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
              },
              {
                property: "currentUrl",
                value: "https://example.com/products/example-product?referrer_domain=www.google.com",
              },
              {
                property: "referrer",
                value: "https://example.com/"
              },
              {
                property: "product_sku",
                value: "example-sku"
              }
            ]
          }
        }
      ]
    }
    ) {
        status
    }
}
Response 
{
  "data": {
    "sendUserEvents": {
      "status": "successful"
    }
  }
}

Send a delivery estimate user event

Send the bwp-widget-promise-loaded user event when the Buy with Prime delivery estimate is rendered or the shopper switches to a different variant within the same product detail page.

Request 
// GraphQL mutation
mutation sendEvents {
  sendUserEvents(
    input: {
      events: [
        {
          eventType: "bwp-widget-promise-loaded",
          eventId: "example-event-id",
          eventTime: "2024-05-31T13:15:30Z",
          clientType: WEBSITE_CLIENT,
          clientVersion: "1.0",
          schemaName: "sfcc-schema",
          schemaVersion: "1",
          additionalProperties: {
            additionalProperties: [
              { 
                property: "ubid", 
                value: "example-ubid" 
              },
              {
                property: "userAgent",
                value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
              },
              {
                property: "currentUrl",
                value: "https://example.com/products/example-product?referrer_domain=www.google.com",
              },
              {
                property: "referrer",
                value: "https://example.com/"
              },
              {
                property: "product_sku",
                value: "example-sku"
              },
              {
                property: "prime_promise_timestamp",
                value: "1709882221"
              }
            ]
          }
        }
      ]
    }
    ) {
        status
    }
}
Response 
{
  "data": {
    "sendUserEvents": {
      "status": "successful"
    }
  }
}

Step 2: Start the report

To generate a report, use the startReportTask mutation. In the request, you can set a date range. Dates are in ISO-8601 UTC format. If you don’t provide a date range, startReportTask defaults to the last seven days.

The response contains a unique taskId that you use to get the status of or get a link to to the report.

The amount of time it takes to generate a report depends on a number of factors:

  • The type of report you request: Reports that involve advanced joins takes more time to process.
  • The requested data range: The longer the data range, the more time the report takes to process.
  • The amount of data you have: If you have a lot of data, such as orders, reports take more time to process.

You can have at most five startReportTask requests in STARTED state at any time. If you submit more than five requests, you get a ThrottlingException.

The following example shows how to call the startReportTask mutation.

Request 
// GraphQL mutation
mutation StartReportTask {
  startReportTask(
    input: {
      timeRange: {
        startDate: "2023-06-01T20:58:49Z"
        endDate: "2024-06-03T20:58:49Z"
      }
      reportType: "USER_EVENTS"
    }
  ) {
    taskId
  }
}
Response 
{
  "data": {
    "startReportTask": {
      "taskId": "example-task-id"
    }
  }
}

Step 3: (Optional) Get the status of the report

To check the status of a report you use the reportTask query with the taskId that you received when you performed a startReportTask mutation.

Reports expire seven days from the time the report was created. For example, if you called startReportTask on 2023-03-07T05:46:00Z, the report expires on 2023-03-14T05:46:00Z. After the report expires, the report is no longer available to download. However, you can make a new request to startReportTask to create a new report.

The status field of the response contains the status of the report. The status can be STARTED, COMPLETED, FAILED.

If you call reportTask with a taskId for an expired report, you get a ResourceNotFoundException.

The following example shows how to get the status of a report.

Request 
// GraphQL query
query ReportTask {
  reportTask(taskId: "example-task-id") {
    status
    requestTime
    lastUpdatedTime
    reportType
    taskId
  }
}
Response for a valid `taskId` 
{
  "data": {
    "reportTask": {
      "status": "STARTED",
      "requestTime": "2024-07-21T22:24:33.436Z",
      "lastUpdatedTime": "2024-07-21T22:24:33.692Z",
      "reportType": "USER_EVENTS",
      "taskId": "example-task-id"
    }
  }
}
Response for an expired `taskId` 
{
  "errors": [
    {
      "message": "Querying for an invalid or expired taskId",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["reportTask"],
      "extensions": {
        "classification": {
          "type": "ResourceNotFoundError",
          "errorType": "ResourceNotFoundException",
          "errorCode": 404
        }
      }
    }
  ],
  "data": {
    "reportTask": null
  }
}

Step 4: Get the report

To get a link to download the report, use the reportDownloadLink query with the taskId from the startReportTask mutation.

The response to the reportDownloadLink query contains a URL that you can use to download a report. The URL expires five minutes after your call to reportDownloadLink. If five minutes have passed, you can make a new call to reportDownloadLink query to get a new URL. The report itself is accessible for seven days after the report is created. You can call the reportDownloadLink query to get a new link to the report as many times as needed till the expiry of the report.

After you get a link to the report, you can download the CSV file by using a standard interface in your chosen programming language.

The following example shows how to get the download link for a report.

Request 
// GraphQL query
query Query {
  reportDownloadLink(
    taskId: "USER_EVENTS:23272b65-efac-412d-a8aa-ce8ef41bb448"
  ) {
    downloadUrl
  }
}
Response 
{
  "data": {
    "reportDownloadLink": {
      "downloadUrl": "https://example-download-url"
    }
  }
}

Fields in the report

User Event reports have the following fields. In the reports, the fields are not necessarily in this order.

Column NameDescription
Event NameThe type of event. Examples: Page Load, Click, Widget Load, and so on.
Event IDUnique identifier for the event. Example: e.g. 1a2b3c-4d5e6f7g8-h9i0j1i2l3m4n5.
TimestampEpoch timestamp, in milliseconds, when the event occurred. Example: 1724543998724.
Current URLThe full page URL where the event happened. Example: https://store.com/example-product.
Store DomainMerchant store URL that uniquely identifies a store. Example: https://example-store.com.
Page Type

The page where the link was clicked. Examples:

  • cart: Cart page
  • checkout: Checkout page
  • collections: Collections page
  • product-page-widget: Product detail page
Page ActionDescription of what the user took action on. Valid only for click events such as "Place order."

Example report

The following table shows an example of a User Events report.

Event NamePage TypePage ActionEvent IDTimestampCurrent URLStore Domain
Page Loadproduct-page-widgetN/Aexample-event-id-123451724543998724
https://store.com/example-product
https://example-store.com
Clickcheckoutplace orderexample-event-id-678901724543998724
https://store.com/checkout
https://example-store.com

Related topics

Updated 2 days ago