Skip to main content

Akeneo PIM Integration

This guide walks you through connecting your Akeneo PIM instance to Open Saasframe, mapping product attributes, running your first import, and configuring ongoing synchronization.

Optional env preconfiguration​

If your deployment already knows the Akeneo credentials, you can preconfigure the integration automatically instead of filling the credentials form manually after every fresh install.

Use these env vars:

SF_INTEGRATION_AKENEO_API_URL=https://your-akeneo-instance.cloud.akeneo.com
SF_INTEGRATION_AKENEO_CLIENT_ID=1_abc123...
SF_INTEGRATION_AKENEO_CLIENT_SECRET=secret123...
SF_INTEGRATION_AKENEO_USERNAME=admin
SF_INTEGRATION_AKENEO_PASSWORD=yourpassword
SF_INTEGRATION_AKENEO_ENABLED=true
SF_INTEGRATION_AKENEO_FORCE_PRECONFIGURE=false

To rerun the preset for an existing tenant:

yarn saasframe sync_akeneo configure-from-env --tenant <tenantId> --org <organizationId>

URL security and host allowlist​

Open Saasframe validates the Akeneo API URL server-side before any network call to prevent SSRF (Server-Side Request Forgery) and credential exfiltration. The following rules are enforced:

  • The URL must use HTTPS.
  • Embedded credentials, custom ports, paths, query parameters, and fragments are rejected.
  • The hostname must match an operator-controlled allowlist.
  • Before each authenticated request, the hostname is resolved and loopback, link-local, RFC1918, and other private or reserved IP ranges are rejected.
  • The outbound fetch is pinned to the validated DNS address to prevent DNS rebinding between validation and connection.

By default, only Akeneo SaaS hosts are allowed: *.cloud.akeneo.com and *.akeneo.cloud.

Self-hosted or custom Akeneo instances​

If your Akeneo PIM runs on a custom domain, set the SF_INTEGRATION_AKENEO_ALLOWED_HOSTS environment variable to a comma-separated list of allowed hostnames. Wildcard subdomains are supported:

# Single self-hosted instance
SF_INTEGRATION_AKENEO_ALLOWED_HOSTS=pim.example.com

# Multiple hosts with wildcard
SF_INTEGRATION_AKENEO_ALLOWED_HOSTS=*.pim.example.com,akeneo.staging.example.com

Legacy aliases SAASFRAME_AKENEO_ALLOWED_HOSTS and AKENEO_ALLOWED_HOSTS are also accepted (checked in priority order).

Allowed hosts must resolve to public, routable IP addresses by default. If your deployment intentionally reaches Akeneo over a trusted private network, combine an exact host allowlist with:

SF_INTEGRATION_AKENEO_ALLOWED_HOSTS=pim.example.internal
SF_INTEGRATION_AKENEO_ALLOW_PRIVATE_URLS=true

Use this only for operator-controlled internal deployments; it disables the private-IP DNS guard for Akeneo requests.

info

All authenticated requests (OAuth token exchange, product pagination, media downloads) are pinned to the validated origin. If the remote API returns absolute URLs pointing to a different host, those requests are rejected to prevent token leakage.

Prerequisites​

  • An Akeneo PIM instance (v5+ recommended) with API access enabled.
  • An API connection created in Akeneo (System → Connections or Connect → Connection settings) with at least read permissions on products, categories, attributes, and media.
  • The integrations.credentials.manage and data_sync.manage features enabled for your role in Open Saasframe.

Step 1 — Enter Akeneo credentials​

  1. Navigate to External Systems → Integrations and click Configure on the Akeneo PIM card.

Akeneo in the Integration Marketplace

  1. Open the Credentials tab and fill in the connection details from your Akeneo instance.

Akeneo credentials form

FieldWhere to find itExample
API URLYour Akeneo instance URLhttps://mycompany.cloud.akeneo.com
Client IDAkeneo → Connect → Connection settings → Credentials1_abc123def456...
Client SecretSame page as Client IDsecret_xyz789...
UsernameThe Akeneo user associated with the connectionsaasframe_api
PasswordPassword for that Akeneo user••••••••
  1. Click Save Credentials.
caution

The Akeneo user must have read access to products, categories, attributes, families, and media files. Without these permissions the import will fail with authorization errors.

Step 2 — Verify health​

Switch to the Health tab and click Run Check. A Healthy result confirms Open Saasframe can authenticate with your Akeneo instance using OAuth and reach the API.

If the check fails, verify that:

  • The API URL is correct and reachable from your server (no trailing slash needed).
  • The Client ID and Secret match the connection in Akeneo.
  • The username and password are valid for the user linked to that connection.

Step 3 — Discover and map attributes​

