Product Information Management

Product Information Management

Overview

A Product Information Management (PIM) system is the single source of truth for product data — names, descriptions, images, attributes, and digital assets — across all channels (website, marketplaces, print catalogs). Akeneo and Salsify are the dominant PIM platforms. This skill covers connecting a PIM as the authoritative source for product enrichment, implementing sync between the PIM and your commerce platform, and building a pipeline that transforms PIM data into channel-specific formats.

When to Use This Skill

• When product data is inconsistent across your website, marketplace listings, and internal systems
• When the merchandising team manages product content in a PIM and the commerce platform needs to reflect it
• When building a new headless storefront that needs a source of enriched product data
• When adding a new sales channel (marketplace, B2B portal) that needs channel-specific product data
• When auditing product data quality and identifying missing attributes across the catalog

Core Instructions

Step 1: Determine your platform and PIM integration approach

Step 2: Platform-specific PIM integration

---

Shopify

Connect Akeneo to Shopify using the official connector:

1. In your Akeneo instance, go to Connect → Marketplace and install the Shopify Connector (free, by Akeneo) 2. Configure a Connection in Akeneo (under Connect → Connections) with read permissions for Products, Media files, and Attribute options 3. In the connector settings, map your Akeneo channels/locales to your Shopify markets (e.g., Akeneo en_US scope → Shopify default language) 4. Map Akeneo attribute codes to Shopify fields:

• name → Shopify product title
• description → Shopify body HTML
• price → Shopify variant price
• Custom attributes → Shopify product metafields (configure under Settings → Custom data in Shopify admin)

5. Run an initial full sync and then schedule incremental syncs — the connector pulls only products with updated > last_sync_at

Verify the sync:

• Go to a product in your Shopify admin and check that the title, description, and images match what's in Akeneo
• Check metafields in the Shopify product page under Metafields section

---

WooCommerce

Sync Akeneo to WooCommerce using the REST API:

The open-source Akeneo WooCommerce Connector (available at github.com/akeneo/woocommerce-connector) provides a starting point, but many merchants build a custom sync script:

1. Set up a cron job (daily or hourly) that:

• Fetches products from Akeneo updated since the last sync using GET /api/rest/v1/products?search={"updated":[{"operator":">","value":"..."}]}
• Checks if the product exists in WooCommerce using GET /wp-json/wc/v3/products?sku={sku}
• Creates or updates the WooCommerce product using POST or PUT /wp-json/wc/v3/products/{id}

2. Map Akeneo fields to WooCommerce fields:

• Akeneo name (en_US) → WooCommerce name
• Akeneo description → WooCommerce description
• Akeneo images → Download and upload to WordPress media library, then set as WooCommerce product images
• Akeneo custom attributes → WooCommerce product attributes or ACF custom fields

3. After each sync, clear WooCommerce's transient cache: wp transient delete-all via WP-CLI to ensure updated products appear immediately

---

BigCommerce

Connect Akeneo using the BigCommerce connector:

1. In Akeneo Marketplace, install the BigCommerce Connector and configure your BigCommerce API credentials (Client ID, Client Secret, Access Token from Advanced Settings → API Accounts) 2. Map Akeneo families to BigCommerce product types in the connector configuration 3. Configure attribute mappings:

• Akeneo attributes → BigCommerce custom fields or variant option sets
• Akeneo categories → BigCommerce category tree

4. Schedule regular incremental syncs from the connector settings

---

Custom / Headless

Connect to the Akeneo REST API:

// lib/akeneo/client.ts
export class AkeneoClient {
  private accessToken: string | null = null;
  private tokenExpiry: number = 0;

  constructor(private config: {
    baseUrl: string; clientId: string; clientSecret: string;
    username: string; password: string;
  }) {}

