ERP-to-PIM Integration: Product Information Management Playbook

TL;DR

• Bottom line: ERP owns operational product data (SKU, cost, weight, compliance); PIM owns commercial product data (descriptions, media, translations, channel attributes). Integrate via API or iPaaS with clear data ownership boundaries — never let both systems write the same field.
• Key limit: Akeneo REST API batches max 100 products per PATCH; Salsify bulk API caps at 50K products per import job; all PIM systems throttle concurrent API connections (typically 5-10 parallel requests).
• Watch out for: Live pricing and inventory must bypass PIM entirely — route ERP-to-ecommerce directly. PIM handles only "cold" product data. Syncing hot data through PIM adds latency and creates stale pricing.
• Best for: Organizations with 10K+ SKUs selling across 3+ channels that need attribute enrichment, translations, and channel-specific content beyond what ERP can manage.
• Authentication: Akeneo uses OAuth 2.0 client credentials; Salsify uses API key + org ID; inRiver uses API key; Stibo STEP uses SAML/OAuth 2.0 depending on deployment.

System Profile

This playbook covers end-to-end integration for connecting any major ERP system (SAP S/4HANA, Oracle NetSuite, Microsoft Dynamics 365) with a PIM system (Akeneo, Salsify, inRiver, or Stibo STEP). The ERP acts as the operational product master; the PIM serves as the commercial content enrichment and channel syndication layer. Middleware or iPaaS platforms typically orchestrate the data flow. [src2, src6]

API Surfaces & Capabilities

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• Akeneo OAuth tokens expire after 1 hour by default — middleware must implement automatic refresh. Stale tokens return 401 with no retry hint. [src1]
• Salsify API keys are user-scoped — when the user is deactivated, all integrations using that key break silently. Use a service account. [src3]
• inRiver API keys are environment-scoped (sandbox vs production) — a key from staging returns 403 on production endpoints. [src4]

Constraints

• Data ownership is non-negotiable: ERP owns SKU, cost/price, weight, dimensions, regulatory/compliance codes, supplier info. PIM owns marketing descriptions, media assets, translations, SEO content, channel-specific attributes. A field can have only ONE authoritative source.
• Live pricing and inventory bypass PIM: Price and stock data must flow directly from ERP to ecommerce/POS channels. PIM can store reference pricing for internal workflow support, but never as the live feed.
• Completeness gates block syndication: PIM systems enforce completeness rules per channel — products missing required attributes are silently excluded from channel exports.
• Media asset sync is separate: Binary files should use dedicated DAM-to-PIM connectors, not the product data API. Embedding base64 in product calls causes timeouts.
• Attribute model mismatch: ERP uses flat attributes; PIM uses hierarchical attribute groups, families, and inheritance. Map ERP product types to PIM families before any data flows.
• Channel-specific formatting: Each sales channel requires different attribute names, value formats, and taxonomy codes. Configure per-channel mappings upfront.

Integration Pattern Decision Tree

START — Integrate ERP with PIM for product data enrichment
├── What's the data flow?
│   ├── ERP -> PIM (product master seeding)
│   │   ├── Catalog < 10K SKUs? -> REST API batch import
│   │   ├── Catalog < 100K SKUs? -> Bulk API or SFTP
│   │   └── Catalog > 100K SKUs? -> File-based + chunked (50K batches)
│   ├── PIM -> Channels (enrichment -> syndication)
│   │   ├── Channel supports API? -> PIM native connector or iPaaS
│   │   └── No API? -> PIM scheduled export -> SFTP/file drop
│   └── Bidirectional (ERP <-> PIM)
│       ├── Define field-level ownership rules FIRST
│       └── Implement conflict resolution before any sync
├── Which middleware?
│   ├── SAP ERP -> Akeneo: Akeneo Accelerators on SAP BTP
│   ├── NetSuite -> Any PIM: Celigo or Boomi
│   ├── D365 -> Any PIM: Azure Integration Services or MuleSoft
│   └── Generic -> Any PIM: Workato, MuleSoft, or Boomi
└── Error handling?
    ├── Zero-loss -> idempotent ops + dead letter queue + reconciliation
    └── Best-effort -> retry with backoff + daily reconciliation

Quick Reference

End-to-End Integration Flow

PIM System Comparison

Step-by-Step Integration Guide

1. Define data ownership matrix

