Skip to main content
Use the catalog when you choose which offers to feature and in what order, on a surface you program yourself. POST /offers/catalog returns the full set of offers a user is eligible for (entitlement and geography already enforced server-side), and you curate client-side. This guide covers only what differs from the shared flow (select, deliver, claim, activate: see the overview, and Rewarded Actions guide for the complete worked example).

​
The curation split

Two hard filters, entitlement and geography, always run on Encore’s side, so any offer you receive is one your app may serve and the end user can redeem. Your curation (which offers to feature, in what order) is a soft filter you apply on top. That split is the whole pattern.
1

Once, at configuration time: pull your inventory

Call POST /offers/catalog with includeAllRegions: true to get your full addressable inventory, each offer with its targetCountries. Pick the offers to feature and save their ids in your own configuration.
Config mode skips the geography filter and returns no clickUrls. It is for planning only; never render offers straight from it to end users.
2

On every render: serve the user

Call with a stable userId and the user’s geography. Encore returns the offers that user is eligible for, each creative carrying a tokenized clickUrl (full contract).
3

Curate client-side

Keep the returned offers whose id is in your featured list, in your preferred order. If none of your picks came back for this user, fall back to the other returned offers so your surface is never empty. Wire each tap to that creative’s clickUrl.
Why filter on your side rather than sending Encore your featured ids? The hard filters can remove some of your picks for a given user (for example, US-only offers for a user in Romania). If the server narrowed to your list, you would be left with nothing to show. Returning the whole eligible set lets you fall back gracefully, and you can never accidentally show an ineligible offer.

​
Gotchas

  • Geography is required on the serve path. Send countryCode in the body, or forward the end user’s IP via X-Forwarded-For. If neither resolves, the call is a 400; Encore never guesses a default country.
  • Per-creative click URLs. The catalog carries one tokenized clickUrl per creative. Route the user to the clickUrl on the exact creative they tapped, treat it as opaque, and never modify or wrap it.
  • Diagnosing a missing pick. If a featured offer is absent from a serve response, compare against your config-time inventory: present there but not here means the user’s country is outside its targetCountries; absent there means your app is not entitled to it.
  • Mixed-platform audiences. Each creative lists supportedPlatforms (ios/android/web); use it to curate each offer to the end user’s surface.