  async getToken(): Promise<string> {
    if (this.accessToken && this.tokenExpiry > Date.now() + 60000) return this.accessToken;

    const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString('base64');
    const res = await fetch(`${this.config.baseUrl}/api/oauth/v1/token`, {
      method: 'POST',
      headers: { 'Authorization': `Basic ${credentials}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ grant_type: 'password', username: this.config.username, password: this.config.password }),
    });

    const data = await res.json();
    this.accessToken = data.access_token;
    this.tokenExpiry = Date.now() + data.expires_in * 1000;
    return this.accessToken!;
  }

  async getAll(path: string): Promise<any[]> {
    const items: any[] = [];
    let nextUrl: string | null = path;

    while (nextUrl) {
      const token = await this.getToken();
      const res = await fetch(`${this.config.baseUrl}${nextUrl}`, {
        headers: { 'Authorization': `Bearer ${token}` },
      });
      const page = await res.json();
      items.push(...(page._embedded?.items ?? []));
      nextUrl = page._links?.next?.href?.replace(this.config.baseUrl, '') ?? null;
    }

    return items;
  }
}

export const akeneo = new AkeneoClient({
  baseUrl: process.env.AKENEO_BASE_URL!,
  clientId: process.env.AKENEO_CLIENT_ID!,
  clientSecret: process.env.AKENEO_CLIENT_SECRET!,
  username: process.env.AKENEO_USERNAME!,
  password: process.env.AKENEO_PASSWORD!,
});

Transform Akeneo's locale/scope-scoped attribute format into a flat storefront product:

// lib/akeneo/product-transformer.ts
export function transformAkeneoProduct(akeneoProduct: any, locale = 'en_US', scope = 'ecommerce') {
  const getValue = (attrCode: string, defaultValue: any = null) => {
    const values = akeneoProduct.values[attrCode] ?? [];
    const match = values.find(v => v.locale === locale && v.scope === scope)
      ?? values.find(v => v.locale === locale && v.scope === null)
      ?? values.find(v => v.locale === null && v.scope === scope)
      ?? values.find(v => v.locale === null && v.scope === null);
    return match?.data ?? defaultValue;
  };

  return {
    sku: akeneoProduct.identifier,
    name: getValue('name', '') as string,
    description: getValue('description', '') as string,
    brand: getValue('brand', '') as string,
    categories: akeneoProduct.categories,
    attributes: {
      color: getValue('color'),
      size: getValue('size'),
      material: getValue('material'),
    },
    enabled: akeneoProduct.enabled,
  };
}

Incremental sync job (fetch only updated products):

// jobs/akeneo-sync.ts
export async function syncAkeneoProducts() {
  const lastSyncAt = await db.syncState.getLastSync('akeneo_products');
  const syncStartTime = new Date();
  const updatedAt = lastSyncAt?.toISOString() ?? '2020-01-01T00:00:00+00:00';

  const products = await akeneo.getAll(
    `/api/rest/v1/products?search={"updated":[{"operator":">","value":"${updatedAt}"}]}&limit=100&with_attribute_options=true`
  );

  let synced = 0, errors = 0;

  for (const akeneoProduct of products) {
    try {
      const storefrontProduct = transformAkeneoProduct(akeneoProduct);
      // Validate required fields before upserting
      if (!storefrontProduct.name) {
        console.warn(`Skipping ${akeneoProduct.identifier}: missing name`);
        continue;
      }
      await db.products.upsert(storefrontProduct.sku, {
        ...storefrontProduct,
        akeneoUpdatedAt: new Date(akeneoProduct.updated),
      });
      synced++;
    } catch (err: any) {
      errors++;
      await db.syncErrors.insert({ productId: akeneoProduct.identifier, error: err.message });
    }
  }

  await db.syncState.updateLastSync('akeneo_products', syncStartTime);
  console.log(`Akeneo sync complete: ${synced} synced, ${errors} errors`);
}

Webhook-triggered sync when Akeneo publishes a product (Akeneo's Event API):

// Register the webhook endpoint in Akeneo under: Connect → Webhooks
// POST /api/webhooks/akeneo
export async function POST(req: NextRequest) {
  const event = await req.json();
  if (event.event_type === 'product.updated' || event.event_type === 'product.created') {
    const sku = event.data.resource.identifier;
    const akeneoProduct = await akeneo.getAll(`/api/rest/v1/products/${sku}?with_attribute_options=true`);
    const storefrontProduct = transformAkeneoProduct(akeneoProduct);
    await db.products.upsert(sku, storefrontProduct);
    // Purge CDN cache for this product's page
    await revalidateProductPage(storefrontProduct.slug);
  }
  return NextResponse.json({ received: true });
}

Best Practices

• Treat the PIM as the source of truth — never write product content back from commerce to PIM — data flows from PIM to commerce; only push back to PIM for data the PIM explicitly manages (e.g., SEO metadata your platform generates)
• Use incremental sync, not full sync — fetching all products every 15 minutes is expensive; use Akeneo's updated filter to fetch only changed products
• Upload images to your own CDN during sync — Akeneo media file URLs are internal API URLs requiring authentication; never serve them directly to customers; upload to S3/R2/Cloudinary during sync
• Cache attribute options locally — color, size, and material option label lookups change rarely; cache them in Redis and refresh hourly to avoid per-product API calls
• Validate required attributes before syncing to the storefront — a product without a name or primary image should not be published; add validation before upsert

Common Pitfalls

Related Skills

• @marketplace-connectors
• @webhook-architecture
• @erp-integration
• @analytics-integration

Akeneo PIM Sync Integration

Problem/Feature Description

A growing e-commerce company has just licensed Akeneo PIM as their central hub for product content. The engineering team needs to build the foundational TypeScript integration layer that connects their Node.js backend to Akeneo, so that product data flows automatically into their commerce database whenever merchandisers update products in Akeneo.

The team currently does a full catalog export every night (all 20,000 products), which takes 45 minutes and hammers the Akeneo API. They need a new approach that only fetches products changed since the last run. The integration also needs to be resilient — a single bad product record shouldn't abort the whole job and lose updates for the rest of the catalog. The last-sync timestamp should be persisted between runs so the job can always pick up where it left off.

Output Specification

Produce a TypeScript implementation with the following files:

• lib/akeneo/client.ts — Akeneo API client class
• jobs/akeneo-sync.ts — Scheduled sync job

The implementation should be realistic, runnable TypeScript (no pseudo-code). Use environment variables for all credentials and configuration. Add a sync-log.md documenting how the key design decisions in the implementation work — specifically the authentication approach, pagination strategy, and how incremental sync is achieved.

Product Enrichment Pipeline for Headless Storefront

Problem/Feature Description

A fashion retailer is launching a new headless storefront backed by Akeneo PIM. Their catalog has attributes like color, size, material, and country_of_origin stored as select-list option codes (e.g., color: "CLR_BLU" instead of "Blue"). They also have localized attributes — descriptions exist in multiple locales and are scoped to different sales channels. Without correct transformation, the storefront will display cryptic codes instead of readable labels, and products missing key content will slip through to production.

The team needs a TypeScript data pipeline that takes raw Akeneo product payloads and transforms them into clean storefront-ready objects. The pipeline must resolve attribute option codes to human-readable labels (loading options from Akeneo and caching them), flatten localized/scoped attribute values correctly, validate that products meet minimum content requirements before passing them downstream, and filter out incomplete products using Akeneo's own completeness data.

Output Specification

Produce a TypeScript implementation with the following files:

• lib/akeneo/product-transformer.ts — transformation logic including locale/scope resolution
• lib/akeneo/attribute-options.ts — attribute option loader and label resolver
• lib/akeneo/pipeline.ts — the pipeline that loads options, validates products, and transforms them

Include a pipeline-design.md that explains the key design decisions in your pipeline: how multi-locale/multi-scope attribute values are resolved, how attribute option labels are loaded and made available to the transformer, and what quality checks are applied before a product is passed downstream.

Input Files

The following representative Akeneo API payloads are provided as reference data. Extract them before beginning.

=============== FILE: inputs/sample-products.json =============== [ { "identifier": "SHIRT-001", "family": "shirts", "enabled": true, "categories": ["summer_collection", "mens"], "updated": "2026-03-10T14:00:00+00:00", "values": { "name": [ {"locale": "en_US", "scope": null, "data": "Classic Oxford Shirt"}, {"locale": "fr_FR", "scope": null, "data": "Chemise Oxford Classique"} ], "description": [ {"locale": "en_US", "scope": "ecommerce", "data": "A timeless Oxford shirt crafted from premium cotton."}, {"locale": "en_US", "scope": "print", "data": "Premium Oxford shirt for print catalog."} ], "color": [{"locale": null, "scope": null, "data": "CLR_BLU"}], "size": [{"locale": null, "scope": null, "data": "SZ_M"}], "material": [{"locale": null, "scope": null, "data": "MAT_COT"}], "images": [{"locale": null, "scope": null, "data": "abc123.jpg"}] }, "completeness": {"ecommerce": 100, "print": 85} }, { "identifier": "SHIRT-002", "family": "shirts", "enabled": true, "categories": ["summer_collection"], "updated": "2026-03-11T09:00:00+00:00", "values": { "name": [{"locale": "en_US", "scope": null, "data": ""}], "description": [{"locale": "en_US", "scope": "ecommerce", "data": "A lightweight linen shirt."}], "color": [{"locale": null, "scope": null, "data": "CLR_WHT"}], "size": [{"locale": null, "scope": null, "data": "SZ_L"}] }, "completeness": {"ecommerce": 60, "print": 40} } ]

=============== FILE: inputs/sample-attribute-options.json =============== { "color": [ {"code": "CLR_BLU", "labels": {"en_US": "Blue", "fr_FR": "Bleu"}}, {"code": "CLR_WHT", "labels": {"en_US": "White", "fr_FR": "Blanc"}} ], "size": [ {"code": "SZ_M", "labels": {"en_US": "Medium"}}, {"code": "SZ_L", "labels": {"en_US": "Large"}} ], "material": [ {"code": "MAT_COT", "labels": {"en_US": "Cotton", "fr_FR": "Coton"}} ] }

Salsify Catalog Migration and Data Quality Dashboard

Problem/Feature Description

A home goods brand is migrating their product catalog management from Salsify to a new commerce platform. Their Salsify instance holds 3,000+ products with properties named in plain English (e.g., "Product Name", "Long Description", "Brand") and digital assets organized by type. The migration team has discovered that data quality is inconsistent — many products are missing required attributes for certain product families — and they need to surface these gaps before going live.

The engineering team needs two things: (1) a TypeScript integration that fetches products from Salsify and normalizes them into the same internal product shape used by the rest of the platform, and (2) a data quality reporting tool that reads a snapshot of the product catalog (in the same Salsify response format) and produces a completeness report showing, for each required attribute in a given product family, how many products have it filled in — sorted to highlight the worst gaps first.

Output Specification

Produce a TypeScript implementation with the following files:

• lib/salsify/client.ts — Salsify API client with product fetching
• lib/salsify/product-mapper.ts — mapping Salsify property names to normalized internal fields
• lib/quality/data-quality.ts — data quality report generator
• quality-report.json — the data quality report generated by running the tool against the provided sample data

Include a migration-notes.md explaining: how Salsify authentication works, how products are mapped from Salsify's property naming convention to the internal format, and how the quality report sorts its results.

Input Files

The following sample data is provided. Extract it before beginning.

=============== FILE: inputs/salsify-products.json =============== [ { "id": "prod-001", "Product ID": "HG-BOWL-001", "Product Name": "Ceramic Serving Bowl", "Long Description": "Hand-crafted ceramic serving bowl with a matte finish, perfect for entertaining.", "Brand": "ArtisanHome", "Color": "Sage Green", "Material": "Ceramic", "Weight (lbs)": 2.4, "Digital Assets": [ {"name": "front-view.jpg", "url": "https://cdn.example.com/hg-bowl-001-front.jpg", "type": "Image"}, {"name": "spec-sheet.pdf", "url": "https://cdn.example.com/hg-bowl-001-spec.pdf", "type": "Document"} ], "system_updated_at": "2026-03-10T10:00:00Z" }, { "id": "prod-002", "Product ID": "HG-VASE-001", "Product Name": "Tall Glass Vase", "Long Description": "", "Brand": "", "Color": "Clear", "Digital Assets": [], "system_updated_at": "2026-03-11T08:30:00Z" }, { "id": "prod-003", "Product ID": "HG-PLATE-001", "Product Name": "Dinner Plate Set", "Long Description": "Set of 4 hand-painted dinner plates.", "Brand": "ArtisanHome", "Material": "Ceramic", "Weight (lbs)": 3.1, "Digital Assets": [ {"name": "plate-set.jpg", "url": "https://cdn.example.com/hg-plate-001.jpg", "type": "Image"} ], "system_updated_at": "2026-03-09T16:45:00Z" } ]

=============== FILE: inputs/family-attributes.json =============== { "home_goods": ["Product Name", "Long Description", "Brand", "Color", "Material", "Weight (lbs)", "Digital Assets"] }