Bloomreach

Sync customer profiles and events to Bloomreach Engagement for personalized commerce experiences. Zeotap keeps your Bloomreach customer data in sync with your warehouse, enabling real-time marketing automation and product recommendations.

Prerequisites

• A Bloomreach Engagement account
• A Bloomreach API Key ID and API Secret with private access permissions
• Your Bloomreach project token

Authentication

Bloomreach uses API Key ID + API Secret authentication (private access).

1. In Bloomreach Engagement, go to Project settings > Access management > API
2. Create a new API group with the permissions you need:
   • For customer profiles: enable Customer properties > Set
   • For customer events: enable Events > Set
3. Generate a new API key within the group — this gives you an API Key ID and API Secret
4. Copy both values and paste them into the corresponding fields in Zeotap

Zeotap uses Basic authentication, encoding the API Key ID and API Secret as a base64 credential pair.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Bloomreach does not have a list/segment membership API, so audience sync modes are not supported. Use regular sync modes to update customer properties that can then be used in Bloomreach segments.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Customer Profiles

registered, email, first_name, last_name, phone, city, country, gender, age

Customer Events

registered, timestamp, properties

How It Works

1. Zeotap transforms your warehouse data using the configured field mappings
2. Rows are batched into groups of up to 50 commands per API request (Bloomreach’s batch limit)
3. Each row becomes a command in the Bloomreach batch endpoint:
   • Customer Profiles: customers command with customer_ids and properties
   • Customer Events: customers/events command with customer_ids, event_type, and properties
4. The registered field is used as the primary customer identifier (customer_ids.registered)
5. All other mapped fields are sent as customer properties or event properties
6. Per-command errors are tracked individually — a failed command does not block the rest of the batch

API Endpoint

All data is sent via the Bloomreach batch endpoint:

POST /track/v2/projects/{projectToken}/batch

Payload Format

Customer Profile Update:

{
  "commands": [
    {
      "name": "customers",
      "data": {
        "customer_ids": { "registered": "user@example.com" },
        "properties": { "first_name": "Jane", "last_name": "Doe" }
      }
    }
  ]
}

Customer Event:

{
  "commands": [
    {
      "name": "customers/events",
      "data": {
        "customer_ids": { "registered": "user@example.com" },
        "event_type": "purchase",
        "properties": { "product_id": "SKU-123", "amount": 49.99 },
        "timestamp": 1681484247
      }
    }
  ]
}

Rate Limits

• 6,000 HTTP requests per minute per IP address (100 requests per second)
• 50 commands per batch request
• Each command must be less than 800 KB
• Each property value must be less than 16 KB
• Maximum 255 custom customer properties per project

When rate limits are exceeded, Bloomreach returns HTTP 429. Zeotap automatically retries with exponential backoff.

Best Practices

• Use the registered customer ID consistently across all syncs to avoid duplicate profiles
• For high-volume imports, prefer scheduled syncs over continuous syncs to stay within rate limits
• Keep customer properties under the 255 custom property limit — map only the fields you need
• Use the batch endpoint’s 50-command limit efficiently by syncing in larger batches rather than one row at a time
• For events, always include a timestamp to ensure correct event ordering in Bloomreach

Troubleshooting

Authentication failed

Verify your API Key ID and API Secret are correct. Ensure the API group has the required permissions:

• Customer properties > Set for customer profile syncs
• Events > Set for customer event syncs

Project not found (404)

Double-check your project token. You can find it in Bloomreach under Project settings > Access management > API. The project token is a unique alphanumeric identifier.

Properties not updating

Bloomreach uses the registered customer ID to match profiles. Ensure the registered field is mapped and contains a value that matches your existing customer records. If profiles are being created instead of updated, the registered value may not match.

Rate limit errors (429)

Zeotap retries automatically on 429 errors with exponential backoff. If you consistently hit rate limits, reduce sync frequency or contact Bloomreach to increase your rate limit.

Custom property limit reached

Bloomreach allows a maximum of 255 custom customer properties per project. If you exceed this limit, the API returns HTTP 200 but silently rejects new properties. Review your field mappings and remove unnecessary fields.

Event type not appearing

Ensure the Event Type field in your target settings matches the expected event type name in Bloomreach. Event types are case-sensitive. Check your Bloomreach project’s event definitions to confirm the correct spelling.

Command-level errors in batch

Bloomreach returns HTTP 200 even when individual commands fail. Zeotap parses per-command results and reports failures individually. Check the sync run details for specific error messages per command.