Skip to main content

Custom attribute

Carry your own identifiers — a user id, a plan tier, a placement name — all the way through a perk click to the conversion it produces, so your reports speak your language instead of Paylode's.

A custom attribute is a key-value pair you attach to a tracking or click URL. Paylode passes it through the redemption flow and hands it back to you on the resulting conversion. If you tag a link with your internal user_id, every conversion from that link comes back stamped with that user_id — no separate lookup, no guessing which of your users converted.

There are two families of attributes, and they behave slightly differently:

  • utm_ parameters — the five standard UTM fields (utm_source, utm_medium, utm_campaign, utm_term, utm_content). These pass straight through and come back exactly as named.
  • cmeta_ parameters — your own custom metadata. You send them with a cmeta_ prefix so Paylode knows to carry them; on the way back the prefix is stripped. Send cmeta_user_id, read user_id.

How it works​

You add the parameters to the URL you hand to Paylode — the click/tracking URL behind a perk, or the attributes you forward through an embedded perks page (see cmeta for perk pages). Paylode records them against the click, follows them through to the purchase, and returns them in the attribution array on the conversion.

Naming and format rules​

Keep attribute names and values within these bounds so nothing is dropped or mangled:

RuleDetail
Name charactersLetters, digits, hyphen (-), and underscore (_) only.
cmeta_ prefixRequired on the way in; removed on the way back.
utm_ setThe five standard UTM keys, passed through unchanged.
Value lengthKeep values to 255 characters or fewer.
EncodingURL-encode values — anything with spaces, &, or = must be escaped.

Here's a click URL carrying one UTM field and two custom attributes. The custom ones use the cmeta_ prefix:

https://example.com/redeem?utm_source=dashboard&cmeta_user_id=42931&cmeta_plan=pro

When a customer who clicks that link converts, the conversion comes back with:

"attribution": [
  { "key": "utm_source", "value": "dashboard" },
  { "key": "user_id", "value": "42931" },
  { "key": "plan", "value": "pro" }
]

Note the cmeta_ prefix is gone (cmeta_user_id → user_id) while utm_source is untouched. Design your keys so the stripped name is the one you want to see in your reports.

Reading them back​

Custom attributes surface wherever you read conversions. See Query your metrics for reading them in your metrics queries, and the conversion concept for the full record shape. The exact fields live in the API reference on developers.paylode.com.