Custom Mapping is the power-user way to shape events for a destination. Author a JSON pipeline of rename, transform, and conditional steps that runs on top of the destination's system default.

Why both Custom Mapping and Custom Attributes exist

Most destinations need only a small change: forward two or three extra ep.* event params alongside the standard fields. Custom Attributes is the fast path for that case. Type the attribute names as chips, hit Save, done.

Custom Mapping is the power path. Reach for it when you need to rename a field, nest values into a structured object, condition a value on another field, transform values (uppercase, hash, date format), or map an event name to a different value per destination. The two fields are not redundant. They run in a defined order at runtime: system default first, then your Custom Mapping, then Custom Attributes passthrough.

Open the destination and find the panel

Go to Echo > Destinations and click the destination you want to customize. Scroll past Event Filter and Custom Attributes to the Custom Mapping panel. It is collapsed by default and auto-expands when an existing customer mapping is present, so you always see what is currently in effect.

Read the system default first

The right column of the panel shows the destination type's read-only system default mapping. Today, system defaults exist for Lens, Meta, Microsoft Ads (UET), Floodlight, Snapchat, and Reddit. GA4, TikTok, Google Ads, Pinterest, and LinkedIn do not have a system default yet, so anything you author runs as-is.

Reading the system default tells you two things: what fields are already populated for you (so you don't have to repeat them), and what destination paths are claimed (so you know your customer step won't override them silently). The merge is system-wins on collision, by design, to keep the destination's required payload shape correct.

Author the JSON in the editor

The CodeMirror editor on the left of the panel is where you write your mapping. Click Insert Example to start from a known-good template, then edit. Use Format to pretty-print the JSON and Clear to reset the editor. The panel runs live JSON validation as you type, so syntax errors are flagged before you can save.

A minimal mapping is just a list of transforms:

{`{
  "transforms": [
    {
      "type": "event_name_map",
      "config": {
        "source": "event_name",
        "destination": "type",
        "map": {
          "purchase": "ecommerce",
          "lead": "forms",
          "view_item": "engagement"
        }
      }
    }
  ]
}`}

Save and the rule rewrites instantly

Click Save on the destination. The destination's EventBridge rule rewrites with the new mapping inline. New events flowing through Echo pick up the new shape immediately, so there is no propagation delay or cache to wait on.

One caveat: there is an 8 KB cap on the inline mapping that ships into the EventBridge rule. Very large mappings are rejected at save time. Use the simple_map shorthand to keep the mapping compact, or split logic across two destinations if you genuinely need that much.

Available transform types

simple_map (rename a source field to a destination field), rename (alias), template (string interpolation), value_map (lookup-based value substitution), event_name_map (map event_name to a per-destination value), condition (only run if a predicate is true), nest (move flat fields into a structured object), lookup (table-based remap). The system reference column shows the destination's defaults and which transforms it uses.

Worked example: Floodlight one-destination-per-advertiser

Floodlight is the canonical case for Custom Mapping. The architecture is one Echo Floodlight destination per DCM advertiser, not per activity tag. To route many events through that single destination to different DCM activities, you map event_name to both type and cat in your customer mapping.

{`{
  "transforms": [
    { "type": "event_name_map", "config": {
        "source": "event_name", "destination": "type",
        "map": { "purchase": "ecommerce", "lead": "forms", "view_item": "engagement" } } },
    { "type": "event_name_map", "config": {
        "source": "event_name", "destination": "cat",
        "map": { "purchase": "completed", "lead": "submitted", "view_item": "pdp" } } }
  ]
}`}

One destination, N activities, no extra plumbing. The destination's Event Filter still controls which events flow in at all.

Worked example: Microsoft Ads action override

The MS Ads UET destination uses event_name as the action by default (so an Echo purchase event becomes UET event action purchase). If your MS Ads conversion goal expects a different action name, add an event_name_map in your Custom Mapping to translate.

{`{
  "transforms": [
    { "type": "event_name_map", "config": {
        "source": "event_name", "destination": "ea",
        "map": { "submit_lead": "lead_submission", "purchase": "order_placed" } } }
  ]
}`}

Troubleshooting

The save button is disabled

Live validation found a JSON syntax error. Look for the inline error indicator in the CodeMirror gutter. Common causes: trailing comma after the last array element, missing closing brace, unescaped quote inside a string value.

I added a transform but the destination ignored it

Check the system reference column on the right. If the destination path you targeted is already claimed by the system default, the merge dropped your step (system wins on collision, logged silently). Pick a different destination path or add your data as a nested field that doesn't clash.

Save fails with "mapping too large"

You hit the 8 KB EventBridge inline-template cap. Use simple_map shorthand to compact verbose rename chains, or split the destination into two destinations with different filters.

Custom Mapping