InRiver Integration

Overview

InRiver is a leading Product Information Management (PIM) platform designed for managing complex product data, digital assets, and multi-channel content distribution. The InRiver integration package enables seamless synchronization of product information, specifications, media assets, and hierarchical data between InRiver and your e-commerce or content management systems.

This integration uses the InRiver Node.js SDK to provide robust connections to your InRiver environment, supporting advanced query filtering, chunked processing, and incremental synchronization for enterprise-scale product catalogs.

Key Features

🗂️ Entity Management

Query and retrieve products, categories, assets, and related entities from InRiver

🔍 Advanced Filtering

Use InRiver's powerful query filters to extract precisely the data you need

📊 Incremental Sync

Track last sync timestamps to only pull updated records for efficient data flow

⚡ Chunked Processing

Handle large product catalogs with configurable batch sizes and processing delays

📷 Media Support

Optionally load media details and digital assets associated with products

🏢 Enterprise Ready

Built for high-volume product data management with robust error handling

When to Use This Integration

Sync product catalogs from InRiver PIM to e-commerce platforms (Shopify, BigCommerce, Magento)
Export product data to content management systems or digital experience platforms
Build data warehouses by pulling InRiver data for analytics and reporting
Automate content distribution across multiple sales channels and touchpoints
Synchronize product hierarchies including categories, variants, and relationships
Manage digital assets by syncing product images, videos, and documents

Configuration

Required Fields

Configure the InRiver integration with your API credentials and query parameters:

{
  "inriver": {
    "base_url": "https://your-instance.productmarketingcloud.com",
    "api_key": "your_api_key_here",
    "query_filters": [
      {
        "type": "ChannelId",
        "value": "393",
        "operator": "Equal"
      }
    ],
    "query_filter_last_date": "2021-11-07T00:00:00",
    "load_values": true,
    "load_media_details": false,
    "chunk_waiting_time": 500,
    "chunk_size": 1000
  }
}

base_url

Type: String (required)

Description: Your InRiver REST API endpoint URL

Format: https://[your-instance].productmarketingcloud.com

Location: Provided by InRiver upon account setup

api_key

Type: String (required)

Description: Your InRiver API authentication key

Location: InRiver Control Center → Settings → API Keys

query_filters

Type: Array of Objects (required)

Description: Filter criteria to specify which entities to retrieve

Properties: type (field name), value (filter value), operator (comparison operator)

Example: Filter by channel ID, entity type, or custom fields

query_filter_last_date

Type: String (ISO 8601 date) (optional)

Description: Date filter for incremental sync—only retrieve entities modified after this date

Format: YYYY-MM-DDTHH:mm:ss (e.g., 2021-11-07T00:00:00)

load_values

Type: Boolean (optional, default: true)

Description: Whether to load field values for entities

Recommendation: Set to true for full product data

load_media_details

Type: Boolean (optional, default: false)

Description: Whether to load detailed media/asset information

Recommendation: Set to true if you need image URLs, file metadata

chunk_waiting_time

Type: Integer (milliseconds) (optional, default: 500)

Description: Delay between processing chunks to manage API rate limits

Recommendation: 500-2000ms depending on data volume

chunk_size

Type: Integer (optional, default: 1000)

Description: Number of records to process per batch

Recommendation: 500-2000 records per chunk for optimal performance

🔑 How to Get Your API Credentials

Log into your InRiver Control Center
Navigate to Settings → API Keys
Create a new API key with appropriate permissions (read access to entities)
Note your base_url (API endpoint) from InRiver documentation or support
Configure query filters based on your channel or entity type requirements

Query Filters

Understanding Query Filters

Query filters allow precise control over which entities are retrieved from InRiver:

Filter Structure

{
  "type": "ChannelId",
  "value": "393",
  "operator": "Equal"
}

Available Operators

Equal: Exact match (e.g., ChannelId = 393)
NotEqual: Exclude matching values
GreaterThan / LessThan: Numeric comparisons
Contains: Partial text match
In: Match any value in array
Between: Range queries

Common Filter Types

ChannelId

Filter entities by specific InRiver channel (e.g., web channel, print channel)

{
  "type": "ChannelId",
  "value": "393",
  "operator": "Equal"
}

EntityTypeId

Filter by entity type (Product, Category, Item, etc.)

{
  "type": "EntityTypeId",
  "value": "Product",
  "operator": "Equal"
}

Modified Date

Filter by last modified date for incremental sync

{
  "type": "ModifiedDate",
  "value": "2024-01-01T00:00:00",
  "operator": "GreaterThan"
}

💡 Filter Best Practices

Start with channel filters to scope queries to specific sales channels
Use entity type filters to retrieve specific data types (products vs. categories)
Combine multiple filters for precise data extraction
Use date filters for incremental sync patterns
Test filters in InRiver UI before implementing in workflows

Available Actions

🔍 Query & Search Entities

Pull products, categories, and entities from InRiver with advanced filtering and chunked processing

Pull / Origin

Use Cases

🛒 E-commerce Catalog Sync

Sync product catalogs from InRiver to Shopify, BigCommerce, Magento, or other e-commerce platforms with automated updates.

🌐 Multi-Channel Distribution

Distribute product content to multiple sales channels (web, mobile, print, retail) from single source of truth.

