Mapping Notation

When payload reshaping is enabled on a pipeline, you use field paths to describe where data comes from in the Shopify payload and where it should appear in the forwarded payload. The notation is based on JSON dot-notation.

Basic Syntax

A path is a dot-separated sequence of property names that describes how to navigate a JSON object.

order.id

The [] suffix on a segment marks that property as an array. It tells ShopVector to iterate over every item in that array.

order.line_items[]

---

Mapping Patterns

Single field to single field

Maps one scalar value to a new top-level (or nested) key.

Input path	Output path
order.id	id

Example

Given this Shopify payload:

{
  "order": {
    "id": 12345,
    "email": "[email protected]"
  }
}

With the mapping order.id → id, the forwarded payload becomes:

{
  "id": 12345
}

---

Array to array

Copies an entire array (each item in full) into a new key.

Input path	Output path
order.line_items[]	lineitems[]

Example

{
  "order": {
    "line_items": [
      { "name": "T-Shirt", "quantity": 2 },
      { "name": "Mug", "quantity": 1 }
    ]
  }
}

With the mapping order.line_items[] → lineitems[]:

{
  "lineitems": [
    { "name": "T-Shirt", "quantity": 2 },
    { "name": "Mug", "quantity": 1 }
  ]
}

---

Property inside an array to a property inside another array

Extracts a single property from each item in an array and places it under a new property name on each corresponding item in the output array.

Input path	Output path
order.line_items[].name	lineitems[].name

Example

{
  "order": {
    "line_items": [
      { "name": "T-Shirt", "quantity": 2 },
      { "name": "Mug", "quantity": 1 }
    ]
  }
}

With the mapping order.line_items[].name → lineitems[].name:

{
  "lineitems": [
    { "name": "T-Shirt" },
    { "name": "Mug" }
  ]
}

The output array has the same number of items as the input array. Each item contains only the mapped property.

---

Property inside an array to a flat array

Collects a single property from every item in an array into a new flat array of scalar values.

Input path	Output path
order.line_items[].name	lineitems_names[]

Example

{
  "order": {
    "line_items": [
      { "name": "T-Shirt", "quantity": 2 },
      { "name": "Mug", "quantity": 1 }
    ]
  }
}

With the mapping order.line_items[].name → lineitems_names[]:

{
  "lineitems_names": ["T-Shirt", "Mug"]
}

The difference from the previous pattern is in the output path: lineitems[].name produces an array of objects, while lineitems_names[] produces an array of values.

---

Combining Multiple Mappings

Multiple mappings are applied together to build a single output payload. Each mapping contributes its output key(s), and the results are merged.

Merging properties into the same output array

When two or more mappings share the same output array name, ShopVector merges them into a single array — each item in the array receives all the mapped properties.

Input	Output
order.line_items[].name	lineitems[].name
order.line_items[].quantity	lineitems[].count

Both mappings target lineitems[], so their properties are combined per item:

{
  "order": {
    "line_items": [
      { "name": "T-Shirt", "quantity": 2 },
      { "name": "Mug", "quantity": 1 }
    ]
  }
}

Produces:

{
  "lineitems": [
    { "name": "T-Shirt", "count": 2 },
    { "name": "Mug", "count": 1 }
  ]
}

The source property quantity is also renamed to count in the process. You can map and rename as many properties from the same source array as you need, and they all land on the same output item.

Mixing array merges with other mappings

You can freely combine array merges with scalar and flat-array mappings in the same pipeline:

Input	Output
order.id	id
order.line_items[].name	lineitems[].name
order.line_items[].quantity	lineitems[].count
order.line_items[].name	lineitems_names[]

Produces:

{
  "id": 12345,
  "lineitems": [
    { "name": "T-Shirt", "count": 2 },
    { "name": "Mug", "count": 1 }
  ],
  "lineitems_names": ["T-Shirt", "Mug"]
}

---

Summary

Pattern	Input example	Output example
Single field	order.id → id	Scalar value at new key
Array	order.line_items[] → lineitems[]	Full array under new key
Array property → object array	order.line_items[].name → lineitems[].name	Array of objects, one property each
Array property → value array	order.line_items[].name → lineitems_names[]	Flat array of scalar values
Merged array properties	order.line_items[].name → lineitems[].name + order.line_items[].quantity → lineitems[].count	Array of objects with multiple properties