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

# Offers API

> New endpoint page for the widget offers feed, sourced from the client-facing HTML reference.

[← Back to API Integration](/integration/api-integration)

Requires an API key — see [Authentication](/integration/api-integration/authentication).

## Get widget offers feed

<span className="text-xs font-mono font-semibold bg-[#07C983]/15 text-[#15803D] dark:bg-[#07C983]/20 dark:text-[#07C983] px-2 py-1 rounded">GET</span> `https://tyviso.com/gap/api?preview=[true/false]&flow=[category]`

Returns the full payload used to render your hosted Rewards page or widget: the header template, CTA styling, social-proof configuration, and the live offers for each placement (`hero`, `popular`, `all`).

<Info>
  This is a separate path from the tracking API — it's not a tracking request.
</Info>

<Warning>
  **Discrepancy in the source material:** the endpoint is documented at `tyviso.com/gap/api`, but the reference example below calls `tyviso.com/dev/gap/api`. We haven't been able to confirm which is correct — check with your Tyviso Technical Lead before relying on either in production, and use whichever URL your account manager confirms.
</Warning>

**Parameters**

<ParamField query="flow" type="string">
  Category of offers to return.
</ParamField>

<ParamField query="preview" type="string">
  `true` or `false` — preview unpublished offers before they go live.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --get "https://tyviso.com/dev/gap/api" \
    -d "preview=false" \
    -d "flow=category" \
    --header "X-API-Key: $KEY" \
    --header "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL("https://tyviso.com/dev/gap/api");
  url.search = new URLSearchParams({ preview: "false", flow: "category" });
  const res = await fetch(url, { headers: { "X-API-Key": KEY } });
  const feed = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "headerTemplate": 2,
    "settings": {
      "ctaLabel": "Claim now",
      "ctaColor": "#FFFFFF",
      "ctaBg": "#4AAEAB",
      "headerBg": "#FFFFFF",
      "headerTextColor": "#000000",
      "sectionTitles": [],
      "socialProof": {
        "enabled": false,
        "socialCta": { "62de5497af4834865468d308": "0 Claimed" },
        "stickers": {},
        "dynamicSocials": false,
        "position": "on_image",
        "displayMode": "exact",
        "showValue": 0,
        "fallbackText": "New"
      }
    },
    "lastcached": 1785844280818,
    "hero": [],
    "popular": [],
    "all": [
      {
        "id": "62de5497af4834865468d308",
        "partner": "Jimmy's Iced Coffee",
        "partnerLogo": "https://…/logo-400x200.png",
        "category": { "name": "Property", "parent": "Finance & Insurance" },
        "ageRestricted": false,
        "terms": "https://…",
        "url": "https://…",
        "title": "Get 25% Off Your First Order @ Jimmy's Iced Coffee",
        "description": "At Jimmy's we know how to make Iced Coffee. Get 25% Off Original, Mocha, Oat & Extra Shot Iced Coffee with free UK delivery.",
        "image": "https://…/image.jpg",
        "offerInfoButtonDiscount": "25% Off",
        "offerInfoButtonDescription": "Refreshing Iced Coffee Delivery Service. Recyclable packaging & free next day delivery. 25% Off code TY-COFFEE25 applied automatically at checkout",
        "offerInfoButtonCta": "LimitedTimeOffer",
        "offerDiscountCode": "TY-COFFEE25",
        "offerDiscountCodeType": "availableAtCheckout",
        "hasMultipleCodes": false,
        "cta": "Claim now",
        "expiry": null
      }
    ],
    "testOffers": []
  }
  ```
</ResponseExample>

<Expandable title="Response fields">
  <ResponseField name="headerTemplate" type="integer">
    Numeric ID of the header layout your widget is using.
  </ResponseField>

  <ResponseField name="settings" type="object">
    CTA copy/colours, header styling, and `socialProof` display rules — render these directly, don't hardcode your own.
  </ResponseField>

  <ResponseField name="hero / popular / all" type="object[]">
    Arrays of [Offer objects](/integration/api-integration/core-objects) for each placement. `all` is your full catalogue; `hero` / `popular` may be empty if unset for your account.
  </ResponseField>

  <ResponseField name="lastcached" type="integer">
    Commission share and the epoch ms this feed was last cached.
  </ResponseField>
</Expandable>

See [Errors](/integration/api-integration/errors) for error shapes.