Skip to main content

Short-term perk

A short-term perk is a deal with a clock on it — a limited-time offer you surface as "ends today" or "this week only" to create urgency. It's a perk variant built for an "expiring soon" section: same idea as a regular perk, but with an end date and an expiry hint that tells the customer how little time is left.

Like local perks, short-term perks are enabled per collection. If you want a collection to show an expiring-soon section, your Paylode contact turns it on for that collection — we'll help you set it up.

How it works​

Each short-term perk carries the familiar perk fields — title, description, category, and a click_url for the Redeem link — plus three that make it time-aware:

  • end_date — when the offer expires, as a Unix timestamp.
  • expiry_hint — a plain-language urgency flag you can render as a badge: ENDS_TODAY, ENDS_TOMORROW, or ENDS_THIS_WEEK.
  • type — the kind of deal, one of COUPON, PRODUCT, FREE_SHIPPING, SALE, or SEASONAL — useful for iconography or grouping.

Prefer expiry_hint for what you show the customer (it reads well on a badge) and end_date when you need the exact moment — for a countdown, or to hide a perk your own cache is holding past its expiry.

note

A collection's expiring-soon section returns a small default number of perks. If you're fetching short-term perks through the API and want more (or fewer), pass the limit query parameter on getShortTermPerks rather than relying on the default staying put.

Keeping the section on-brand​

Short-term perks are sourced for you, so the exact deals rotate. You control what fits your audience with per-collection keyword include and exclude lists — see the short-term-perks operations in the API reference.

In the API​

Fetch a collection's short-term perks with getShortTermPerks. Pass the collection and authenticate with your API key.

curl "https://perk-collections.paylode.com/short-term-perks?collection=spring-rewards" \
  -H "X-API-Key: sk_example_0000000000000000"

A trimmed 200 response:

{
  "short_term_perks": [
    {
      "id": "bde22b26-6c21-11e8-a0ab-52540a1457f9",
      "title": "48-hour free shipping",
      "description": "Free shipping on every order through Sunday",
      "category": "Retail",
      "type": "FREE_SHIPPING",
      "end_date": 1693484993,
      "expiry_hint": "ENDS_THIS_WEEK",
      "click_url": "https://link.paylode.com/?upid=fja0f111gatda-sf",
      "rank": 1
    }
  ],
  "limit": 8,
  "offset": 0
}

For the full field list and parameters, see getShortTermPerks in the API reference.