> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Curated Catalog

> Choose which premium brand offers to feature, and in what order, on a surface you program yourself.

Use the catalog when **you** choose which offers to feature and in what order, on a surface you program yourself. [`POST /offers/catalog`](/publishers/offers-api/reference/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](/publishers/offers-api/overview#the-flow), and [Rewarded Actions guide](/publishers/offers-api/guides/rewarded-actions) 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.

<Steps>
  <Step title="Once, at configuration time: pull your inventory">
    Call [`POST /offers/catalog`](/publishers/offers-api/reference/catalog) with `includeAllRegions: true` to get your full addressable inventory, each offer with its `targetCountries`. Pick the offers to feature and save their `id`s in your own configuration.

    ```bash theme={null}
    curl -X POST https://api.encorekit.com/encore/publisher/sdk/v1/offers/catalog \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "includeAllRegions": true }'
    ```

    <Warning>
      Config mode skips the geography filter and returns no `clickUrl`s. It is for planning only; never render offers straight from it to end users.
    </Warning>
  </Step>

  <Step title="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](/publishers/offers-api/reference/catalog)).

    ```bash theme={null}
    curl -X POST https://api.encorekit.com/encore/publisher/sdk/v1/offers/catalog \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "userId": "user-8b3f7c10", "countryCode": "US" }'
    ```
  </Step>

  <Step title="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`.
  </Step>
</Steps>

**Why filter on your side rather than sending Encore your featured `id`s?** 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.

## Related

* [`POST /offers/catalog` reference](/publishers/offers-api/reference/catalog): full request/response contract and status codes.
* [API Reference overview](/publishers/offers-api/overview#choosing-a-selection-mode): the selection-mode decision table.
* [Rewarded Actions guide](/publishers/offers-api/guides/rewarded-actions): the flagship worked example of the shared flow.