Create a field-by-field ownership matrix specifying which system is authoritative for each attribute. This prevents the #1 PIM integration failure: two systems overwriting each other's data. [src1, src2]

DATA OWNERSHIP MATRIX (example)
| Attribute          | Owner | Source System | Consumers           |
|--------------------|-------|---------------|---------------------|
| SKU / Item Number  | ERP   | SAP S/4HANA   | PIM, eCommerce      |
| Cost Price         | ERP   | SAP S/4HANA   | Internal only       |
| Sell Price         | ERP   | SAP S/4HANA   | eCommerce (direct)  |
| Product Name       | PIM   | Akeneo        | eCommerce, marketplace |
| Description (EN)   | PIM   | Akeneo        | eCommerce, marketplace |
| Hero Image         | DAM   | Cloudinary    | PIM, eCommerce      |

Verify: Every field has exactly ONE owner. No field is blank in the "Owner" column.

2. Map ERP product types to PIM attribute families

Each PIM system groups attributes into families (Akeneo), schemas (Salsify), or entity types (inRiver). Map each ERP product category to the corresponding PIM family. [src1, src5]

// Akeneo: Create product family via REST API
// POST /api/rest/v1/families
{
  "code": "electronics_accessories",
  "attributes": ["sku", "name", "description", "hero_image", "weight", "ean"],
  "attribute_as_label": "name",
  "attribute_requirements": {
    "ecommerce": ["sku", "name", "description", "hero_image", "ean"],
    "amazon": ["sku", "name", "amazon_bullet_points", "hero_image", "ean"]
  }
}

Verify: GET /api/rest/v1/families/electronics_accessories returns the family with all attributes.

3. Configure ERP product export

Set up the ERP to export product master data to middleware/iPaaS. Use change-based triggers where possible. [src2]

# SAP S/4HANA OData product export (delta pattern)
import requests
params = {
    "$filter": f"LastChangeDateTime gt datetime'{last_sync}'",
    "$select": "Product,ProductDescription,GrossWeight,WeightUnit,ProductGroup",
    "$top": 1000
}
response = requests.get(f"{SAP_BASE}/Product", headers=headers, params=params)
products = response.json().get("value", [])

Verify: Response status 200; value array contains product records.

4. Transform and load into PIM

Map ERP fields to PIM attributes, convert data types, and batch-import into PIM. [src1]

# Akeneo batch import (max 100 products per PATCH)
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/vnd.akeneo.collection+json"}
payload = "\n".join(json.dumps(transform(p)) for p in products[:100])
resp = requests.patch(f"{AKENEO_BASE}/api/rest/v1/products", headers=headers, data=payload)
# Parse per-product status: 201=created, 204=updated, 422=validation error

Verify: Response contains per-product status lines; no 422 errors.

5. Configure channel syndication

Set up PIM completeness rules and channel-specific exports. [src8]

# Salsify: trigger channel export
export_resp = requests.post(f"{SALSIFY_BASE}/orgs/{ORG_ID}/channel_runs",
    headers=headers, json={"channel_id": SHOPIFY_CHANNEL_ID})
# Poll for completion, check products_exported count

Verify: Channel run "completed"; product count matches expected; check channel for missing products.

6. Implement delta sync and reconciliation

Set up incremental sync and periodic full reconciliation to catch drift. [src2]

# Delta sync: only changed products since last run
changed = erp.get_products(modified_after=last_sync_timestamp)
pim.batch_import(changed)
# Weekly: full reconciliation — compare ERP vs PIM product counts

Verify: Delta sync updates only changed products; reconciliation report shows zero drift.

Code Examples

Python: Full ERP-to-Akeneo PIM Sync Pipeline

# Input:  ERP product records (list of dicts), Akeneo OAuth credentials
# Output: Sync report with created/updated/failed counts

import requests, json

