Bluecore

Sync customer data and events to Bluecore for personalized retail marketing campaigns. Zeotap sends customer profiles, purchase events, and behavioral signals to Bluecore’s Events API, enabling AI-driven email, site, and paid media personalization.

Prerequisites

• A Bluecore account with API access enabled
• A Bluecore API key (contact Bluecore support at support@bluecore.com if you do not have one)
• Your Bluecore namespace (also called token) — this identifies your Bluecore account

Authentication

Bluecore uses API Key authentication.

1. Contact your Bluecore account representative or email support@bluecore.com to request an API key
2. Once you receive the key, paste it into the API Key field in Zeotap
3. Enter your Bluecore Namespace in the configuration section

Configuration

Target Settings

Available Event Types

Supported Operations

Sync Modes

Audience Sync Modes

Bluecore does not have a list or segment membership API. Audiences are managed through Bluecore’s Audience Builder based on ingested events and customer attributes.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

email, first_name, last_name, phone, city, state, zip, country, gender, birthday

All customer attributes sent to Bluecore must be lowercase and use underscores instead of spaces or dashes (e.g., first_name, not First-Name). Zeotap automatically lowercases attribute names.

How It Works

Customer Patch (Profile Sync)

1. Zeotap maps each row to a Bluecore customer_patch event
2. Customer attributes are nested under a customer object in the event payload
3. Each event is sent individually to the Bluecore Events API (POST https://api.bluecore.app/api/track/mobile/v1)
4. Bluecore creates or updates the customer profile based on the email address

Commerce Events (Purchase, Viewed Product, etc.)

1. Zeotap maps each row to the selected commerce event type
2. Product fields (product_id, price, quantity, name) are nested under a products array
3. Purchase events include order_id and total at the properties level
4. Each event is sent individually to the Bluecore Events API

Event Payload Format

All events follow Bluecore’s standard format:

{
  "event": "customer_patch",
  "properties": {
    "token": "your-namespace",
    "distinct_id": "customer@example.com",
    "customer": {
      "email": "customer@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}

Error Handling

• Zeotap automatically retries failed requests up to 3 times with exponential backoff
• HTTP 429 (rate limit) responses are retried automatically
• Failed rows are reported individually with error details in the sync log

Rate Limits

Bluecore’s Events API does not publish explicit rate limits. Zeotap sends events individually with automatic retry and backoff to avoid overwhelming the API.

If you experience rate limiting (HTTP 429 responses), consider:

• Reducing the frequency of your sync schedule
• Breaking large syncs into smaller batches
• Contacting Bluecore support to discuss your volume requirements

Best Practices

• Use customer_patch for profile syncs to create or update customer attributes in Bluecore
• Map email for every sync — it is the primary identifier for all Bluecore events
• Use lowercase attribute names with underscores (e.g., first_name, zip_code) per Bluecore’s requirements
• Use boolean values for boolean attributes — Bluecore does not accept string representations like "true" or "false"
• Include product_id for commerce events to enable Bluecore’s product recommendation engine
• Send purchase events with order_id and total for accurate revenue attribution

Troubleshooting

Authentication failed: invalid API key or namespace

Verify that your API key is correct and has not been revoked. Confirm your namespace matches exactly what Bluecore provided. Contact Bluecore support at support@bluecore.com if you need a new API key.

Events not appearing in Bluecore

Bluecore returns HTTP 202 for accepted events, which means events are queued for processing. Allow up to 15 minutes for events to appear in the Bluecore Audience Builder. Use Bluecore’s Audience Builder to query for test customers and verify successful ingestion.

Customer attributes not updating

Ensure all attribute names are lowercase and use underscores instead of spaces or dashes. Bluecore silently ignores attributes that do not follow this convention.

Missing product data in commerce events

For purchase, viewed_product, add_to_cart, and wishlist events, ensure you map a product_id or id field. Without a product identifier, Bluecore cannot associate the event with a product in your catalog.

Purchase events missing revenue data

Purchase events require both order_id and total fields. Map these fields in your sync configuration to ensure accurate revenue tracking in Bluecore.

Non-email distinct_id not linking to customer

If you use a device ID or UUID as the distinct_id, you must first send an identify event to link that identifier to the customer’s email address. Without this link, Bluecore cannot associate events with a customer profile.

Boolean attributes stored as strings

Bluecore requires boolean attributes to use actual boolean values (true/false), not string representations. If your warehouse stores booleans as strings, use a SQL model to cast them before syncing.

Rate limit errors (HTTP 429)

Zeotap automatically retries with exponential backoff. If 429 errors persist, reduce your sync frequency or contact Bluecore support to discuss rate limit increases for your account.