Send Your Data (Product)

❗️

Please ignore the Accept header(Accept: application/json) in the request examples. This is just a quirk of the example module.

After formatting your data, you must deliver it to Bloomreach using one of two methods:

  • Direct API payload: send your catalog data directly via an API payload
  • SFTP file : send your catalog data via a file on SFTP

There are two modes available to update your catalog data:

  • PUT (full): replace the catalog’s data entirely
  • PATCH (delta): make partial updates to the catalog's data

PUT mode

When you PUT products into a catalog, you replace the catalog’s data entirely. In PUT mode, the only operation allowed is ADD and the only scope allowed is PRODUCT so that data loading can be parallelized and optimized for ingestion speed. We recommend sending your data through a SFTP file when using PUT mode.

You don't need to update the full catalog daily using PUT, and we recommend using PATCH mode if you need to make frequent updates (more than once per day). We recommend using PUT mode if you are updating a large part of your catalog data, but you should limit using PUT to once per day. In PUT mode, a configurable percentage of malformed products is allowed.

Before you begin

Before sending your content catalog data to Bloomreach via the Catalog Data Management API, ensure that you have the following:

  • Formatted catalog data - Create your product catalog data according to the Format your Data page.
  • Transfer Key - You need an API key for authentication that is unique to your merchant account. If you do not already have it, speak to your Bloomreach representative.
  • Catalog names - Catalog names used in the Catalog Data Management API endpoints. Use the same value as your domain key in your search API requests.
  • Authentication key - Required header for Catalog Data Management API requests. You should have received this during kickoff.

Endpoints

  • Production: https://api.connect.bloomreach.com/dataconnect/api/v1/
  • Staging: https://api-staging.connect.bloomreach.com/dataconnect/api/v1/

Authentication key

An API key will be provided for each environment in your account. This access key must accompany all API requests as a request header. Example value: merchantname-1066facc-94fb-450e-9f9c-b66d0b155fd2

Steps

For full updates

  1. If sending data through SFTP, upload your catalog data to your Bloomreach SFTP location.
  2. Send the Catalog Data Management PUT API request.
  3. Run the index API.

For delta updates

  1. If sending data through SFTP, upload your catalog data to your Bloomreach SFTP location.
  2. Send the Catalog Data Management PATCH API request.
  3. If the order of data is important, wait for the PATCH job to finish.
  4. Run the index API.

❗️

No malformed items allowed in catalog data

If there are any malformed items in your catalog data, the whole operation will be invalid and no changes will be applied.

Send Data as a file through SFTP

To send your catalog data via a file on SFTP, you must convert all of the patch operations into a file of JSONLines. Each line should only contain one patch operation. In your Catalog Data Management API request body, include the relative path to the file location.

Feed files may be sent uncompressed, or be compressed using gzip. The max size of a single API payload is 5MB.

In the request body, provide the paths to your catalog files as relative paths. For example, if your catalog files are in a folder named "content_en", then the request body should look like the following:

[ 
  "content_en/20200410-090909-products1_staging.jsonl", 
  "content_en/20200410-090909-products2_staging.jsonl" 
]
{"op": "add", "path": "/products/pid-123", "value": {...}} //First product record
{"op": "add", "path": "/products/pid-456", "value": {...}} //Second product record
{"op": "add", "path": "/products/pid-789", "value": {...}} //Third product record, etc.
…

SFTP Endpoints

  • Production: sftp.connect.bloomreach.com (3.82.164.133, port 22)
  • Staging: sftp-staging.connect.bloomreach.com (54.211.108.247, port 22)

Your sftp command should look like the following:

sftp -i ~/path/to/private_key @sftp-staging.connect.bloomreach.com

Provide Bloomreach with public keys that will need access to each environment. More than one can be provided for each environment, and we advise using different public keys for staging and production.

📘

SFTP tips

SFTP directory structure

Any catalog data files should be sent via the SFTP location provided in the SFTP Endpoints section. We suggest organizing catalogs into their own folders to help with debugging. For example, you could create a folder called <catalog_name> and then place files related to that catalog in this folder.

File naming

We suggest naming your catalog data files to include the catalog name, the type of modification (put/full, patch/delta) and a datetime version identifier. This will help with debugging. For example, if your catalog is named <catalog_name>, you could name your file 20200410-090909-<catalog_name>_full.jsonl

Storage length

Files sent to the Bloomreach SFTP are stored for 30 days. Files that are older than 30 days will be automatically deleted and cleared.

Send Data as API payload

To send your catalog data directly via an API payload, you must convert all of the operations into a single JSON Patch, which is an array of catalog records. In your Catalog Data Management API request body, include the catalog records.

The max size of a single API payload is 5MB.

[{
  "op": "add",
  "path": "/products/pid-123",
  "value": {
    "attributes": {
      "title": "Example 123",
      "price": 100,
      "description": "Example product description here",
      "url": "http://www.example.com/example-product-url.html",
      "availability": true
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-456",
  "value": {
    "attributes": {
      "title": "Example 456",
      "tags": ["", ""]
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-789",
  "value": {
    "attributes": {
      "title": "Example 789",
      "category": "Seafood",
      "tags": ["", ""]
    }
  }
},
{
  "op": "add",
  "path": "/products/pid-101112/attributes/availability",
  "value": false
}
]

Job ID

The response contains a job ID that can be used to query for status.

Sample PUT request 


PUThttps://api.connect.bloomreach.com/dataconnect/api/v1/accounts/account_ID/catalogs/catalog_name/products

Replace account ID with your Bloomreach provided account ID.

The catalog name is exactly the same as your domain key in your search API requests, and points to where this information will be stored on the backend represented with catalog name and language key.
Headers
AuthorizationBearer API key

Replace API key with your API key
Content-Type (for Direct API payload)application/json-patch+json
Content-Type (for SFTP)application/json
Body
Direct API payload

(JSON Patch format)
[{
"op": "add",
"path": "/products/pid-123",
"value": {
"attributes": {
"title": "Example 123",
      "price": 100,
      "description": "Example product description here",
      "url": "http://www.example.com/example-product-url.html",
      "availability": true
}
}
},
{
"op": "add",
"path": "/products/pid-456",
"value": {
"attributes": {
"title": "Example 456",
"tags": ["", ""]
}
}
}]
SFTP File

(JSONLines format,
file paths must be relative)
[
"{catalog name}/{catalog1.jsonl}",
"{catalog name}/{catalog2.jsonl}"
]
Response{"jobId":"713aa624-1d7c-4e4a-ac23-6463e48a5fdd"}

Parameters Overview


Language