Skip to main content

Perk

A perk is the single deal you put in front of a customer — a discount, a free trial, a bundled freebie. It's the atomic unit of value in Paylode: everything else in the platform (collections, perks centers, Boost incentives) is a way of grouping, ranking, and rendering perks.

Think of one perk as one offer a customer can act on: "20% off your first order", "a free month of the app", "free shipping this week". You choose which perks to show, and Paylode gives you everything needed to render them — the copy, the imagery, the categories, and a Redeem link that takes the customer to the offer and records the click along the way. You never build the redemption plumbing yourself; you decide what to show and where.

How it works​

Every perk carries the same core fields, whatever the offer:

  • title — what the perk is, in the customer's words. "Get 16 free meals."
  • description — a longer, customer-facing explanation. "Delicious meals delivered to your door."
  • callout — the short value flag you'd put on a badge. "up to 70% off."
  • redemption_note — how the customer actually claims it. "Use code SAVE20" or "Discount applied automatically at checkout."
  • details — the fine print: terms, eligibility, expiry conditions.
  • click_url — the link behind your Redeem button (see below).
  • offer_slug — a stable text id for the perk, handy as a key when you sync perks into your own system.

A perk also carries relations you can use to lay it out: media (banner and logo imagery), categories (for filtering), locations (where the offer is redeemable), and the partner brand behind it.

The Redeem-button contract​

Whatever the perk type, the rule is the same: put click_url behind your Redeem button. That single link does two jobs — it records the view/click for your reporting and then forwards the customer to the live offer. Don't try to reconstruct a destination yourself or strip parameters from the link; use it verbatim. If tracking ever hiccups, the link still redirects the customer, so a click never dead-ends.

Three ways a customer redeems​

One perk model, three redemption shapes. Which one you're looking at is readable from the fields:

Perk typeHow the customer redeemsHow to detect it
Automatically appliedNothing to enter — the discount lands at checkout.No coupon, and is_coupon_perk is absent/false. redemption_note says it's automatic.
Static couponOne shared code everyone uses.coupon field carries the code ("SAVE20"). Reusable, so show it inline.
Single-use codeEach customer gets their own one-time code.is_coupon_perk is true. There's no shared coupon — you request a code per customer when they redeem.

The single-use case is the only one that needs an extra call: you allocate a fresh code on demand rather than displaying a shared one. That flow — and the "what happens when the code pool runs low" behavior — is its own concept; see Coupon and the guide Coupon.

In the API​

Fetch a single perk from one of your collections with getPerkOfCollection. Authenticate with your API key.

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

A trimmed 200 response (fields removed for brevity):

{
  "id": "42",
  "title": "Get 16 free meals",
  "description": "Delicious meals that are easy to make, delivered to your door",
  "callout": "up to 70% off",
  "redemption_note": "Discount applied automatically at checkout",
  "click_url": "https://link.paylode.com/?upid=fja0f111gatda-sf",
  "offer_slug": "sixteen-free-meals",
  "rank": 1,
  "is_coupon_perk": false,
  "relations": {
    "partner": { "id": "0888n3nn", "name": "Bloom & Co." },
    "categories": [{ "id": 1, "name": "Food & Drink", "slug": "food-drink" }]
  }
}

To read a perk's live redemption details you always go through a collection the perk belongs to — a perk id on its own isn't addressable. See Perk collection for how collections are shaped, and the getPerkOfCollection operation in the API reference for the full field list.