Placements

Overview

Kard’s placements, content strategy, and marketing delivery functionality give you control over where and when offers appear, so the right users see the right loyalty opportunities at the right times. Every placement is configurable: you choose the medium it delivers on, the schedule it follows, and the offers it surfaces by linking a content strategy.

By pairing configurable placements with reusable content strategies, you can personalize the offer experience across in-app, push, and email from a single setup. This guide walks you through how placements work, the mediums they support, how content strategies select offers, and how to send offer notifications on a recurring cadence or on demand for one-time sends.

Setting up follows three steps:

1. Create a content strategy: define which offers to show and how to rank them.
2. Create a placement: choose where and how offers are delivered, and link the content strategy to it.
3. Send notifications: reach users directly with a recurring push or a one-time on-demand push or email.

Content Strategies

A content strategy defines which offers to show and how to order them — independent of medium or timing, so one strategy can be reused everywhere. You create and manage strategies through the Content Strategies API.

Create a strategy

1
{
2
  "data": {
3
    "type": "contentStrategy",
4
    "attributes": {
5
      "name": "Featured Gas Offers",
6
      "sort": "HIGHEST_CASHBACK",
7
      "categories": ["Gas"]
8
    }
9
  }
10
}

The response returns 201 with the new strategy, including the id you’ll reference when creating a placement:

1
{
2
  "type": "contentStrategy",
3
  "id": "01961e5a-b74c-7d42-8456-d3a1f2c90e71",
4
  "attributes": {
5
    "name": "Featured Gas Offers",
6
    "organizationId": "org-123",
7
    "sort": "HIGHEST_CASHBACK",
8
    "categories": ["Gas"],
9
    "categoryExclusions": [],
10
    "merchantExclusions": []
11
  }
12
}

Link that id to any placement through contentStrategyId. Updating the strategy changes every placement that uses it — no per-channel rework.

Placements

Placements are the building blocks for delivering offers, and a placement’s type decides how and where offers reach the user:

• placement: renders offers inside your app, holding multiple offers via availableSlots.
• placementPushNotification: sends a single offer as a push notification on a recurring schedule.
• placementEmail: sends offers as an email on a recurring schedule, filling up to availableSlots offers per send.
• placementOnDemand: sends a one-time push or email, outside of any schedule.

The first three are created once and link to a content strategy through a contentStrategyId — Kard selects and surfaces the offers, and any update to the strategy flows through automatically. On-demand sends are fired as you need them, reusing a placement’s strategy or a set of offers you specify. The sections below walk through each.

Create a placement

Create a placement through the Placements API, setting type to the kind you want to create. This example creates an in-app main-page placement with five slots, linked to the content strategy created above:

1
{
2
  "data": {
3
    "type": "placement",
4
    "attributes": {
5
      "name": "Featured Gas Offers",
6
      "availableSlots": 5,
7
      "contentStrategyId": "01961e5a-b74c-7d42-8456-d3a1f2c90e71"
8
    }
9
  }
10
}

Mediums

Mediums are configured as part of your placements, and the same content strategy can power offers across all three:

• In-app: a placement renders offers when the user opens the screen. It’s evaluated at request time, so no schedule is needed — to display it, call Get Placement Content for the user, and Kard returns the offers the placement’s content strategy selects as standardOffer resources (up to availableSlots), ready to render.
• Push: offers are sent to the user’s device as a notification (see Placement notifications).
• Email: offers are sent on a recurring cadence (a placementEmail) or as a one-time on-demand send.

Curating the in-app placement

Get Placement Content is how you curate the in-app placement experience. When a user opens the screen, call the endpoint with their userId and the placementId, and Kard resolves the linked content strategy in real time — handing back the offers already selected and ranked for that user. Render them exactly as they arrive; there’s no client-side filtering or sorting to do. Pass supportedComponents to shape which UI components come back.

$
GET /v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content?include=categories

A standard (in-app) placement returns offers — render these in the order returned, up to the placement’s availableSlots:

