Impressions

An impression should be recorded when a deal creative is displayed to a member. Recording impressions enables analytics, delivery optimization, and attribution tracking on the platform.

When to Record

Record an impression each time a creative returned by list-eligible is rendered and visible to the member. This typically means:

• The creative has entered the viewport and is visible on screen
• For email placements, when the email is opened/rendered

Do not record impressions for creatives that are fetched but never displayed (e.g. below-the-fold content the user never scrolls to).

Recording Impressions

You can submit impressions individually or in batches depending on how you want to integrate. Your systems can submit them directly to the Publisher software, or you can record them in your own database and use a background worker to asynchronously submit them to the Publisher software.

curl -X POST https://<your-instance-url>/publisher.v1/impression/record \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "impressions": [
      {
        "member_id": "m_x1y2z3",
        "creative_id": "dc_abc",
        "ad_unit_id": "au_abc123"
      },
      {
        "member_id": "m_a4b5c6",
        "creative_id": "dc_def",
        "ad_unit_id": "au_abc123"
      }
    ]
  }'

All three fields are required for each impression and correspond directly to the values returned by the list-eligible endpoint:

Field	Required	Source
member_id	yes	The member you queried delivery for
creative_id	yes	creative_id from the eligible deal
ad_unit_id	yes	The ad unit you queried delivery for
timestamp	no	ISO 8601 timestamp of when the impression occurred. Defaults to server time if omitted
idempotency_key	no	A unique string to deduplicate submissions

A maximum of 5,000 impressions can be submitted per request.

Timestamps

By default, impression timestamps are set server-side at recording time. If you are submitting impressions asynchronously (e.g. from a background worker that batches them from your own database), you can provide an explicit timestamp to record when the impression actually occurred:

{
  "impressions": [
    {
      "member_id": "m_x1y2z3",
      "creative_id": "dc_abc",
      "ad_unit_id": "au_abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

If timestamp is omitted, the server uses the current time.

Idempotency

When submitting impressions asynchronously or retrying failed requests, you can include an idempotency_key to prevent duplicate recordings. If an impression with the same key has already been recorded, the duplicate is silently skipped:

{
  "impressions": [
    {
      "member_id": "m_x1y2z3",
      "creative_id": "dc_abc",
      "ad_unit_id": "au_abc123",
      "idempotency_key": "019078a1-b4c3-7def-8a12-4b5c6d7e8f90"
    }
  ]
}

The key can be any unique string. Using a UUIDv7 generated at the time the impression occurs is a simple and reliable approach.

Impressions submitted without an idempotency_key are always recorded regardless of whether an identical impression already exists.

Best Practices

• Batch impressions - If multiple creatives are shown simultaneously (e.g. a feed of deals), record all impressions in a single request rather than one request per creative.
• Record at display time - Record the impression when the creative is actually rendered to the user, not when the eligible deals are fetched.
• Use exact values from delivery - Always use the creative_id and ad_unit_id exactly as returned by list-eligible. These values are used for attribution and must match precisely.