PromoteIQ

Send conversion events and product feed data to PromoteIQ (Microsoft Retail Media) for attribution, campaign optimization, and retail media advertising.

Prerequisites

• A PromoteIQ account with API access enabled
• Your retailer-specific API base URL (provided by your PromoteIQ Technical Account Manager)
• Your retailer-specific deployment ID (PID)
• An API key for authentication

Authentication

PromoteIQ uses API Key authentication.

1. Contact your PromoteIQ Technical Account Manager to obtain your API credentials
2. Enter your API Key in Zeotap

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

PromoteIQ does not support audience membership management. Use regular sync modes to send conversion and product data.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

How It Works

Conversion Tracking

When Object Type is set to Conversions, Zeotap sends order and event data to the PromoteIQ /conversion endpoint. Rows are grouped by transaction ID (txnid) so that all line items from the same order are sent together. This enables PromoteIQ to accurately attribute conversions to ad campaigns.

Each conversion payload includes the retailer PID, conversion type, customer identifier, and an array of purchased items with SKU, price, and quantity.

Product Feed

When Object Type is set to Product Feed, Zeotap sends product catalog data to PromoteIQ. Products are sent in batches of up to 500 items per request. Each product includes SKU, name, brand, pricing, availability, and image URLs.

Batch Processing

• Conversions: Rows with the same txnid are grouped into a single request. Rows without a transaction ID are sent in chunks of up to 100 items.
• Product Feed: Products are sent in batches of up to 500 per request.
• Requests are retried automatically on transient failures (HTTP 429 or 5xx) with exponential backoff.

Rate Limits

PromoteIQ rate limits vary by retailer deployment. Contact your Technical Account Manager for your specific limits. Zeotap automatically handles HTTP 429 responses with exponential backoff and retry.

Best Practices

• Always include a txnid for conversion data to ensure accurate attribution grouping
• Use hashed customer identifiers rather than PII (PromoteIQ does not accept personally identifiable information)
• For product feeds, send a full catalog daily with delta updates for price and availability changes
• Set the correct conversion type to match your business event (One-Time Purchase, Subscription, Add to Cart, or Add to List)
• Include currency in every conversion to ensure accurate revenue attribution

Troubleshooting

Authentication failed: invalid API key

Verify your API key with your PromoteIQ Technical Account Manager. API keys are specific to your retailer deployment and environment (sandbox vs. production).

API base URL connection error

Ensure the base URL matches your retailer-specific PromoteIQ endpoint. PromoteIQ uses retailer-specific URLs (e.g., https://ad-retailername.tagdelivery.com). The URL must use HTTPS.

Conversion data not appearing in reports

Check that the txnid and customer fields are populated. PromoteIQ requires these fields for attribution. Also verify the conversion type matches the event (e.g., use ATC for Add to Cart events, not ONETIME).

Product feed products not available for campaigns

Ensure all required product feed fields are mapped: sku, name, priceCurrent, available, imageLarge, and landingPageUrl. Missing required fields may cause products to be skipped.

HTTP 429 Too Many Requests

Zeotap automatically retries on rate limit errors with exponential backoff. If errors persist, reduce sync frequency or contact your Technical Account Manager to increase rate limits.

Impression IDs expiring

PromoteIQ impression IDs have a 6-hour TTL. Ensure conversion events are sent within 6 hours of the associated ad impression for accurate attribution.