POST /offers/feed

Returns the bandit-ranked eligible offers for one user, up to limit, so you can render them in your own UI and cycle through them. Each offer carries its own impressionUid and a branded short clickUrl.

POST https://api.encorekit.com/encore/publisher/sdk/v1/offers/feed

Calling this endpoint is not the impression. When you actually display an offer, confirm it with POST /offers/impressions/{impressionUid}/delivered. For the scenario walkthrough (render, confirm, route the tap), see the Rewarded Actions guide; to fetch your full curated inventory instead of a ranked selection, see POST /offers/catalog.

Authentication

Pass your publishable key in the X-API-Key header (pk_live_* for production, pk_test_* for development). Multi-app projects also send X-Platform: api (requires an API-platform app in the project; without one the response is 401 Invalid API key). A test key returns the demo catalog rather than your inventory, and records no impressions, clicks, or conversions from it. The full model, including the API platform app type, is in the overview’s Authentication section.

Request

Structure

interface OffersFeedRequest {
  clientId: string;              // required: stable per-operator identifier
  userId: string;                // required: stable end-user identifier
  limit?: number;                // 1-25, default 10
  attributes: {
    countryCode: string;         // required: ISO 3166-1 alpha-2, two uppercase letters
    language: string;            // required: BCP-47 language tag
    platform?: 'android' | 'ios' | 'web';  // the END USER's device platform; never 'api'
  };
  placementId?: string;          // optional: which surface this feed is rendered in
}

Field Reference

Field	Type	Required	Description
`clientId`	string	Yes	Stable per-operator identifier: the business, account, or operator the offers are rendered on behalf of. Carried through as an analytics dimension so impressions, clicks, and conversions can be broken down per client.
`userId`	string	Yes	End-user identifier on your surface. Seeds bandit ranking and is the userId on the transaction created at click time, plus the userId dimension on the click event. It is also the analytics identity on the impression event, so it determines the Unique Users figure on your dashboard. Keep it stable per user.
`limit`	integer	No	How many offers to return. Range `1` to `25`, default `10`. You control display order and cycle through them. Fewer may be returned when fewer eligible offers exist.
`attributes.countryCode`	string	Yes	ISO 3166-1 alpha-2, two uppercase letters (for example `"US"`, `"GB"`, `"CA"`). Drives geo-targeting and the country dimension on analytics.
`attributes.language`	string	Yes	BCP-47 language tag (for example `"en"`, `"es"`). Drives creative locale resolution.
`attributes.platform`	string	No	The end user’s device platform: `"android"`, `"ios"`, or `"web"`. Optional for API-platform apps: omit it to receive all entitled, geo-eligible offers; send it to narrow the feed to creatives that support that surface. Never send `"api"` here.
`placementId`	string	No	Label for the surface this feed is rendered in (for example `"cancel_flow"`, `"home_feed"`, `"post_purchase"`). Stamped onto every impression in the response and onto the click it produces, so your dashboard can break the funnel out by placement. Normalised server-side: trimmed, blank treated as absent, truncated to 64 characters. Omit it and this traffic groups under `(unlabeled)`. See Splitting your funnel by placement.

Attributes you stored earlier fill the gaps. If you have sent this userId a set with POST /users/attributes, any attribute this request omits is filled from it, and a stored age narrows the offers a user under 18 may be shown. Anything in this request’s own attributes always wins. countryCode and language stay required here regardless: the request is rejected before the stored set is read, so storing them does not make them optional.

API-platform apps receive every eligible offer by default. An app created with platform API gets all entitled, geo-eligible offers with no per-platform trimming, which is ideal when you serve a mixed-platform audience from your own server. To narrow a single request to one surface, send that end user’s device platform in attributes.platform.

Response

Structure

interface OffersFeedResponse {
  success: true;
  offers: Array<{
    impressionUid: string;              // per-offer impression handle (UUID)
    clickUrl: string;                   // branded short link on link.encorekit.com
    campaignId: string;                 // stable offer id (UUID); join key for completions
    title: string;                      // offer headline
    description: string | null;         // short supporting line
    imageUrl: string;                   // wide banner creative (~2.4:1)
    additionalImages: string[];         // extra image URLs; may be empty
    advertiserName: string;             // advertiser / brand name
    advertiserLogo: string | null;      // roughly square logo URL
    perk?: string | null;               // campaign value proposition
    badgeLabel: 'free_trial' | 'discount' | null;  // constrained promo badge
    isDemo?: true;                      // present only on a demo offer
  }>;
}

Field Reference

