Metafield reference

Warning! This feature is not publicly available yet. Reach out to support to get early access.

Origin writes attribution data back onto each Shopify order as app-owned metafields. This document describes every metafield and the exact structure of its JSON value.

In the tables below, strings default to "" (empty string) rather than being omitted, unless noted otherwise.

Overview

Key	Value shape	Description
`attribution_first_touch`	`Record<string, AttributionTouchObject>`	First-touch attribution result keyed by attribution window.
`attribution_last_touch`	`Record<string, AttributionTouchObject>`	Last-touch attribution result keyed by attribution window.
`attribution_linear`	`Record<string, AttributionTouchObject[]>`	Linear attribution result (list of touches) keyed by attribution window.

The values of the three attribution_* metafields are objects where the key is the attribution window in days. Possible keys are "1", "7", "14", "30", "90", "180", "365". Which keys appear in the object depends on the store's plan allowance.

Definition

`attribution_first_touch`

First-touch attribution per attribution window. The earliest touch in each window receives full credit.

Top-level object — keys are attribution windows in days

Key	Type	Description
`"1"`, `"7"`, `"14"`, `"30"`, `"90"`, `"180"`, `"365"`	`AttributionTouchObject` or `null`	First-touch result for the given window.

(see AttributionTouchObject).

Example

{
  "1": {
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "spring_sale",
    "utm_content": "carousel_a",
    "utm_term": "",
    "landing_page": "https://shop.com/products/widget",
    "touch_ts": "2026-05-01T12:30:00.000Z",
    "credit": 1,
    "attributed_revenue": 100,
    "ad_platform_key": "facebook",
    "ad_external_id": "1203912093",
    "ad_campaign_external_id": ""
  },
  "7": {
    // ...
  },
  "14": {
    // ...
  },
  "30": {
    // ...
  }
}

`attribution_last_touch`

Last-touch attribution per attribution window. The most recent (converting) touch in each window receives full credit. Identical structure to attribution_first_touch.

Top-level object — keys are attribution windows in days

Key	Type	Description
`"1"`, `"7"`, `"14"`, `"30"`, `"90"`, `"180"`, `"365"`	`AttributionTouchObject` or `null`	Last-touch result for the given window.

(see AttributionTouchObject).

`attribution_linear`

Linear attribution per attribution window. Every touch in the window shares the credit evenly (1 / number_of_touches).

Top-level object — keys are attribution windows in days

Key	Type	Description
`"1"`, `"7"`, `"14"`, `"30"`, `"90"`, `"180"`, `"365"`	`AttributionTouchObject[]`	All touches in the window (oldest first), each with its share of the credit. Present only when the plan includes the window and the order has at least one touch inside it.

(see AttributionTouchObject).

Example

{
  "1": [
    {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "spring_sale",
      "utm_content": "carousel_a",
      "utm_term": "",
      "landing_page": "https://shop.com/products/widget",
      "touch_ts": "2026-05-01T12:30:00.000Z",
      "credit": 0.5,
      "attributed_revenue": 50,
      "ad_platform_key": "facebook",
      "ad_external_id": "1203912093",
      "ad_campaign_external_id": ""
    },
    {
      "utm_source": "google",
      "utm_medium": "organic",
      "utm_campaign": "",
      "utm_content": "",
      "utm_term": "",
      "landing_page": "https://shop.com/",
      "touch_ts": "2026-05-03T09:10:00.000Z",
      "credit": 0.5,
      "attributed_revenue": 50,
      "ad_platform_key": "",
      "ad_external_id": "",
      "ad_campaign_external_id": ""
    }
  ],
  "7": [
    // ...
  ],
  "14": [
    // ...
  ],
  "30": [
    // ...
  ]
}

`AttributionTouchObject`

Used by attribution_first_touch, attribution_last_touch, and attribution_linear. Every key is always present, empty strings are used when the value is not present.

Field	Type	Description
`utm_source`	`string`	UTM source of the touch. `""` if none.
`utm_medium`	`string`	UTM medium of the touch. `""` if none.
`utm_campaign`	`string`	UTM campaign of the touch. `""` if none.
`utm_content`	`string`	UTM content of the touch. `""` if none.
`utm_term`	`string`	UTM term of the touch. `""` if none.
`landing_page`	`string`	Landing-page URL of the originating session. `""` if unknown.
`touch_ts`	`string`	When the touch occurred (ISO 8601 datetime, UTC), e.g. `2026-05-18T09:10:00.000Z`.
`credit`	`number`	Fraction of the order credited to this touch under the model. `1` for first-touch and last-touch; `1 / number_of_touches` for each linear touch.
`attributed_revenue`	`number`	Revenue credited to this touch, in the store's currency. Equals `credit * order total`.
`ad_platform_key`	`string`	Ad platform of the linked ad/campaign (e.g. `"meta"`, `"google"`). `""` if the touch is not linked to an ad or campaign.
`ad_external_id`	`string`	The ad platform's own ad id, when the touch is linked to a specific ad. `""` otherwise.
`ad_campaign_external_id`	`string`	The ad platform's own campaign id, when the touch is linked to a campaign but not a specific ad. `""` otherwise.

Notes on the ad fields

A touch is only attributed to ads or ad campaigns when tracking parameters have been correctly configured.
The ad takes priority over the campaign: when a touch is linked to a specific ad, ad_external_id is populated and ad_campaign_external_id is left empty (""). When it is linked only to a campaign, ad_campaign_external_id is populated and ad_external_id is left empty ("").
ad_platform_key is populated whenever either ID is present.

Updated on: 26/05/2026

Was this article helpful?

Thank you!