Skip to main content

Sync perks to a CMS

Keep the perks in your own content system — a headless CMS, a database, a static site generator — up to date with Paylode, without editing them by hand.

If your site renders content from a CMS rather than calling APIs at request time, you'll want your perks to live there too. This guide pulls a collection on a schedule and upserts each perk into your CMS by its stable id, so adds, edits, and removals in Paylode flow through automatically. It's a background job, not a customer-facing request — which changes one thing about how you call the API (see step 3).

How it works​

You run a job on a schedule — a cron entry, a CI job, a scheduled function. Each run fetches the full collection, then for every perk:

  • upserts it into your CMS keyed on the perk id (create if new, update if changed), and
  • removes or deactivates any CMS record whose perk id is no longer in the collection.

Because you key on the perk id, re-running the job is safe — it converges to whatever the collection currently holds.

Before you begin​

  • Your API key. Sent as the X-API-Key header. See Authentication.
  • Your collection id.
  • A runtime that runs on a schedule. Cron, a CI pipeline, or a scheduled serverless function all work — the job is a single GET plus your CMS writes.

Steps​

1. Fetch the collection​

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

2. Map each perk to your CMS model​

Pull the display fields onto your CMS record. Store the click_url as-is — it's the Redeem link and must be used verbatim (don't wrap it):

{
  "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.",
  "coupon": "PAYLODE20",
  "click_url": "https://link.paylode.com/?upid=sample-opaque-ref",
  "metadata": "Food Tasty Cook"
}
caution

metadata is a string, not an object. It's free-text used for on-page search (keywords describing the perk) — store it as a plain string. Treating it as JSON will throw.

3. Suppress view tracking on sync jobs​

A perk read normally counts as a customer viewing that perk. A sync job isn't a customer, so tell Paylode not to record the view by sending X-Disable-View-Tracking: true (shown in step 1). Skip this and your background job will inflate your perk-view metrics.

4. Upsert and prune​

For each perk in the response, upsert into your CMS keyed on id. Then delete or deactivate any CMS record whose id wasn't in this run's response — that's how removals propagate.

Once you're live​

Pick a cadence that matches how often your perks change — hourly or daily is typical. Each run reconciles your CMS to the live collection, so a missed run self-heals on the next one.

Worked example​

A daily Node job that syncs a collection into a CMS:

async function sync() {
  const res = await fetch(
    "https://perk-collections.paylode.com/perk-collections/example-rewards",
    {
      headers: {
        "X-API-Key": "sk_example_0000000000",
        "X-Disable-View-Tracking": "true",
      },
    }
  );
  const { perks, groups } = await res.json();

  // perks[] is flat; groups[] carries display order if you need it
  const seen = new Set();
  for (const perk of perks) {
    await cms.upsert("perk", perk.id, {
      title: perk.title,
      callout: perk.callout,
      description: perk.description,
      note: perk.redemption_note,
      code: perk.coupon ?? null,
      redeemHref: perk.click_url,
      search: perk.metadata ?? "",   // string, not an object
    });
    seen.add(perk.id);
  }

  await cms.deactivateMissing("perk", seen);
}

Troubleshooting​

note

If your perk-view numbers jump on the schedule your job runs, you've forgotten X-Disable-View-Tracking: true. Add it to the sync request — leave it off only on real customer-facing reads.

Reference​

This guide uses the getPerkCollection operation. See the perk-collection operations in the API Reference.