Send context data in records

Context data goes in your records alongside base data. You send it with the same Update records endpoint, patch operations, and modes as for base data. Imports don't support context data. To learn how contexts work and how Data hub builds items from context data, see Contexts.

A root item is the top-level item in a record, and its variants sit under it. For now, root items are product items.

Prerequisites

• A context. Use its context name as the key under contexts, such as store. To add a context and check the requirements for context names and values, follow Set up contexts.

Where context data lives in a record

Context data sits next to fields and variants in a contexts object, keyed by context name and then by context value. Each entry has the same shape as base data:

• fields: the root item's fields for that context value.

• variants: one entry for each variant that differs for that context value. Each entry can hold fields and exclude.

<rootId>
├── fields
├── variants
│   └── <variantId>
│       └── fields
└── contexts
    └── <contextName>
        └── <contextValue>
            ├── fields
            └── variants
                └── <variantId>
                    ├── fields
                    └── exclude

Data hub takes membership and values only from contexts, not from base record fields or custom expressions.

Include only the variants that differ. When exclude is true, the variant is hidden only for that context value.

For how an entry sets membership and how variants take their values, see Contexts. For what happens to variant entries with no variant record, and to removed records, see Set up contexts.

How context data reaches items

Context data reaches items through mappings in the schema. To map your context fields, follow Set up contexts. To learn how Data hub builds items from mapped values, see Contexts.

Example record

[
  {
    "op": "add",
    "path": "/P100",
    "value": {
      "fields": {
        "title": "Trail running shoe",
        "price": 120.00
      },
      "variants": {
        "P100-S": {
          "fields": {
            "size": "S"
          }
        },
        "P100-M": {
          "fields": {
            "size": "M"
          }
        },
        "P100-L": {
          "fields": {
            "size": "L"
          }
        }
      },
      "contexts": {
        "store": {
          "store_042": {
            "fields": {
              "price": 99.00,
              "inventory_level": "in_stock"
            },
            "variants": {
              "P100-M": {
                "fields": {
                  "inventory_level": "low_stock"
                }
              },
              "P100-L": {
                "exclude": true
              }
            }
          },
          "store_017": {}
        }
      }
    }
  }
]

If price and inventory_level have context mappings, then in store_042, the price is 99.00, size M is low_stock, and size L is hidden. In store_017, the root item appears with its base data. Any other store doesn't include it.

Patch paths

In the paths, <rootId> is the root item identifier and <variantId> is the variant identifier.

You can use add, upsert, and remove on every path. add creates or replaces, upsert creates or merges, and remove removes.

Field paths can go deeper, as for base data. For example, /P100/contexts/store/store_042/fields/pricing/amount sets one property, and …/variants/P100-M/fields/pickup_slots/- appends to an array. These operations change only the saved context data. They don't copy base values into it.

Context values can contain / and ~. In a patch path, write / as ~1 and ~ as ~0. For example, /P100/contexts/store/store~1us~0west targets store/us~west. For other requirements for context values, see Set up contexts.

Common tasks

Add a root item to a context value with no context data:

[
  {
    "op": "upsert",
    "path": "/P100/contexts/store/store_105",
    "value": {}
  }
]

Change one store's price. Fields you leave out keep their values, and the entry is created if it doesn't exist:

[
  {
    "op": "upsert",
    "path": "/P100/contexts/store/store_042/fields",
    "value": {
      "price": 94.00
    }
  }
]

Keep a root item in a store but drop its context data:

[
  {
    "op": "add",
    "path": "/P100/contexts/store/store_042",
    "value": {}
  }
]

Remove a root item from one store, or from every store:

[
  {
    "op": "remove",
    "path": "/P100/contexts/store/store_017"
  }
]

[
  {
    "op": "remove",
    "path": "/P100/contexts"
  }
]

Hide a variant in one store. You don't need an empty variants object first:

[
  {
    "op": "upsert",
    "path": "/P100/contexts/store/store_017/variants/P100-L",
    "value": {
      "exclude": true
    }
  }
]

To show it again, remove exclude. Setting exclude to false has the same effect.

Full mode and delta mode

• Full mode: Send every record with all of its entries, including empty ones. At the end of the records update, Data hub removes context data and memberships that the patch doesn't include.

• Delta mode: Context data that the patch doesn't include stays as it is. An add on a whole record replaces the whole record, including contexts, so the root item leaves every context value that the operation leaves out. To keep other context data, use upsert or a deeper path.

A change to context data rebuilds the root item and its variants in the next items update.

Best practices

• Target the smallest path that covers your change.

For best practices on the data you send, see Set up contexts.

Related articles

• Contexts

• Patch format and delivery

• Set up contexts