Update product data via API

This guide walks you through uploading product data into a Data hub item collection using the API. Learn how to structure your data as records, create patch operations for updates, send full or incremental changes, and validate results.

Prerequisites

Ensure you have the following:

Knowledge

Understanding of item collection concepts.
Understanding of how the patch mechanism works.

Workspace and organization access

Access to a Bloomreach workspace within your organization.

Item collection

Created an Item collection within your workspace to hold your product data.
Get the collection name (for example, test_collection) from Data hub > Items.
Determine the item type you're working with (typically product for a product catalog).

API access and credentials

Provisioned API key (token name and secret) with permissions to update and view records in Data hub Item collections and view job status. Go to Workspace Settings > Access Management > API > API Groups for these credentials.
Base URL for API calls in your environment.
Workspace ID (a UUID). Note that this is the same as the workspace token.

Steps to get the credentials:

On the product login, click the settings icon next to the workspace.
Go to Workspace settings > Access management > API.
Note the workspace token and the base URL.

Step 1: Structure your product data as a record

A record typically includes:

record ID: a unique identifier for the product (for example, "006").
fields object: product-level fields like price, rating, and reviews.
variants object: optional section if your product has multiple variants (color, size, SKU).

Here's an example representing a product with two variants:

{
  "id": "006",
  "fields": {
    "price": 299.99,
    "rating": 4,
    "reviews": 164
  },
  "variants": {
    "372991_0": {
      "fields": {
        "sku": "120546",
        "sku_price": 299.99
      }
    },
    "372991_1": {
      "fields": {
        "sku": "372991_1",
        "sku_price": 299.99
      }
    }
  }
}

You can include as many fields as needed in the product-level fields object and as many variants under the variants object. Each variant requires a unique variant ID.

Step 2: Convert records to patch operations

To send data into Bloomreach, wrap each record or partial record in a patch operation that describes where (path) and how (op) to apply it.

Operation types

add: Creates a new record or completely overwrites the existing one at that path.

upsert: Partially merges fields if the record already exists. Creates the record if it doesn't exist.

remove: Removes the target product, variant, or field entirely.

Path targets

The path specifies the target location:

"/006" targets the product record with ID "006".
"/006/fields/price" targets the price field of product "006".
"/006/variants/372991_0" targets a specific variant under product "006".

If a product or variant identifier or field name contains a forward slash (/) or tilde (~) character, you must escape them in the path target using ~1 and ~0, respectively.

Value

The value contains the JSON data to apply when adding or upserting.

Example: Adding one product

A minimal patch in JSON or JSONLines format that adds product "006" looks like this:

[
  {
    "op": "add",
    "path": "/006",
    "value": {
      "fields": {
        "price": 299.99,
        "rating": 4,
        "reviews": 164
      },
      "variants": {
        "372991_0": {
          "fields": {
            "sku": "120546",
            "sku_price": 299.99
          }
        },
        "372991_1": {
          "fields": {
            "sku": "372991_1",
            "sku_price": 299.99
          }
        }
      }
    }
  }
]

For bulk loading thousands of products, include one patch operation per product (or per change) in sequence. This often uses JSONLines format, where each line contains one JSON object.

Step 3: Send a full or delta update

Full update

A full update instructs Bloomreach to remove all existing records in the collection before applying your patch. Use this approach for an initial load or a periodic full refresh.

Here's an example curl command:

# Variables/Endpoints
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"

# Perform a FULL update
curl -X POST "${PRODUCT_ENDPOINT}/records?update_mode=full" \
  -H "Content-Type: application/json-patch+jsonlines" \
  -u "${API_TOKEN_NAME}:${API_TOKEN_SECRET}" \
  --data-binary @all_products.jsonl

Command breakdown:

--data-binary @all_products.jsonl references a local file containing one or more patch operations, typically one add operation per product.
Content-Type: application/json-patch+jsonlines signals JSONLines patch data.
?update_mode=full triggers the full replacement logic.

Delta update

When you only want to modify or add a few products, variants, or fields, use a delta update (update_mode=delta). In the patch, you can mix add, upsert, and remove operations as needed.

Example: Upsert fields and remove a variant

This example demonstrates two operations:

Upsert product "013" (adding new fields or merging with existing data).
Remove a specific variant "013-LG-UPS" under that product.

# Delta update
curl -X POST "${PRODUCT_ENDPOINT}/records?update_mode=delta" \
  -H "Content-Type: application/json-patch+jsonlines" \
  -u "${API_TOKEN_NAME}:${API_TOKEN_SECRET}" \
  --data-binary @- <<EOF
{"op":"upsert","path":"/013","value":{"fields":{"keywords":"upserted_val1","subject_upsert":"upserted_val2"},"variants":{"013-SM-UPS":{"fields":{"sku":"1234556-SM-UPS"}},"013-MD-UPS":{"fields":{"sku":"1234556-MD-UPS"}},"013-LG-UPS":{"fields":{"sku":"1234556-LG-UPS"}}}}}
{"op":"remove","path":"/013/variants/013-LG-UPS"}
EOF

Operation breakdown:

First operation: upsert at "/013" merges or creates product "013".
Second operation: remove deletes the path "/013/variants/013-LG-UPS".

Bloomreach responds with a job object. Follow the same pattern described in Step 4 to check the job's status.

Automatic success behaviors (optional)

When updating records, you can optionally specify what happens after a successful update using query parameters:

on_success_trigger=update-items: Transforms your updated records into items immediately. This is typically a good default.

on_success_trigger=update-destination-items: Also syncs the updated items to connected Discovery and Engagement catalogs automatically. This is also a good default.

You might skip these automatic updates if your source system loads data in multiple steps where each step leaves records partially complete, or when you're testing schema changes and don't want to immediately impact connected applications.

Bloomreach responds with a JSON object containing a job identifier:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "item-collections/update-records",
    "state": "PENDING",
    ...
  }
}

Save the id value to track the job's progress.

Step 4: Track the update job status

Data hub Item collections process updates asynchronously. Query the job's status to see if it succeeded, is still running, or encountered errors.

JOB_ID="<the-job-id-from-the-response>"

curl -sX GET "${BASE_URL}/api/cde/v1/workspaces/${WORKSPACE_ID}/jobs/${JOB_ID}" \
  -u "${API_TOKEN_NAME}:${API_TOKEN_SECRET}" \
  | jq .

Check the response for:

"state": "SUCCESS" indicates the job finished successfully.
"state": "FAILED" indicates errors occurred.
"details" provides any error messages.

Next steps

Once your records are in an Item collection, transform them into items via API or UI and, optionally, sync the items to destinations via API or UI.

If your environment is configured for automatic item updates, the data flows from records to items after each successful update job. Otherwise, manually trigger an Update Items job.