finsilabs/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

| Platform | PIM Integration Option | What It Syncs | |----------|----------------------|--------------| | Shopify | Akeneo's official Shopify connector (free, Akeneo Marketplace) or Salsify Syndication for Shopify | Product names, descriptions, images, and attributes → Shopify product metafields; Shopify variants mapped to Akeneo product models | | WooCommerce | Akeneo WooCommerce Connector (open-source, GitHub) or custom REST API sync | Product data pushed to WooCommerce via the Products REST API; images uploaded to WordPress media library | | BigCommerce | Akeneo BigCommerce Connector (Akeneo Marketplace) or Salsify for BigCommerce | Product attributes pushed to BigCommerce custom fields and variants; image syndication to BigCommerce CDN | | Custom / Headless | Direct REST API integration with Akeneo or Salsify | Full control over data mapping; incremental sync via updated filter; image upload to your CDN during sync |

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

| Problem | Solution | |---------|----------| | Sync fails on products with missing required attributes | Wrap each product sync in try/catch; log the product identifier with the error; skip and continue rather than aborting the entire sync | | Images not available after sync | Akeneo media URLs require authentication; download and re-upload to your CDN during sync — never serve akeneo-base-url/api/rest/v1/media-files/... directly | | Akeneo API rate limits | Use batched requests and run syncs off-peak; cache attribute options locally to reduce API calls per product | | Category mapping out of sync after PIM reorganization | Build a category sync job that runs before the product sync; alert when an Akeneo category code has no mapping in your commerce platform | | Shopify connector not syncing metafields | Ensure the metafield namespace and key in the connector configuration match what's configured in Shopify admin → Settings → Custom data → Products |

Related Skills

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