class AkeneoPIMSync:
    def __init__(self, base_url, client_id, client_secret):
        self.base_url = base_url
        self.client_id = client_id
        self.client_secret = client_secret
        self.token = None

    def authenticate(self):
        resp = requests.post(f"{self.base_url}/api/oauth/v1/token", json={
            "grant_type": "client_credentials",
            "client_id": self.client_id, "client_secret": self.client_secret
        })
        resp.raise_for_status()
        self.token = resp.json()["access_token"]

    def batch_upsert(self, products, batch_size=100):
        headers = {"Authorization": f"Bearer {self.token}",
                    "Content-Type": "application/vnd.akeneo.collection+json"}
        results = {"created": 0, "updated": 0, "failed": 0, "errors": []}
        for i in range(0, len(products), batch_size):
            batch = products[i:i + batch_size]
            payload = "\n".join(json.dumps(p) for p in batch)
            resp = requests.patch(f"{self.base_url}/api/rest/v1/products",
                                  headers=headers, data=payload)
            for line in resp.text.strip().split("\n"):
                result = json.loads(line)
                code = result.get("status_code")
                if code == 201: results["created"] += 1
                elif code == 204: results["updated"] += 1
                else:
                    results["failed"] += 1
                    results["errors"].append(result)
        return results

JavaScript/Node.js: inRiver Entity Import

// Input:  ERP product records, inRiver API key
// Output: Created entity IDs
const axios = require('axios'); // [email protected]
const INRIVER_BASE = 'https://apieuw.productmarketingcloud.com/api/v1.0.0';

async function importToInRiver(products, apiKey) {
  const headers = { 'X-inRiver-APIKey': apiKey, 'Content-Type': 'application/json' };
  const results = { created: 0, failed: 0, errors: [] };
  const batchSize = 500;
  for (let i = 0; i < products.length; i += batchSize) {
    const batch = products.slice(i, i + batchSize).map(p => ({
      entityTypeId: 'Product',
      fieldValues: [
        { fieldTypeId: 'ProductNumber', value: p.sku },
        { fieldTypeId: 'ProductName', value: p.name }
      ]
    }));
    try {
      const resp = await axios.post(`${INRIVER_BASE}/entities:createmany`, batch, { headers });
      results.created += resp.data.length;
    } catch (err) {
      results.failed += batch.length;
      results.errors.push(err.response?.data || err.message);
    }
  }
  return results;
}

cURL: Quick Akeneo API Test

# Get OAuth token
curl -X POST "https://your-akeneo.cloud.akeneo.com/api/oauth/v1/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"ID","client_secret":"SECRET"}'
# Expected: {"access_token":"...","expires_in":3600}

# List products
curl "https://your-akeneo.cloud.akeneo.com/api/rest/v1/products?limit=10" \
  -H "Authorization: Bearer TOKEN"
# Expected: {"_embedded":{"items":[...]}}

Data Mapping

Field Mapping Reference

Data Type Gotchas

• Localized attributes: ERP stores one language per field; PIM stores multiple locales. Sending without locale on a localizable attribute causes 422 in Akeneo. [src1]
• Measurement attributes: Akeneo requires {"amount": "1.500", "unit": "KILOGRAM"} objects. Bare numbers cause validation errors. [src1]
• Multi-value fields: SAP stores as concatenated strings (pipe-delimited); PIM expects arrays. Split and trim. [src2]
• Media references: ERP stores file paths; PIM expects uploaded binaries or URLs. Requires separate media pipeline. [src1]
• Category trees: ERP uses flat codes; PIM uses hierarchical trees. Maintain mapping table as both evolve. [src5]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Attribute family mismatch: Import fails when ERP product type has no PIM family mapping. Fix: Create catch-all family; route unmapped products to classification queue. [src1]
• Completeness gate blocking syndication: Products pass PIM validation but fail channel-specific completeness — silently excluded. Fix: Monitor PIM vs channel product count delta; alert on >5% gap. [src8]
• Media upload timeout: Images >20MB timeout on PIM upload APIs. Fix: Compress to max 5MB; use async upload; prefer CDN URLs over binary upload. [src1]
• OAuth token race condition: Multiple workers refresh same token, invalidating each other's. Fix: Token cache with mutex; or separate credentials per worker. [src1]
• Character encoding mismatch: ERP exports Windows-1252; PIM expects UTF-8. Special characters corrupt. Fix: Force UTF-8 in middleware transformation; validate encoding before API call. [src2]
• Category tree reorganization: PIM category restructure breaks all ERP-to-PIM mappings silently. Fix: Store mappings in middleware config; alert on unmapped categories; webhook on category changes. [src5]

Anti-Patterns

Wrong: Syncing live pricing through PIM

# BAD — routing price updates through PIM adds 15-60 min latency
ERP (price change) -> iPaaS -> PIM -> iPaaS -> eCommerce
# Customers see stale pricing