📊 Data Warehouse Integration

Export InRiver product data to data warehouses (Snowflake, BigQuery) for analytics and business intelligence.

🔄 Real-Time Inventory Sync

Use incremental sync to push updated product information to downstream systems as changes occur in InRiver.

🖼️ Digital Asset Management

Sync product images, videos, and documents from InRiver to content delivery networks or media libraries.

🏷️ Product Information Enrichment

Pull InRiver data to enrich product information in CRM, ERP, or marketing automation platforms.

Incremental Synchronization

Efficient Data Updates

For large product catalogs, incremental sync reduces processing time by only retrieving changed records:

Implementation Pattern

Initial Full Sync: First run pulls all entities matching your filters
Store Last Sync Time: Record the timestamp of successful sync completion
Incremental Updates: Subsequent syncs use query_filter_last_date to only pull modified records
Update Timestamp: After each successful sync, update the last sync timestamp

{
  "inriver": {
    "base_url": "https://your-instance.productmarketingcloud.com",
    "api_key": "your_api_key_here",
    "query_filters": [
      {
        "type": "ChannelId",
        "value": "393",
        "operator": "Equal"
      },
      {
        "type": "ModifiedDate",
        "value": "2024-01-25T08:00:00",
        "operator": "GreaterThan"
      }
    ],
    "query_filter_last_date": "2024-01-25T08:00:00"
  }
}

💡 Incremental Sync Best Practices

Schedule frequent small syncs rather than infrequent large ones
Store last sync timestamp reliably (database, config file, environment variable)
Add buffer time (e.g., -5 minutes) to account for InRiver processing delays
Monitor for missed updates and implement fallback full sync periodically
Test date filter logic thoroughly before production deployment

Performance Optimization

⚡ Chunking Strategy

Optimize chunk_size and chunk_waiting_time based on catalog size:

Small catalogs (<10k entities): chunk_size: 2000, chunk_waiting_time: 500ms
Medium catalogs (10k-100k): chunk_size: 1000, chunk_waiting_time: 1000ms
Large catalogs (>100k): chunk_size: 500, chunk_waiting_time: 1500-2000ms
Monitor API response times and adjust accordingly

🎯 Selective Loading

Load only necessary data to improve performance:

Set load_media_details: false if you don't need asset metadata
Use precise query filters to reduce result set size
Consider channel-specific syncs rather than pulling all channels
Filter by entity type to separate product vs. category syncs

⏰ Scheduling

Optimize sync timing for best performance:

Schedule large full syncs during off-peak hours
Run incremental syncs frequently (every 15-60 minutes)
Coordinate with InRiver team for maintenance windows
Consider time zone differences for global operations

Data Privacy & Security

Enterprise Data Protection

When working with InRiver product data:

✅ Secure API keys using environment variables or secrets management
✅ Encrypt data in transit (HTTPS required for InRiver API)
✅ Limit access to InRiver credentials based on least privilege principle
✅ Monitor API usage for unusual patterns or unauthorized access
✅ Implement audit logging for all data sync operations
✅ Rotate API keys periodically according to security policies

🔒 Security Best Practices

Never commit API keys to version control systems
Use dedicated API keys for each integration/environment
Implement IP whitelisting if supported by your InRiver plan
Monitor for data exfiltration or unexpected large downloads
Ensure destination systems have appropriate security controls

Troubleshooting

🔴 Issue: "Authentication failed"

Cause: API key is invalid, expired, or lacks required permissions.

Solution: Verify api_key in InRiver Control Center. Ensure key has read permissions for entities. Check base_url is correct.

🔴 Issue: "No entities returned"

Cause: Query filters are too restrictive or no entities match criteria.

Solution: Review query_filters configuration. Test filters in InRiver UI. Check channel ID is correct. Verify entity type exists.

🔴 Issue: "Timeout errors"

Cause: Query returning too many results or InRiver API slow.

Solution: Reduce chunk_size. Increase chunk_waiting_time. Add more specific filters. Consider breaking into smaller queries.

🔴 Issue: "Missing product data"

Cause: load_values set to false or data not published to channel.

Solution: Set load_values: true. Verify entities are published to queried channel in InRiver. Check field mapping.

🔴 Issue: "Incremental sync not working"

Cause: Date format incorrect or timestamp not updating.

Solution: Verify query_filter_last_date uses ISO 8601 format. Ensure timestamp updates after each successful sync. Add date filter to query_filters.

Installation & Setup

⚠️ NPM Registry Configuration Required

The InRiver integration uses a private SDK package hosted on GitHub. You need to configure npm to access the Imagination Media GitHub registry:

1. Create .npmrc File

Add the following to your project's .npmrc file:

@imagination-media:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Authenticate with GitHub

Generate a GitHub Personal Access Token with read:packages permission and configure npm authentication.

📦 Package Details

Package: @imagination-media/inriver-nodejs-sdk
Version: 2.0.1
Repository: github.com/Imagination-Media/inriver-nodejs-sdk

Support & Resources

For help with InRiver integration:

Check the InRiver Documentation
Review InRiver Developer Portal
See InRiver Node.js SDK Repository
Contact InRiver Support for API-specific questions
Contact Retrieve support for integration-specific questions