Skip to navigation

Attributions

Overview

As part of the integration, Kard offers robust solutions for collecting user attribution data for in-app and mobile push notification touchpoints. These data points provide valuable insights into how users interact with your rewards program.

Attribution metrics are increasingly becoming a key requirement among merchants as Kard continues to partner with top-of-wallet, everyday-spend brands. By enabling user attribution data collection, you’ll unlock access to more premium offers and drive stronger engagement within your program, ultimately helping you deliver greater value to your users.

Event Types and Mediums

Event Types

Kard’s attribution system collects two event types:

  • Impressions: Occur anytime a resource (like an offer logo or notification) is loaded within your app experience.

    Example: When a user opens the rewards screen and offers are displayed — each offer loaded generates an IMPRESSION event. See below for a visual representation of an impression event:

    Rewards List
  • Views: Occur anytime a user acts to view a specific resource.

    Example: When a user clicks an offer to view its details, or taps on a push notification to open the rewards screen — this generates a VIEW event. See below for a visual representation of a view event:

    Attribution Notification

Mediums

Each event must include a medium field to describe where in your experience the event occurred.

Supported mediums:

  • BROWSE — User is viewing a list of offers in the rewards experience.
  • MAP — User is exploring offers on a map view.
  • SEARCH — User is viewing or clicking offers as part of a search experience.
  • PUSH — Event occurred within a mobile push notification.

Implementation Methods

Kard supports two integration options for real-time attribution tracking. You may use either, but not both for the same event type:

  1. Event Tracking via Image URLs — Attribution tracking tokens are included with assets returned by Kard’s APIs and webhooks.
  2. Event Tracking via the Attribution API Endpoint — Provides direct event delivery if your system already tracks impressions and views.

In-App Experiences

Overview

In-app notifications and offer impressions are tracked when users interact with the rewards experience inside your application.

For in-app impressions and views, you can choose either:

  1. Image-based tracking, or
  2. The Attribution API Endpoint

Use a single method consistently for each event type to prevent duplication.


Option 1: Image-Based Tracking

When loading offers or images from Kard, append the eventCode and medium parameters to the provided URL. The images are provided in the Get Offers by User and Get Locations by User API endpoints in the data.attributes.assets.url fields.

Example payload:

GET /v2/issuers/{{organizationId}}/users/{{userId}}/offers
{
"data": {
"attributes": {
...
"assets": [
{
"url": "http://attribution.getkard.com/logos/breakfastbunny_logo.png?subtype=IMG_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
"alt": "",
"type": "IMG_VIEW"
},
{
"url": "https://attribution.getkard.com/public/banners/breakfast-bunny-banner.jpg?subtype=BANNER_VIEW&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D",
"alt": "",
"type": "BANNER_VIEW"
},
...
],
...
},
},
}
...

User browsing the rewards list → eventCode=IMPRESSION&medium=BROWSE

<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=IMPRESSION&medium=BROWSE"/>

User opening an offer detail page upon browsing list → eventCode=VIEW&medium=BROWSE

<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=VIEW&medium=BROWSE" />

User viewing offers on a map → eventCode=IMPRESSION&medium=MAP

<img src="https://attribution.getkard.com/image.jpg?token=valid.signed.jwt&eventCode=IMPRESSION&medium=MAP" />

Do not cache these image URLs. Kard’s CDN already handles caching to ensure accurate, real-time tracking.


Option 2: Attribution API Tracking

If you track these events yourself, you can send them directly to Kard via the Attribution API. Note, in addition to providing an eventCode and a medium the API requires an entityId representing the Kard-provided offerId related to the attribution event and an eventDate capturing the timestamp the event occurred.

User browsing the rewards list eventCode=IMPRESSION, medium=BROWSE

POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "IMPRESSION",
"medium": "BROWSE",
"eventDate": "2025-01-01T00:00:00Z"
}
}
]
}

User opening an offer detail page upon a map → eventCode=VIEW, medium=MAP

POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "offerAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c075",
"eventCode": "VIEW",
"medium": "MAP",
"eventDate": "2025-01-02T00:00:00Z"
}
}
]
}

Mobile Push Notifications

Overview

Kard supports attribution tracking for mobile push notifications, which allows you to measure engagement from the moment a notification is displayed (impression) through to user interaction (view).

For push notifications, Kard requires a hybrid approach:

  • IMPRESSION events: Must be sent via the Attribution API
  • VIEW events: Can be tracked either via the Attribution API or the image-based tracking method

Push Notification Impressions

Triggered when a Kard-provided push notification is displayed on a user’s device. You must use the attribution API to send push notification impressions.

Because iOS and Android do not provide a built-in, reliable way to capture notification impressions, this data should be sent on a best-effort basis. If your app or SDK can detect when a notification is actually shown (for example, using platform-specific APIs, analytics SDKs, or Firebase Cloud Messaging), use that signal to send the impression event.

If such tracking is not available, please instead send the event when the push notification is sent to the device.


What Works Best

Use your existing notification or analytics SDKs (e.g., Firebase Cloud Messaging or other in-app event trackers) to detect when a push notification is actually displayed on the user’s device. When available, this provides the most accurate impression data.

What to Do Instead

If you do not have tools or SDKs capable of detecting impressions, you can still participate in attribution by sending an impression event when the notification is sent to the device.

This data collection helps Kard approximate impressions that were sent to the user when display data isn’t available, without requiring any extra SDKs or configuration.

User’s lock screen displays a push notification for an earned reward → eventCode=IMPRESSION, medium=PUSH