1
{
2
  "data": [
3
    {
4
      "type": "standardOffer",
5
      "id": "5e27318c9b346f00087fbb5c",
6
      "attributes": {
7
        "name": "World's Greatest Chicken",
8
        "terms": "Offer valid at US locations only.",
9
        "purchaseChannel": ["INSTORE"],
10
        "userReward": { "type": "PERCENT", "value": 5.7 },
11
        "startDate": "2024-11-17T05:00:00Z",
12
        "expirationDate": "2025-03-17T05:00:00Z",
13
        "isTargeted": true,
14
        "assets": [
15
          { "type": "IMG_VIEW", "url": "https://attribution.getkard.com/logos/wgc_logo.png?token=example", "alt": "" }
16
        ],
17
        "websiteUrl": "https://worldsgreatestchicken.test.com",
18
        "description": "Crispy, double-fried spicy chicken."
19
      },
20
      "relationships": {
21
        "category": { "data": [ { "type": "category", "id": "65920081b524d126068de24a" } ] }
22
      }
23
    }
24
  ],
25
  "included": [
26
    { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } }
27
  ],
28
  "links": {
29
    "self": "/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content",
30
    "prev": null,
31
    "next": null
32
  },
33
  "meta": {
34
    "placementName": "Homepage Banner",
35
    "availableCategories": [
36
      { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } }
37
    ]
38
  }
39
}

The data array holds the offers to display, included carries the referenced categories (when requested), and meta.placementName echoes the placement’s display name. Because selection and ranking happen server-side from the content strategy, updating that strategy re-curates the in-app placement automatically — no client changes needed.

Placement Notifications

Placements can also reach users as notifications, over push or email. These come in two forms: recurring sends on a cadence, and one-time on-demand sends.

Cadence notifications

A placementPushNotification delivers a single offer to the user on the recurring schedule you define. Its availableSlots is fixed at 1, so the linked content strategy picks the most relevant offer for each run. You set the schedule with a cadence object:

Create type placementPushNotification through the Placements API. This example sends a daily offer at 09:00 UTC:

1
{
2
  "data": {
3
    "type": "placementPushNotification",
4
    "attributes": {
5
      "name": "Daily Gas Offers",
6
      "cadence": { "frequency": "DAILY", "timeOfDay": "09:00" },
7
      "contentStrategyId": "01961e5a-b74c-7d42-8456-d3a1f2c90e71"
8
    }
9
  }
10
}

For a weekly send, set frequency to WEEKLY and add a dayOfWeek — for example, { "frequency": "WEEKLY", "timeOfDay": "14:00", "dayOfWeek": "FRI" }.

Email on a cadence

Email placements follow the same schedule model. Create a placementEmail with a cadence and an availableSlots count — unlike push (fixed at one offer), an email send can feature several offers, so the linked content strategy fills up to availableSlots:

1
{
2
  "data": {
3
    "type": "placementEmail",
4
    "attributes": {
5
      "name": "Weekly Deals Email",
6
      "availableSlots": 10,
7
      "cadence": { "frequency": "WEEKLY", "timeOfDay": "10:00", "dayOfWeek": "MON" },
8
      "contentStrategyId": "01961e5a-b74c-7d42-8456-d3a1f2c90e71"
9
    }
10
  }
11
}

Receiving the content file

Kard selects the offers for a scheduled send, but you deliver the message to your users. On each run, Kard resolves the linked content strategy, compiles the selected offers into a gzipped JSONL file, and notifies you through your notification webhook.

The handoff has three steps:

1. Subscribe once. Register a webhook for the event with the Create Subscriptions endpoint. Use pushNotificationPlacementFile for push placements and emailNotificationPlacementFile for email placements.
2. The cadence fires. At the scheduled time, Kard builds the file and POSTs a notification to your subscribed webhookUrl.
3. Download and send. The payload carries a presigned downloadUrl; GET it before it expires to retrieve the gzipped JSONL, then deliver the offers to your users.

Subscribe to the push placement-file event:

1
{
2
  "data": [
3
    {
4
      "type": "subscription",
5
      "attributes": {
6
        "eventName": "pushNotificationPlacementFile",
7
        "webhookUrl": "https://your-domain.com/webhooks/kard",
8
        "enabled": true
9
      }
10
    }
11
  ]
12
}

When the cadence runs, Kard delivers a webhook payload like the one below (push shown; email uses emailNotificationPlacementFile):

