Akeneo PIM development sits at the intersection of product data modeling, Symfony engineering, and ecommerce operations. Brands hire teams not only to “install Akeneo,” but to encode how products are enriched, approved, localized, and published across Shopify, Magento, Amazon, marketplaces, and ERP systems. This Akeneo PIM development guide explains how Spygar approaches custom Akeneo work so catalogs stay accurate, integrations stay resilient, and upgrades stay boring.
Great Akeneo development is invisible at upgrade time—custom code that survives version bumps is the real deliverable.
Understand the Akeneo platform before you customize
Akeneo Community Edition and Enterprise Edition share a product-centric domain model: families, attributes, attribute groups, categories, products, product models, variants, associations, and media. On top of that, Akeneo runs asynchronous jobs for imports, exports, mass edits, and completeness recalculation. Development work should respect these seams. If you fight the model—stuffing channel-specific copy into the wrong attribute type, or bypassing jobs for heavy writes—you create technical debt that surfaces as slow grids, failed exports, and painful migrations.
- Map business nouns to Akeneo concepts before writing a line of bundle code
- Prefer attributes, reference entities (EE), and rules over ad-hoc database columns
- Use Akeneo jobs for bulk work so the UI stays responsive under catalog load
- Plan localization and channel requirements during modeling, not after go-live
Upgrade-safe custom development patterns
The most expensive Akeneo mistake is patching vendor code. Use Symfony bundles, event subscribers, service decoration, and Akeneo extension points so custom behavior travels cleanly across minor and major releases. Keep business logic in your own namespaces. Document every override. When you must change UI screens, isolate front-end assets and avoid copying entire vendor templates unless you have a maintenance plan.
For connectors and integrations, treat Akeneo as the system of record for product content and assets—not for inventory, pricing engines, or order state unless your architecture explicitly requires it. Clear ownership boundaries make Akeneo API integrations easier to test and safer to scale. Always start from the official Akeneo REST API reference index when designing custom connectors.
API building blocks every Akeneo developer should know
Custom bundles often wrap the same REST calls Magento/Shopify connectors use. Auth + UUID product upserts cover most write paths; list/get with completeness covers most read paths. For file-based or job-based custom connectors (notify-after-export, new formats), follow our create custom Akeneo connector guide—aligned with the official docs. Deep REST parameter/response examples live in the API integration guide—here are the two calls developers hit first:
/api/oauth/v1/token
Official docs
Get an authentication token
Exchange connection credentials for a Bearer access token. No prior Bearer auth is required for this call.
Headers
Content-Type: application/json (or application/x-www-form-urlencoded)Authorization: Basic {base64(client_id:client_secret)}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
username |
body | string | Yes | PIM connection username |
password |
body | string | Yes | PIM connection password |
grant_type |
body | string | Yes | Must be password |
Example request
curl -X POST "https://YOUR_PIM_HOST/api/oauth/v1/token" \
-H "Content-Type: application/json" \
-H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-d '{
"username": "your_connection_username",
"password": "your_connection_password",
"grant_type": "password"
}'Response — 200 OK
Returns an authentication token used as Authorization: Bearer on later calls.
{
"access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
"expires_in": 3600,
"token_type": "bearer",
"scope": null,
"refresh_token": "M3FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
}Response — 400 Bad Request
Malformed JSON or invalid request framing.
{
"code": 400,
"message": "Invalid JSON message received"
}Response — 422 Unprocessable Entity
Validation failed (wrong grant_type, bad credentials shape, etc.).
{
"code": 422,
"message": "Property \"grant_type\" expects a valid grant type. Check the expected format on the API documentation."
}/api/rest/v1/products-uuid/{uuid}
Official docs
Get a product (UUID)
Fetch one product by immutable UUID. Use query flags to include completeness, quality scores, or root parent.
Headers
Authorization: Bearer {access_token}Accept: application/json
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
uuid |
path | string | Yes | Product UUID |
scope |
query | string | No | Filter scopable values |
locales |
query | string | No | Filter localizable values |
attributes |
query | string | No | Limit returned attributes |
with_attribute_options |
query | boolean | No | Include option labels |
with_quality_scores |
query | boolean | No | Include quality scores |
with_completenesses |
query | boolean | No | Include completenesses |
with_root_parent |
query | boolean | No | Include root parent model code |
Example request
curl -G "https://YOUR_PIM_HOST/api/rest/v1/products-uuid/25566245-55c3-42ce-86d9-8610ac459fa8" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode 'scope=ecommerce' \
--data-urlencode 'locales=en_US' \
--data-urlencode 'with_completenesses=true'Response — 200 OK
Product standard format.
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": ["summer_collection"],
"groups": [],
"parent": null,
"values": {
"sku": [{"data": "top", "locale": null, "scope": null, "attribute_type": "pim_catalog_identifier"}],
"name": [
{"data": "Top", "locale": "en_US", "scope": null, "attribute_type": "pim_catalog_text"}
],
"description": [
{"data": "Summer top", "locale": "en_US", "scope": "ecommerce", "attribute_type": "pim_catalog_textarea"}
]
},
"created": "2026-01-05T10:00:00+00:00",
"updated": "2026-03-01T12:30:00+00:00",
"completenesses": [
{"scope": "ecommerce", "locale": "en_US", "data": 100}
]
}Response — 404 Not Found
UUID does not exist (or not visible under permissions).
{
"code": 404,
"message": "Product \"25566245-55c3-42ce-86d9-8610ac459fa8\" does not exist."
}Jobs, queues, and observability
Real catalogs are big. Imports of tens or hundreds of thousands of SKUs, nightly channel exports, and completeness recalculations belong in jobs with logging, retries, and dead-letter handling. Surface job status to business users. Alert on repeated failures. Without observability, “Akeneo is slow” becomes a vague complaint instead of a measurable queue backlog or a missing index.
- Instrument import/export jobs with duration, error counts, and sample failing SKUs
- Keep idempotent writers so a replayed job does not duplicate or corrupt data
- Separate validation failures (business) from infrastructure failures (ops)
- Load-test completeness and grid queries with production-like volume
Testing and delivery discipline
Akeneo custom development should ship with fixtures that represent your hardest product families—variant trees, multi-locale requirements, asset-heavy SKUs, and incomplete records. Automate smoke tests for login, product save, import job success, and one channel export. Pair that with a documented upgrade runbook: backup, dependency matrix, migration scripts, regression on critical connectors, and a rollback path.
When to choose CE vs EE for development scope
Community Edition can power strong mid-market catalogs when modeling and connectors are designed carefully. Enterprise Edition unlocks governance features—rules engines, workflows, advanced asset management, and reference entities—that reduce custom code for large brand teams. Spygar helps clients decide where licensed EE capability is cheaper than building equivalents, and where custom Akeneo development still creates durable advantage.
How Spygar delivers Akeneo PIM development
We start with product modeling workshops, then design connectors, enrichment UX, and operational jobs against measurable outcomes: faster time-to-market, fewer channel rejections, and higher catalog completeness. Whether you need a greenfield Akeneo build, a connector to Magento or Shopify, or hardening of an existing instance, we treat maintainability as a first-class requirement—because Akeneo only creates value when merchandisers trust it every day.
