Skip to main content

Perk collection

A perk collection is a curated, ordered set of perks that renders as one page for your customers. Where a perk is a single deal, a collection is the thing a customer actually sees — the catalog of deals you've chosen and arranged for them.

You decide which perks go in, and in what order; Paylode renders the page. The important part is that membership and ordering live on the server, not in your code. When you add, remove, or re-rank perks in the Paylode app, the live page changes on the next load — no redeploy, no code change on your side.

How it works​

A collection has a stable id (its slug — e.g. spring-rewards), an owner (your client account), and its perks. Perks inside a collection can be arranged two ways, and a collection can use either or both:

  • Loose perks — a flat, ranked list rendered top to bottom.
  • Groups — named, themed sections ("Best gifts for the holidays"), each with its own ranked list of perks. Groups let you break a long page into labelled blocks.

Ranking​

Both perks and groups carry a rank from 1 to 1000. Smaller rank shows first. A perk with rank: 1 leads the list; a group with rank: 1 is the top section. Ranking is how you put your strongest offer where customers see it first — see Choose and rank perks.

Server-side membership​

Because the collection's contents are resolved server-side on every read, the collection is a live surface. A perk that expires, a perk you pull, a re-rank you make in the app — all of it is reflected the next time the page loads. Your integration fetches the collection and renders whatever comes back; it never has to know the collection changed.

How you reach a collection​

A collection is addressable two ways, depending on how you authenticate:

  • By slug, using your API key — for reading collections from your own backend or a custom page.
  • By perk-page domain, using the domain header — how an embedded or hosted perks page resolves its own collection.

Both return the same collection shape.

In the API​

Fetch a full collection — its perks, groups, and owner — with getPerkCollection, addressing it by slug and authenticating with your API key.

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

A trimmed 200 response (perk and group fields cut for brevity):

{
  "id": "spring-rewards",
  "owner": "example-co",
  "groups": [
    {
      "id": "6341c870-c23a-11ec-a6d6-0800200c9a66",
      "name": "Best gifts for spring",
      "rank": 1,
      "perks": [
        { "id": "42", "title": "Get 16 free meals", "rank": 1 }
      ]
    }
  ],
  "perks": [
    { "id": "51", "title": "Free month of streaming", "rank": 1 }
  ]
}

perks holds the collection's loose, ungrouped perks; groups holds the sectioned ones. Both are already in the order you set. For the exhaustive field list, see the getPerkCollection operation in the API reference.