Correct: Direct ERP-to-channel for hot data

# GOOD — hot data bypasses PIM entirely
ERP (price change) -> iPaaS -> eCommerce (direct, <1 min)
ERP (product master) -> iPaaS -> PIM (cold data only)
PIM (enriched content) -> iPaaS -> eCommerce

Wrong: Full catalog rescan on every sync

# BAD — scanning all 500K products every hour
all_products = erp.get_all_products()  # 500K records, 45 min
pim.batch_import(all_products)          # 5,000 API calls, 2 hours

Correct: Delta sync with change tracking

# GOOD — only sync changed products
changed = erp.get_products(modified_after=last_sync)  # ~50 records
pim.batch_import(changed)  # 1 API call

Wrong: Embedding base64 media in product API calls

# BAD — 50MB payload, timeout, 413 Payload Too Large
product["hero_image"] = base64_encode(read_file("product.jpg"))

Correct: Upload media separately, then reference by code

# GOOD — upload asset first, reference in product
media_resp = requests.post(f"{AKENEO}/api/rest/v1/media-files", files=files)
product["hero_image"] = media_resp.headers["Location"].split("/")[-1]

Common Pitfalls

• Not mapping ERP types to PIM families first: Products imported without family assignment get empty attributes. Fix: Build mapping table first; reject unmapped products to review queue. [src1]
• Assuming PIM handles pricing and inventory: PIM is for "cold" product content. Teams routing pricing through PIM discover 30-60 min latency. Fix: ERP-to-ecommerce direct for hot data. [src1, src2]
• Ignoring channel completeness rules: Each channel requires specific attributes (Amazon: bullet points; Google Shopping: GTIN + google_product_category). Missing attributes = silently dropped. Fix: Define completeness rules per channel; build pre-syndication validation. [src8]
• Not handling PIM attribute model changes: When PIM team adds/renames attributes, ERP integration breaks. Fix: Version field mapping config; detect model changes via API; alert on new required attributes. [src5]
• Ignoring locale and scope in Akeneo: Values without proper locale/scope cause silent data loss — saved but invisible. Fix: Always specify locale and scope; validate against attribute properties. [src1]
• Treating initial load like delta sync: Initial 500K SKU import needs different batch sizes and error handling than daily 500-change deltas. Fix: Build two flows — initial load (SFTP/STEPXML, overnight) and delta sync (API, event-driven). [src2]

Diagnostic Commands

# Test Akeneo OAuth authentication
curl -s -o /dev/null -w "%{http_code}" \
  -X POST "https://your-akeneo.cloud.akeneo.com/api/oauth/v1/token" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"ID","client_secret":"SECRET"}'
# Expected: 200

# Check Akeneo product count
curl -s "https://your-akeneo.cloud.akeneo.com/api/rest/v1/products?limit=1" \
  -H "Authorization: Bearer TOKEN" | python -c "import sys,json; print(json.load(sys.stdin).get('items_count'))"

# List Akeneo families
curl -s "https://your-akeneo.cloud.akeneo.com/api/rest/v1/families" \
  -H "Authorization: Bearer TOKEN"

# Test Salsify API key
curl -s -o /dev/null -w "%{http_code}" \
  "https://app.salsify.com/api/v1/orgs/ORG_ID/products?per_page=1" \
  -H "Authorization: Bearer API_KEY"
# Expected: 200

# Test inRiver API key
curl -s -o /dev/null -w "%{http_code}" \
  "https://apieuw.productmarketingcloud.com/api/v1.0.0/model/entitytypes" \
  -H "X-inRiver-APIKey: YOUR_API_KEY"
# Expected: 200

Version History & Compatibility

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• PIM API rate limits are edition-dependent and change with vendor releases — verify current limits against your specific contract before sizing an integration.
• Specific middleware/iPaaS configuration varies significantly by platform — consult vendor-specific documentation for connector setup.
• Akeneo Community Edition (free) has limited API capabilities compared to Enterprise/Serenity — Event Platform and some endpoints are Enterprise-only.
• Media/DAM integration is deliberately high-level because each PIM vendor's media handling differs substantially. Plan a dedicated DAM integration workstream.
• PIM pricing varies by catalog size, channels, and users — comparison figures are rough market ranges as of early 2026.
• PIM systems evolve rapidly with monthly or quarterly updates. Pin integration code to specific API versions and test after every vendor upgrade.