1
{
2
  "data": {
3
    "id": "669e3823-1688-4d6e-b46e-cf1999d4a25d",
4
    "type": "pushNotificationPlacementFile",
5
    "attributes": {
6
      "placementName": "Top gas cashback",
7
      "availableSlots": 3,
8
      "cadence": "WEEKLY",
9
      "downloadUrl": "https://example.com/placements/669e3823-1688-4d6e-b46e-cf1999d4a25d.jsonl.gz"
10
    },
11
    "relationships": {
12
      "placement": { "data": { "type": "placement", "id": "669e3823-1688-4d6e-b46e-cf1999d4a25d" } },
13
      "contentStrategy": { "data": { "type": "contentStrategy", "id": "8df56d4f-0dbf-47ab-b081-0c6534dddd34" } }
14
    }
15
  }
16
}

Email placement files

An email placement (placementEmail) hands off its file the same way, on the event emailNotificationPlacementFile — subscribe to it just as you would the push event. Because an email send isn’t capped at a single offer, availableSlots tells you how many offers the file holds.

1
{
2
  "data": {
3
    "id": "0192a1b2-c3d4-7e8f-9012-3456789abc01",
4
    "type": "emailNotificationPlacementFile",
5
    "attributes": {
6
      "name": "Monthly Top Cashback Email",
7
      "availableSlots": 3,
8
      "cadence": "MONTHLY",
9
      "downloadUrl": "https://example.com/placements/0192a1b2-c3d4-7e8f-9012-3456789abc01.jsonl.gz"
10
    },
11
    "relationships": {
12
      "placement": { "data": { "type": "placement", "id": "0192a1b2-c3d4-7e8f-9012-aaaa5678cccc" } },
13
      "contentStrategy": { "data": { "type": "contentStrategy", "id": "8df56d4f-0dbf-47ab-b081-0c6534dddd34" } }
14
    }
15
  }
16
}

The downloadUrl resolves to the same gzipped JSONL format as the push file (one record per eligible user). Download it before it expires, decompress, and render the offers into your email template. The field reference below applies to both the push and email payloads.

Inside the content file

The downloadUrl points to a gzipped JSONL file: decompress it, then parse one line per eligible user — not one line per offer. Each line is a self-contained JSON:API data envelope whose id is the placement the content was generated for. Push and email use different record types.

Push — each line is a pushNotificationPlacementContent record. The content strategy’s top offer is already resolved into the title, message, and a per-user attributionUrl, so you deliver the line as-is.

Two records follow, one per user — id, title, and message are placement-level (identical across users), while userId and attributionUrl are per-user. The bodies are expanded below for readability; in the file each record is written as a single line.

1
{
2
  "data": {
3
    "type": "pushNotificationPlacementContent",
4
    "id": "669e3823-1688-4d6e-b46e-cf1999d4a25d",
5
    "attributes": {
6
      "userId": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
7
      "title": "Top Gas cashback",
8
      "message": "Explore Gas offers with our highest cashback rates.",
9
      "attributionUrl": "https://attribution.getkard.com/p/eyJhbGciOiJIUzI1NiJ9.aaa..."
10
    }
11
  }
12
}
13
...
14
{
15
  "data": {
16
    "type": "pushNotificationPlacementContent",
17
    "id": "669e3823-1688-4d6e-b46e-cf1999d4a25d",
18
    "attributes": {
19
      "userId": "7c2e9a10-4b3d-4f88-91a2-6de0f1c3b5a4",
20
      "title": "Top Gas cashback",
21
      "message": "Explore Gas offers with our highest cashback rates.",
22
      "attributionUrl": "https://attribution.getkard.com/p/eyJhbGciOiJIUzI1NiJ9.bbb..."
23
    }
24
  }
25
}

Email — each line is an emailNotificationPlacementContent record. Because an email send can feature several offers, the attributes carry an offers array (up to availableSlots) plus a single per-user attributionToken; append that token to each offer’s img URL when you render it.

Two records follow, one per user — id, title, and message are placement-level, while userId, attributionToken, and the offers array are per-user (each user gets the offers they’re eligible for, up to availableSlots). The bodies are expanded below for readability; in the file each record is written as a single line.

