Build a custom perk page

Render your perks yourself — your markup, your layout, your framework — while Paylode stays the source of truth for the perks and their redemption links.

The embed and hosted page give you a ready-made perks page. A custom integration trades that convenience for full control: you call the Perk Collections API, get the perks as JSON, and build the page exactly the way you want it. You own the rendering; Paylode owns the data and the redemption. Choose this path when the embed's look or placement can't fit your product, or when you're composing perks into a larger custom surface.

How it works

A collection is the set of perks you've chosen, arranged into ranked groups. You fetch the whole collection in one call, then render its perks. Each perk carries everything the customer needs to see — a title, a callout, a description, a redemption note — plus a click_url that backs the "Redeem" button.

There are three kinds of perk, and they differ only in how the customer redeems:

Perk type	What the customer does	How you tell
Automatically applied	Clicks Redeem; the discount is applied on arrival	No coupon, is_coupon_perk is absent/false. The redemption_note explains it's automatic.
Static coupon	Copies a code that everyone shares, then clicks Redeem	coupon holds the code (e.g. PAYLODE20).
Single-use code	Requests their own one-time code, then clicks Redeem	is_coupon_perk is true; there's no coupon field — you allocate one on demand.

The one contract that never changes: the click_url is the Redeem button. Whatever the perk type, point the button at click_url as-is. It records the view and redirects the customer to the right destination. Don't parse it, rewrite it, or build your own redirect.

Before you begin

• Your API key. Sent as the X-API-Key header. See Authentication.
• Your collection id. The id of the collection you want to render.

Steps

1. Fetch the collection

curl https://perk-collections.paylode.com/perk-collections/example-rewards \
  -H "X-API-Key: sk_example_0000000000"

const res = await fetch(
  "https://perk-collections.paylode.com/perk-collections/example-rewards",
  { headers: { "X-API-Key": "sk_example_0000000000" } }
);
const collection = await res.json();

A trimmed response (the real body includes more fields; these are the ones you render):

{
  "id": "example-rewards",
  "owner": "example-co",
  "groups": [
    {
      "id": "6341c870-c23a-11ec-a6d6-0800200c9a66",
      "name": "Food & Drink",
      "rank": 1,
      "perks": [
        {
          "id": "42",
          "title": "Get 16 free meals",
          "callout": "up to 70% off",
          "description": "Meals that are easy to make, delivered to your door.",
          "redemption_note": "Applied automatically at checkout.",
          "rank": 1,
          "click_url": "https://link.paylode.com/?upid=sample-opaque-ref"
        }
      ]
    }
  ],
  "perks": []
}

Perks arrive both inside groups (arranged for display) and flat in perks. Render from groups when you want the client's chosen layout; use the flat perks array when you're building your own arrangement. Within a group, lower rank shows first — sort ascending.

2. Render each perk

Map the fields straight onto your UI:

• title — the headline ("Get 16 free meals").
• callout — the short value line ("up to 70% off").
• description — the body copy.
• redemption_note — how to redeem ("Use code PAYLODE20" or "Applied automatically at checkout").
• coupon — present only on static-coupon perks; show it as a copyable code.
• click_url — the href for your Redeem button.

<a class="redeem" href="https://link.paylode.com/?upid=sample-opaque-ref">
  Redeem
</a>

3. Fetch a single perk when you need one

For a detail page or a lazy-loaded card, fetch one perk from the collection:

curl https://perk-collections.paylode.com/perk-collections/example-rewards/perk/42 \
  -H "X-API-Key: sk_example_0000000000"

The shape matches a perk inside the collection, including a fresh click_url.

4. Filter what you fetch

getPerkCollection takes query parameters so you can fetch a focused slice instead of filtering client-side:

Parameter	Effect	Example
categories	Only perks in the given category ids	?categories=1&categories=4
location_country / location_region / location_city	Only perks eligible in that location	?location_country=usa
show_coupon_perks	Include single-use coupon perks (default false)	?show_coupon_perks=true

To learn which categories a collection actually contains, call getPerkCollectionCategories:

curl "https://perk-collections.paylode.com/perk-collections/example-rewards/categories" \
  -H "X-API-Key: sk_example_0000000000"

[
  { "id": 1, "name": "Food & Drink", "slug": "food-drink" },
  { "id": 4, "name": "Health & Wellness", "slug": "health-wellness" }
]

Each category carries a slug alongside its id — a stable text id that never changes, even if the category is later renamed. Use it the way you'd use offer_slug on a perk: as a key when you wire categories into your own markup, routing, or configuration. The name is the display label (and is localized when you request another language), so keep filtering and keys on id or slug, never on the name.

5. (Optional) Use a perk's Universal URL for off-page channels

If you also want to feature one of your perks outside the page you're building — a campaign email, a push notification, a banner — you don't need another API call. Open the perk in the admin app's Marketplace: alongside your earnings for the perk, it shows your account-specific Universal URL where one is available — a tracking-ready link you can drop into any channel. See the Perks Marketplace overview. Your API integration always renders from the collection (getPerkCollection) and uses each perk's click_url verbatim.

Troubleshooting

caution

Never build your own redirect around click_url. It carries the tracking that credits your conversions; wrapping or rewriting it breaks attribution. Use it verbatim as the Redeem button's href.

note

Single-use coupon perks (is_coupon_perk: true) have no coupon field in the collection — that's expected. You mint each customer's code at redemption time; see Coupon.

Worked example

Render a collection into grouped sections, ranked, with the right Redeem link on every perk:

const res = await fetch(
  "https://perk-collections.paylode.com/perk-collections/example-rewards?show_coupon_perks=true",
  { headers: { "X-API-Key": "sk_example_0000000000" } }
);
const { groups } = await res.json();

for (const group of groups.sort((a, b) => a.rank - b.rank)) {
  renderHeading(group.name);
  for (const perk of group.perks.sort((a, b) => a.rank - b.rank)) {
    renderCard({
      title: perk.title,
      callout: perk.callout,
      note: perk.redemption_note,
      code: perk.coupon,            // present only on static-coupon perks
      redeemHref: perk.click_url,   // always the Redeem button's href
    });
  }
}

Reference

• getPerkCollection, getPerkOfCollection, getPerkCollectionCategories — the Perk Collections operations behind this page.

See them in the API Reference.

Related

• Perk Pages overview — what the product does and how this page fits it.