Field	Type	Description
`success`	`true`	Always `true` on a 200. Non-success outcomes come back as 4xx/5xx; see Status codes.
`offers`	array	A ranked list of offers, best first. Empty array when no eligible offers were found for this user (geo-targeted out, no active campaigns, all creatives filtered by platform). Never a 404.
`offers[].impressionUid`	UUID	Per-offer impression handle. Use it to confirm the impression when you display this offer via `POST /offers/impressions/{impressionUid}/delivered`. Not end-user-visible.
`offers[].clickUrl`	URL	Branded short link on the fixed host `link.encorekit.com`. Open it when the user taps this offer: it 302-redirects to the advertiser with attribution and registers the click/claim. End-user-visible. Always wire the tap to it.
`offers[].campaignId`	UUID	Stable identifier for the offer. The `offer_completed` webhook sends the same value as its `campaignId`, so this is how you match a completion back to the offer you displayed. Unchanged across renders, locales, and creative rotation. Not end-user-visible.
`offers[].title`	string	Headline of the offer. Use as the lead line in your UI. Display text, not an identifier: it comes from the creative, so it varies between creatives of the same offer and is translated when you request another language. Never key off it.
`offers[].description`	string \| `null`	Short supporting line about the offer (for example `"Limited time offer"`). May be `null`.
`offers[].imageUrl`	URL	Wide banner creative. Render it as the offer’s hero image; see Image fields.
`offers[].additionalImages`	array of URL	Extra image URLs for this offer; ratio not guaranteed. May be empty. Render ratio-agnostic.
`offers[].advertiserName`	string	The advertiser / brand name (for example `"Acme"`).
`offers[].advertiserLogo`	URL \| `null`	The advertiser’s logo image URL (roughly square), or `null` when the advertiser has no logo set.
`offers[].perk`	string \| `null`	The campaign value proposition (for example `"3 months free"`), or `null`. May also be absent from the object.
`offers[].badgeLabel`	`"free_trial"` \| `"discount"` \| `null`	Constrained promo badge for the offer card, or `null` when the campaign has none. Map the enum to your own display text. Distinct from `perk` (the longer value proposition).
`offers[].isDemo`	`true` \| absent	Present and `true` only when this is a demo offer, which a `pk_test_` key is served instead of your inventory. Absent* on ordinary inventory here, though `/offers/search` serializes it as `false`, so test for truthiness rather than for a specific absent-or-false shape. Surface it as a demo rather than presenting it as real, and treat its presence in a production build as a sign the wrong key shipped. See what a test key serves.

Beyond impressionUid and campaignId, the response carries no internal identifiers. Creative ids and request ids are not returned; they are still computed server-side for analytics.

Image fields

Field	Aspect ratio	Nullable	How to render
`advertiserLogo`	~1:1 (square), not strictly enforced	Yes	Render in a 1:1 frame with `object-fit: contain`; handle `null` by hiding the mark or falling back to `advertiserName`.
`imageUrl`	~2.4:1 wide banner (NOT 16:9)	No	Design the slot for ~2.4:1, or use `object-fit: cover`.
`additionalImages[]`	Not guaranteed	Array may be empty	Render ratio-agnostic (`object-fit: contain` in a flexible frame).

imageUrl is a wide ~2.4:1 banner, not 16:9. A 16:9 slot will crop or letterbox it.

Example

# X-Platform is only needed for multi-app projects; single-app keys can omit it.
curl --location --request POST 'https://api.encorekit.com/encore/publisher/sdk/v1/offers/feed' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Platform: api' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "client-42",
    "userId": "user-8b3f7c10",
    "limit": 10,
    "attributes": {
      "countryCode": "US",
      "language": "en",
      "platform": "ios"
    }
  }'

{
  "success": true,
  "offers": [
    {
      "impressionUid": "550e8400-e29b-41d4-a716-446655440000",
      "clickUrl": "https://link.encorekit.com/Xa3kPq7T",
      "campaignId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Get 50% Off",
      "description": "Limited time offer",
      "imageUrl": "https://cdn.example.com/banner.png",
      "additionalImages": ["https://cdn.example.com/img2.png"],
      "advertiserName": "Acme",
      "advertiserLogo": "https://cdn.example.com/acme-logo.png",
      "perk": "3 months free",
      "badgeLabel": "discount"
    }
  ]
}

Status codes

Code	Meaning
`200`	Success. `offers` may be an empty array if no eligible offers.
`400`	Malformed request (missing required field, invalid `attributes.countryCode`, `limit` out of range). Don’t retry; fix the request.
`401`	Missing or invalid `X-API-Key`.
`409`	The client has exceeded their trial limit (rare).
`429`	Rate-limited. Back off and retry.
`503`	Server temporarily over capacity. Retry with backoff.
`5xx` (other)	Encore-side failure. Render nothing and proceed without offers.

Retry guidance

Retries are not deduplicated server-side. Every /offers/feed call generates fresh short links and analytics rows, so only fetch a feed once per placement you intend to render.
Use exponential backoff with jitter (for example 200ms, 1s, 5s, max 3 retries) for transient failures (429 / 503 / network).
After exhausting retries, render nothing. The end-user experience should never degrade because of an Encore outage.

POST /offers/impressions/{impressionUid}/delivered: confirm each offer’s impression when it is displayed.
Rewarded Actions guide: the full fetch, render, confirm, click pattern.
POST /offers/catalog: full eligible inventory for curated surfaces.
API Reference overview: auth, the impression model, and feed vs catalog.

​Authentication

​Request

​Structure

​Field Reference

​Response

​Structure

​Field Reference

​Image fields

​Example

​Status codes

​Retry guidance

​Related

Authentication

Request

Structure

Field Reference

Response

Structure

Field Reference

Image fields

Example

Status codes

Retry guidance

Related