Note: in addition to eventCode and a medium the API requires an entityId representing the Kard-provided notificationId related to the attribution event and an eventDate capturing the timestamp the event occurred.

POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144a623",
"eventCode": "IMPRESSION",
"medium": "PUSH",
"eventDate": "2025-01-06T00:00:00Z"
}
}
]
}

Push Notification Views

Triggered when a user clicks on a push notification and opens the app or relevant reward experience. You can choose either of the following implementations:

Option 1: Image-Based Tracking

The blank image pixel is included in the relevant notification webhooks within the data.attributes.attributionUrl field. To use it, append the eventCode and medium parameters to the provided URL.

Example payload:

{
"data": {
"attributes": {
"attributionUrl": "https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt",
...
},
...
},
...
}

User clicks into push notification and opens into app → eventCode=VIEW, medium=PUSH

<img src="https://attribution.getkard.com/public/logos/transparent.png?token=valid.signed.jwt&eventCode=VIEW&medium=PUSH" />

Option 2: Attribution API

If you track these events yourself, you can send them directly to Kard via the Attribution API. User clicks into push notification and opens into app → eventCode=VIEW, medium=PUSH

Note: in addition to eventCode and a medium the API requires an entityId representing the Kard-provided notificationId related to the attribution event and an eventDate capturing the timestamp the event occurred.

POST /v2/issuers/{{organizationId}}/users/{{userId}}/attributions
{
"data": [
{
"type": "notificationAttribution",
"attributes": {
"entityId": "60e4ba1da31c5a22a144c178",
"eventCode": "VIEW",
"medium": "PUSH",
"eventDate": "2025-01-07T00:00:00Z"
}
}
]
}

List Attribution Events

Use List Attribution Events to check which attribution events Kard recorded, for example when a user says they activated an offer and did not get their reward.

GET /v2/issuers/{{organizationId}}/attributions?filter[userId]=user-123&filter[type]=offerAttribution&filter[entityId]=offer-456&filter[eventCode]=ACTIVATE
{
"data": [
{
"type": "offerAttribution",
"id": "0b9a7e1c-6f1e-4c43-9a1e-3c0f2b7d9a11",
"attributes": {
"userId": "user-123",
"entityId": "offer-456",
"eventCode": "ACTIVATE",
"medium": "CTA",
"eventDate": "2026-09-30T14:02:11Z",
"createdAt": "2026-09-30T14:02:13Z"
},
"relationships": {
"user": { "data": { "type": "user", "id": "user-123" } },
"offer": { "data": { "type": "offer", "id": "offer-456" } }
}
}
],
"links": {
"self": "/v2/issuers/{{organizationId}}/attributions?filter[userId]=user-123&filter[type]=offerAttribution&filter[entityId]=offer-456&filter[eventCode]=ACTIVATE&page[size]=10",
"next": "/v2/issuers/{{organizationId}}/attributions?filter[userId]=user-123&filter[type]=offerAttribution&filter[entityId]=offer-456&filter[eventCode]=ACTIVATE&page[size]=10&page[after]=eyJ..."
}
}

An empty data means Kard has no matching record, for example because the activation never reached Kard.

What it returns

The endpoint returns the events Kard uses to match transactions to rewards. It is not a log of every impression, view or click. It includes:

  • Activations and impressions for offers that require them to earn a reward.
  • Every activate and boost sent through the Activate and Boost endpoints, and every placement slot activation.

To receive every impression and view, subscribe to the attributionEventsFile webhook, which delivers your offer and notification attribution events as files. Placement slot activations are not included in the files.

Filters

ParameterDescription
filter[userId]Your user ID.
filter[type]offerAttribution, notificationAttribution or placementSlotAttribution.
filter[entityId]The offer, notification or slot ID, depending on filter[type]. To look up an offer, use it with filter[type]=offerAttribution.
filter[eventCode]IMPRESSION, VIEW, ACTIVATE or BOOST. Repeat it to match several.
filter[medium]BROWSE, EMAIL, MAP, SEARCH, CTA or PUSH. Repeat it to match several.
filter[rank]state.rank, the offer’s position in the list when the event happened.
filter[placementId]state.placementId.
filter[startDate], filter[endDate]ISO 8601 times. Start is inclusive, end is exclusive.

Without filter[userId], filter[startDate] and filter[endDate] are required and can be at most 31 days apart. With filter[userId], the dates are optional.

state is stored only for events recorded after this endpoint launched, so filter[rank] and filter[placementId] match only those events, and only when you sent state.

Pagination and ordering

Results are sorted by eventDate, newest first. page[size] defaults to 10, with a maximum of 100. To page, follow links.next and links.prev, or pass their page[after] and page[before] cursors.

Notes

  • eventDate is the event time you sent. createdAt is when Kard recorded it. Recording is asynchronous, so an event sent through the bulk Attribution API usually appears seconds to minutes after the 202.
  • id is Kard’s attribution ID. It is not the _id in the attribution files.
  • Requires the rewards/attributions.read scope. Results only include your organization’s users.
  • Returns 400 for an invalid filter value, a missing or too-long date window, or page[size] over 100, and 401 for a missing or invalid token or a missing scope.

Best Practices

  • In-app experiences: Use either Image-based tracking or the API for both event types.
  • Push Notification Impressions: Must be sent via the Attribution API.
  • Push Notification Views: Use either Image-based tracking or the API.
  • Use either Image-based tracking or the Attribution API per event type — not both.
  • Avoid caching attribution URLs if you choose to use the Image-based tracking.
  • Send all API-based events promptly for real-time data accuracy.