Get started with context data

Use contexts when the same product has different prices or is available in different stores. You keep the product's shared details in one place and send the differences for each store.

In this guide, you'll give a trail running shoe a price of 99.00 in one store and keep its usual price of 120.00 in another. You'll set this up in Data hub, send a small example, and check both prices.

Before you begin

Make sure you have:

• Contexts available in your workspace.

• A test item collection for products that you can edit. A collection is where Data hub keeps your product data.

• A working way to send product data to that collection. Data hub calls this incoming data records. If you haven't set this up, follow Update product data via API first.

Use a test product with the ID P100 for this example. If your test collection already uses that ID, replace it with an unused ID throughout the examples.

Choose what changes between stores

In this example, your products vary by store. That makes store the context and each store ID, such as store_042, a context value. To learn what contexts are and which item types support them, read Contexts.

The product's usual title and price are its base data. A different price for a particular store is context data.

You choose the context name in Settings. The store IDs come from the product data you send later.

Add the store context

Add the context to the product item type of your test collection. Follow the steps to add a context in Set up contexts and use these values:

• Context name: store

• Display name: Store

Use store throughout this example. Add and save the context before sending the example data.

Tell the schema where to find the prices

The Schema tab tells Data hub where to find each product detail in your incoming data. These details are called attributes.

If title or price isn't already listed, use Add attribute and choose the predefined attribute. The predefined price attribute accepts decimal numbers, such as 99.00.

1. On Schema, edit Item identifier mapping, choose Record ID, then select Apply. The /P100 in the example will produce an item with the ID P100.

2. Add or edit the predefined title attribute. Choose Record field and enter title for Field name. Save the mapping.

3. Add or edit the predefined price attribute. Keep Base value enabled, choose Record field, and enter price for Field name.

Then add the store mapping to the price attribute. Follow the steps to map schema attributes in Set up contexts, choose Record field, and enter price for Field name.

This tells Data hub to use a store's price when the record supplies one. When the store has no price in context data, Data hub keeps the base price.

Send the example product

Send this example to your test collection using the Update records endpoint. Add these settings to the request URL:

update_mode=delta&on_success_trigger=update-items

update_mode=delta updates the data you supply without replacing the collection's complete set of records. on_success_trigger=update-items tells Data hub to prepare the saved data for viewing and use in other apps.

Use Content-Type: application/json-patch+json for both JSON examples in this guide.

[
  {
    "op": "upsert",
    "path": "/P100",
    "value": {
      "fields": {
        "title": "Trail running shoe",
        "price": 120.00
      },
      "contexts": {
        "store": {
          "store_042": {
            "fields": {
              "price": 99.00
            }
          },
          "store_017": {}
        }
      }
    }
  }
]

Save the JSON as p100.json, then send it with this command:

# Variables and endpoint
BASE_URL="<BASE_URL>"
WORKSPACE_ID="<YOUR_WORKSPACE_ID>"
API_TOKEN_NAME="<YOUR_TOKEN_NAME>"
API_TOKEN_SECRET="<YOUR_TOKEN_SECRET>"
COLLECTION_NAME="<YOUR_COLLECTION_NAME>"
PRODUCT_ENDPOINT="${BASE_URL}/api/cde/v1/workspaces/${WORKSPACE_ID}/item-collections/${COLLECTION_NAME}/item-types/product"

# Send the example product
curl -X POST "${PRODUCT_ENDPOINT}/records?update_mode=delta&on_success_trigger=update-items" \
  -H "Content-Type: application/json-patch+json" \
  -u "${API_TOKEN_NAME}:${API_TOKEN_SECRET}" \
  --data-binary @p100.json

Data hub responds with a job object. Use its id to track the records update in Jobs or through the jobs API.

The example does three things:

• fields supplies the product's base details.

• store_042 includes the product and gives it a price of 99.00.

• store_017 includes the product without changing its details. The empty {} entry is intentional, so this store uses the base price of 120.00.

A store with no entry doesn't include this product. An empty entry and a missing entry have different meanings.

The word upsert means to add the product if it doesn't exist, or update the supplied data if it does.

Check the product prices

Data hub first saves your incoming records, then builds the items that you can view and send to other apps.

1. Open Jobs and wait for the records update to finish successfully.

2. Wait for the items update started by your request to finish successfully.

3. Open Products (shown as Product items in some collections). Search for P100 using Search by item ID....

4. Open the item and use the Context selector to check the following results.

For more ways to check records and items, see Set up contexts.

If the result is different:

Try changing one store's price

Send this second update to change the price in store_042 to 94.00. Use the same request settings: update_mode=delta&on_success_trigger=update-items.

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

Wait for the records update and items update to finish. Open P100 again and select store_042. Its price should now be 94.00. Base data and store_017 should still show 120.00.

Use context data in Search or Marketing

You have added a store context, sent a product with store-specific prices, and changed one store's price.

When you're ready to use these prices in Search or Marketing, send the items through your existing connection. Each app must request the store's version of the product. For how context data reaches each app, see Contexts. To connect destinations, see Set up contexts.

After the app has finished updating, check P100 for store_042 there. Its price should be 94.00.

For variants, exclusions, and more ways to update store data, see Send context data in records.