1
{
2
  "data": {
3
    "type": "emailNotificationPlacementContent",
4
    "id": "0192a1b2-c3d4-7e8f-9012-aaaa5678cccc",
5
    "attributes": {
6
      "userId": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
7
      "title": "Top Gas cashback",
8
      "message": "Explore Gas offers with our highest cashback rates.",
9
      "attributionToken": "eyJhbGciOiJIUzI1NiJ9.aaa...",
10
      "offers": [
11
        {
12
          "id": "629fc220b7a4290009a188ec",
13
          "name": "Shell",
14
          "reward": "5% cash back",
15
          "img": "https://cdn.getkard.com/offers/629fc220b7a4290009a188ec.png"
16
        },
17
        {
18
          "id": "629fc220b7a4290009a188ff",
19
          "name": "Chevron",
20
          "reward": "3% cash back",
21
          "img": "https://cdn.getkard.com/offers/629fc220b7a4290009a188ff.png"
22
        }
23
      ]
24
    }
25
  }
26
}
27
...
28
{
29
  "data": {
30
    "type": "emailNotificationPlacementContent",
31
    "id": "0192a1b2-c3d4-7e8f-9012-aaaa5678cccc",
32
    "attributes": {
33
      "userId": "7c2e9a10-4b3d-4f88-91a2-6de0f1c3b5a4",
34
      "title": "Top Gas cashback",
35
      "message": "Explore Gas offers with our highest cashback rates.",
36
      "attributionToken": "eyJhbGciOiJIUzI1NiJ9.bbb...",
37
      "offers": [
38
        {
39
          "id": "629fc220b7a4290009a188ec",
40
          "name": "Shell",
41
          "reward": "5% cash back",
42
          "img": "https://cdn.getkard.com/offers/629fc220b7a4290009a188ec.png"
43
        }
44
      ]
45
    }
46
  }
47
}

See the Attributions guide for how to track engagement on the links and tokens these records carry.

One-time sends (on-demand)

When you need to reach users outside of a schedule, fire a one-time, on-demand send. Set the medium to push or email, and pin the audience with exactly one of placementId (to reuse an existing placement’s strategy) or offerIds (to feature a specific set of offers).

1
{
2
  "data": {
3
    "type": "placementOnDemand",
4
    "attributes": {
5
      "medium": "email",
6
      "offerIds": ["629fc220b7a4290009a188ec"]
7
    }
8
  }
9
}

The request returns 202 with a queued status, and the send is processed asynchronously.

Receiving the on-demand file

On-demand fires hand off the content file exactly like cadence sends. Once the queued job finishes building the file, Kard posts a notification to your subscribed webhook — pushNotificationPlacementFile when medium is push, emailNotificationPlacementFile when it’s email — carrying the presigned downloadUrl for the gzipped JSONL. Subscribe and consume the payload exactly as described in Receiving the content file above.

The file itself uses the same per-user JSONL records documented in Inside the content file — pushNotificationPlacementContent or emailNotificationPlacementContent, one line per eligible user. What fills those records depends on how you fired the send:

• By placementId: the send reuses that placement’s content strategy, availableSlots, and derived copy, so the file matches the placement’s cadence send — records carry the placement’s id, and title/message come from the strategy’s sort and categories.
• By offerIds: availableSlots equals the number of offers you pinned and the copy falls back to the default template.

A pinned-offer (offerIds) email send — like the on-demand request above — produces records like this:

1
{
2
  "data": {
3
    "type": "emailNotificationPlacementContent",
4
    "id": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
5
    "attributes": {
6
      "userId": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
7
      "title": "Earn 5% at Shell",
8
      "message": "Explore this offer and discover more ways to earn cash back.",
9
      "attributionToken": "eyJhbGciOiJIUzI1NiJ9.aaa...",
10
      "offers": [
11
        {
12
          "id": "629fc220b7a4290009a188ec",
13
          "name": "Shell",
14
          "reward": "5% cash back",
15
          "img": "https://cdn.getkard.com/offers/629fc220b7a4290009a188ec.png"
16
        }
17
      ]
18
    }
19
  }
20
}

Firing the same pinned offer with medium: "push" produces a pushNotificationPlacementContent record instead — same default copy, with the offer resolved into a per-user attributionUrl:

1
{
2
  "data": {
3
    "type": "pushNotificationPlacementContent",
4
    "id": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
5
    "attributes": {
6
      "userId": "b3f1c2a4-9d80-4e21-8a77-2c1f5e6d0a9b",
7
      "title": "Earn 5% at Shell",
8
      "message": "Explore this offer and discover more ways to earn cash back.",
9
      "attributionUrl": "https://attribution.getkard.com/p/eyJhbGciOiJIUzI1NiJ9.aaa..."
10
    }
11
  }
12
}