Before importing products, Open Saasframe needs to understand how your Akeneo attributes map to catalog fields. Navigate to the Attributes Mapping section on the Akeneo integration page.

Attribute mapping overview

Open Saasframe automatically discovers your Akeneo families and their attributes. For each attribute, you can choose how it maps:

  • Standard field — maps to a built-in Open Saasframe product field (name, description, SKU, price, weight, etc.)
  • Custom field — creates a new custom field in your catalog to hold the data
  • Skip — ignores the attribute during import

Click on any attribute row to open the attribute editor and configure the mapping in detail.

Attribute editor

tip

Open Saasframe infers sensible defaults for most attributes. Review the mapping before your first import, but you don't need to configure every attribute manually.

Step 4 — Run the first import​

Once credentials are verified and attributes are mapped, start the initial full import. Navigate to the import section and click Start Import.

First import

The first import runs in three sequential steps:

  1. Categories — imports your Akeneo category tree, preserving the hierarchy.
  2. Attributes — creates option schemas and custom fields based on your attribute mapping.
  3. Products — imports simple products and product models (with variants), downloads media files, and applies pricing.

Each step shows real-time progress. You can monitor the import from the Ongoing Imports view.

Ongoing imports with progress

info

The first import can take several minutes for large catalogs (10,000+ products). Open Saasframe processes products in batches with rate limiting to avoid overloading your Akeneo instance. You can safely navigate away — the import continues in the background.

Step 5 — Review imported products​

After the import completes, navigate to Catalog → Products to verify your data. Here is what to expect:

Source product in Akeneo​

Source product in Akeneo

Imported main product​

The main product appears with all mapped fields populated — name, description, images, and any custom fields from your attribute mapping.

Imported main product

Variants​

Akeneo product models with variant axes are imported as Open Saasframe product variants. Each variant inherits the parent product's shared attributes and adds its own axis values (e.g., size, color).

Imported variants

Families and attributes​

The Akeneo family structure is preserved through option schemas and custom field sets, keeping your product data organized.

Imported families and attributes

Products with variants (Converse example)​

Imported product with variants

Step 6 — Configure scheduled sync​

After the initial import, set up automatic synchronization to keep your catalog in sync with Akeneo. Open the Scheduler settings for the Akeneo integration.

Scheduler settings

Configure the sync interval to match your needs. Incremental syncs are fast because they only fetch products updated since the last successful run.

Scheduled imports overview

SettingRecommendation
Sync intervalEvery 5–15 minutes for active catalogs, hourly for stable ones
ModeIncremental (default) — only fetches changes since last sync
tip

Incremental syncs use Akeneo's updated timestamp filter, so only modified products are fetched. A sync of a 50,000-product catalog with 20 changes takes seconds, not minutes.

How variants work​

Akeneo uses a two-level hierarchy for configurable products:

Product Model (e.g., "Converse Chuck Taylor")
  └── Variant (e.g., "Size 42, Black")
  └── Variant (e.g., "Size 43, White")

Open Saasframe flattens this into:

Product (e.g., "Converse Chuck Taylor")
  ├── Variant: Size 42, Black
  ├── Variant: Size 43, White
  └── Option Schema: Size + Color (from family variant axes)

The family variant axes become option schemas automatically, so your storefront can render proper size/color selectors.

How media sync works​

During import, Open Saasframe downloads product images and files from Akeneo using authenticated API requests and re-hosts them in the local attachment system. This means:

  • Images are served from your Open Saasframe instance, not from Akeneo.
  • Media files are deduplicated using content hashes — re-importing the same image does not create duplicates.
  • Incremental syncs skip media that hasn't changed.

Troubleshooting​

ProblemSolution
Health check fails with "Unauthorized"Verify Client ID, Secret, Username, and Password. Regenerate the connection credentials in Akeneo if needed.
Health check fails with "Connection refused"Check the API URL. Ensure your server can reach the Akeneo instance (firewall, DNS).
Health check fails with "host is not allowed"Your Akeneo URL does not match the default host allowlist (*.cloud.akeneo.com, *.akeneo.cloud). Set SF_INTEGRATION_AKENEO_ALLOWED_HOSTS to include your custom domain. See URL security and host allowlist.
Products imported without imagesThe Akeneo user may lack media read permissions. Check the connection's permission scope in Akeneo.
Missing attributes on imported productsReview the attribute mapping — unmapped attributes are skipped by default.
Variants not appearingEnsure the source products are product models (not simple products) with family variants configured in Akeneo.
Sync seems stuckCheck Ongoing Imports for error details. Large catalogs may take time on the first full import.
Duplicate products after re-importOpen Saasframe matches products by Akeneo identifier. If identifiers changed in Akeneo, duplicates can occur — use the deletion reconciliation to clean up.

Next steps​