01 / master
Akeneo is the product content master
Catalog, attributes, options, variants, reference entities, rich media, locales and channels. The authoritative record of what each product is.
The real problem
Akeneo enriches the catalog. Shopify sells it. The work is the space between.
A locale-and-channel-scoped product model has to flatten into a flat Shopify product, variant and metafield, keep reference-entity relationships intact, and publish only what is ready. That flattening is where catalogs break.
02 / storefront
Shopify is where it goes live
Products, variants, metafields, metaobjects and Markets. Inventory, orders and pricing logic stay in the commerce and ERP layer, not the PIM.
03 / the gap
The flattening is where it breaks
A locale-and-channel-scoped product model has to flatten into a flat Shopify product, variant and metafield, keep reference-entity relationships intact, and publish only what is ready.
Our position
We built a product around that exact gap. Akeneo plugs in as a path-mapped adapter on the same platform that runs NetSuite in production.
How they connect
One direction for product content. The storefront never writes back.
Products, attributes, variants, reference entities and media are read out of Akeneo and published to Shopify. This is a PIM, not an ERP: there is no order, inventory or pricing lane through Akeneo. Akeneo is your product content master; Shopify is where it goes live.
Content master
Akeneo PIM
read · never overwritten
The platform
Makro Middleware.
map · gate · audit
The storefront
Shopify Plus
where products go live
Product content: Akeneo → Makro Middleware → Shopify, one way
Orders, inventory, pricing: in the commerce or ERP layer, not the PIM
GraphQL readA product with its values, family, categories and reference-entity links in one round trip. The read endpoint at
graphql.sdk.akeneo.cloud aggregates the GET REST calls, requires a REST token, runs read-only, and is capped at 500 requests per 10 seconds per PIM. No asset binaries.Akeneo → MKEvents API webhooksAkeneo announces a change instead of being polled. Near-real-time on SaaS, acknowledged in under 500ms, then queued durably. The API guarantees no retry and no ordering, so the platform owns the durability and dedupes by the
updated timestamp.Akeneo → MKREST writes · deltaIncremental reads by the
updated property, cursor-paged for large catalogs. A 50,000-item catalog with 12 real edits syncs 12 records. Bulk PATCH caps at 100 resources, paging at 100 per page, with search_after beyond the offset ceiling.Akeneo → MKOAuth 2.0 · ConnectionServer-to-server auth on a dedicated least-privilege Connection. A password-grant token from
POST /api/oauth/v1/token, scoped to a read-only API user role. A missing ACL returns HTTP 403, never silent data.handshakeREST reconciliationThe periodic poll Akeneo itself mandates as the backstop to the Events API. A scheduled pass compares the PIM against what is live on Shopify and replays anything the event path missed, keyed on the immutable product
uuid, not the renameable SKU.Akeneo → MKThe console
This is not a connector. It is something you operate.
Every publish, every failure, every reconciliation is visible. This is the same Makro Middleware console your team would watch in production. Move through the views.
console.makro.agency / northbridge-industrial / publish
live
Sync Monitor
Sync Monitor
Dead Letter Queue
Observability
Entity Key Map
Schedules
Channel & Locale Routing
Records / 24h ▲
48,210
across 9 entities
Queue depth
3 pending
2 retrying · 1 review
Avg latency
1.2s
event → Shopify
Last reconcile
04:00
0 drift detected
Activitylive · last 60s
Throughputrecords / hr
In queue
3
of 48,210 processed
Auto-retrying
2
transient · rate-limit
Needs review
1
permanent
Resolved / 24h
41
38 auto · 3 manual
Dead Letter Queuenothing is dropped in silence
| Time | Entity | Error class | Attempts | Next | Action |
|---|---|---|---|---|---|
| 08:13:04 | product · SKU-10288 | PERMANENT · validation | 3 / 3 | held | Inspect |
| 07:55:22 | reference · brand bouroullec | TRANSIENT · timeout | 2 / 5 | 09:50 | Retry now |
| 06:40:11 | attribute options · size | RATE_LIMIT · 3 req/s | 1 / 5 | paced | Inspect |
Publish volume7-day · records
Circuit breakersper endpoint
Akeneo · GraphQLlast trip · never
closedAkeneo · REST writeslast trip · 3d ago
closedShopify · Admin APIlast trip · never
closedUptime · 90 dayserror rate 0.03%
product · Northbridge Cabinetentity_key_map
akeneo uuid8f2a-c1d9-4e07-44b0
skuSKU-004182
shopify gidgid://shopify/Product/61…
completeness100 · en_US · ecommerce
updatedunchanged since 04:00
→ decision: SKIP · already in sync
Every record is keyed on the immutable Akeneo uuid, never the renameable SKU. The middleware reads this row before every write and decides create, update, or skip.
Rename the identifier in Akeneo and the mapping still holds on Shopify. This is what stops duplicate products and orphaned variants before they reach your storefront.
The publish gate is per-(channel, locale) completeness = 100. A product that is not complete for the bound channel and locale is held, not half-published.
Active schedules
7
all workflows enabled
Runs today
96
0 failures
Next run
09:46
delta product read
Nightly batch
01:00
full catalog · 48,210
Workflowstenant · northbridge
Product delta readREST · updated > watermarkevery 15 min✓ 09:38 · 142 recordsnext 09:53Run now
Event consumerEvents API · <500ms acknear real-time✓ 09:41 · 6 eventsstreamingPause
Reference entitiesN+1 hydrate · cachedhourly✓ 09:00 · 38 recordsnext 10:00Run now
Attribute optionsdedicated ≤3 req/s laneevery 15 min✓ 09:40 · 24 optionsnext 09:55Run now
Asset Manager mediashare_link · web variantevery 30 min✓ 09:42 · 11 assetsnext 10:12Run now
Full catalog batchREST · search_after cursornightly · 01:00✓ 01:00 · 48,210 recordsnext 01:00Run now
Daily reconciliationPIM vs Shopify vs key mapdaily · 04:00✓ 04:00 · 0 driftnext 04:00Run now
Akeneo channelecommerce
category treemaster_catalog
localesen_US · fr_FR
currenciesUSD · EUR
value sliceen_US + ecommerce
eligiblein tree · publish
en_US→US store · en✓
fr_FR→EU store · fr✓
USD price→Markets · US✓
EUR price→Markets · EU✓
reference brand→metaobject✓
channel read first · category tree gates eligibility
Shopify targetUS store · Markets
productgid://Product/61…
marketUnited States
title (en)from en_US value
referencebrand metaobject
statuspublished
Publish journeyproduct → Shopify · diff before publish
09:42:04event received→
09:42:04HMAC ✓ · dedup ✓→
09:42:05completeness 100 ✓→
09:42:05value slice selected→
09:42:06diff vs live→
09:42:07published to Shopify
drag, scroll, or use the tabs
Inside the platform
How we build it. Feature by feature.
Ten engineered subsystems sit behind the publish. Each one is the reason a custom build survives a catalog the native app and a connector cannot model. Drag through them.
01 / 10
When a record fails
Integrations are judged by how they fail. Follow one failed publish.
An attribute-option write hits Akeneo's 3 req/s ceiling. Colour carries the verdict: amber is sorted, teal retries, red is held, green replays. Nothing disappears into a log file.
01
It arrives
An attribute-option write hits Akeneo's 3 req/s ceiling and comes back HTTP 429 with a Retry-After. Instead of disappearing into a log, it enters the pipeline.
captured→ 02
It gets classified
Every failure is sorted before anything is retried, so a bad record never loops forever.
classified→ 03
Rate-limit paces
The 429 routes to a dedicated ≤3 req/s lane, honors the Retry-After, and clears itself. Transient timeouts retry with backoff.
→ 04
Permanent is held
A validation failure, an incomplete product, or a missing reference routes straight to the dead-letter queue for review. It is never retried blindly or lost.
held for review→ 05
You replay it
Fix the cause, replay from the queue. The periodic REST reconciliation Akeneo itself mandates catches anything the lossy event path missed.
replayed · reconciledThe failure modes no vendor page admits
Where the native app and off-the-shelf connectors break.
The official Akeneo App for Shopify is a clean one-way publisher for the happy path. It is SaaS and not customizable, and it stops fitting at the same documented walls every time. A custom middleware layer is built to handle all of them, explicitly.
No metaobject or metafield definitions
The app does not create metaobject or metafield definitions for you. You map PIM attributes to definitions that already exist, only compatible types map, and the app ignores the akeneo namespace. Reference-entity-to-metaobject depth is custom work.
250 metafields, first ~10,000 attributes
A hard ceiling of 250 metafield definitions per store, mapped from the first ~10,000 eligible PIM attributes, at product and variant level only. Complex catalogs hit these walls fast and need a deliberate attribute and metafield architecture.
→ metafield architecture scoped to the catalogOne locale per store
The native app allows only one language and locale per Shopify store. Multi-store is supported, one locale each. A true multi-market storefront needs per-store channel feeds or custom per-locale and per-market routing through Shopify Markets.
→ channel-and-locale routing into Shopify MarketsCategories are not collections
An Akeneo category tree is hierarchical with unlimited nesting; Shopify collections are flat. The app syncs the category label to a tag or metafield, not a native collection. Deterministic tree-to-smart-collection logic is custom.
→ tree mapped to smart-collection rulesThe variant-model mismatch
Akeneo expresses variants via product models and family variants, up to 2 model levels and up to 5 axis attributes. Shopify is fixed at product, up to 3 options, variants. Text and Number attributes are not supported as Shopify variant axes. The hierarchy has to be flattened.
→ family-variant hierarchy flattened to optionsOne-way only, no deletion, lossy events
The app is unidirectional, Akeneo to Shopify, and cannot delete products in Shopify. The Events API guarantees nothing: no retry, a 2-hour discard window, no ordering. Reliable real-time requires middleware that owns the durability.
→ deletion handling + durable, deduped event queueClaims you can check
What you will hear, and what the docs actually say.
Every reality below is verified against Akeneo's own developer or help docs, or a named vendor source. This is the difference between a team that read the marketing and a team that shipped against the documentation.
01
The claim"The native Akeneo App for Shopify handles everything. Install it and you're integrated."
The realityThe first-party app is a clean one-way, no-code publisher for the happy path, but it is SaaS and not customizable: products sync using the PIM structure as-is. The moment you need a transformed product shape, governed publishing, deletion, or more than one locale per store, it stops fitting.
02
The claim"It's a two-way integration. Shopify changes flow back to Akeneo."
The realityNo. The app is unidirectional, Akeneo to Shopify only. Shopify-to-Akeneo synchronization is not supported. It syndicates product content; it does not sync orders, customers, or inventory levels, and it cannot delete products in Shopify. Those flows live in the commerce or ERP layer.
03
The claim"Community Edition is fine, the native app supports it."
The realityCommunity Edition is not supported by the native app. Reference entities and the Asset Manager, the rich brand and media objects, are Enterprise and Serenity only. A Community build is materially different and usually needs a third-party connector or custom middleware. Scope the edition before quoting.
04
The claim"Akeneo categories become Shopify collections automatically."
The realityNo. Categories are not synced as native collections. An Akeneo tree is hierarchical with unlimited nesting; Shopify collections are flat. The app syncs the category label to a tag or metafield, which can drive a smart collection. Deterministic tree-to-rule logic is custom work.
05
The claim"Just map all your PIM attributes and metafields to Shopify."
The realityHard ceilings apply: maximum 250 metafield definitions per store, mapping from the first ~10,000 eligible attributes, and the app does not create metaobject or metafield definitions for you. You map to definitions that already exist, only compatible types map, and the app ignores the
akeneo namespace.06
The claim"Multi-language is built in, one store covers all your locales."
The realityThe native app allows only one language and locale per store. Multi-store is supported, one locale each. A true multi-market storefront needs per-store channel feeds or custom per-locale and per-market routing through Shopify Markets.
07
The claim"Akeneo webhooks give you reliable real-time sync."
The realityThe Events API is deliberately lossy: no retry ever, events older than 2 hours are discarded, a 500ms acknowledgement budget, no ordering guarantee, only 3 subscriptions, and it is SaaS-only and not available for Apps. Akeneo itself instructs you to reconcile via periodic REST polling. Reliable real-time requires middleware.
08
The claim"Bulk-load the catalog as fast as your code can call."
The realityAkeneo throttles hard. General cap is 100 req/s per PIM instance, but only 3 req/s for creating or updating attribute options, the tightest REST limit and the #1 source of 429s. Concurrency is 4 per connection, 10 per instance; bulk writes cap at 100 records per PATCH. Over-limit returns HTTP 429 with a
Retry-After you must honor.09
The claim"Akeneo's variant model maps straight onto Shopify variants."
The realityThe two models are shaped differently. Akeneo uses product models and family variants, up to 2 product-model levels and up to 5 axis attributes; Shopify is fixed at product, up to 3 options, variants. The hierarchy has to be flattened, and Text and Number attributes are not supported as Shopify variant axes.
10
The claim"Brands, designers, and collections just become metafields."
The realityThey shouldn't be flattened. Reference entities are first-class records with their own attributes and lifecycle, and they map naturally onto Shopify metaobjects. But the product payload returns only the record code plus a
reference_data_name; hydrating the real record needs a second API call, an N+1 step to budget and cache. Reference entities are EE and Serenity only.11
The claim"Every attribute value is just a value you copy across."
The realityEvery Akeneo attribute value is an array scoped by
locale and scope (channel), up to one entry per (channel, locale) couple. The mapper must select the correct entry, for example en_US plus ecommerce, and read the channel definition first, because the channel's single bound category tree decides which products are even eligible.12
The claim"A StrikeTru or WebKul connector covers everything the native app misses."
The realityThey widen edition coverage and add mapping, but remain generic catalog pipes whose governance stops at job-level retry, error logs, and chat alerts, not approval gates, diff-before-publish, or per-market release. StrikeTru is one-way, priced per SKU tier (a dated range around $149–$299/mo as of mid-2025); WebKul installs into the Akeneo runtime. Neither owns the governed-publishing control plane.
13
The claim"Pick whichever sync, they all do the same thing."
The realityThere are four real paths: the native app for clean publishing within the limits, a third-party connector when you need transformation the app can't express, an iPaaS for broad multi-system orchestration, and middleware when you need governed publishing, deletion, more than one locale per store, or near-real-time event-driven sync. The choice is an architecture decision, not an app install.
14
The claim"We can keep your old SKUs as the join key forever."
The realityKey on the immutable product
uuid (the /products-uuid endpoint), not the SKU a merchant can rename. The native app's pre-existing-catalog matching stores a link keyed by PIM UUID plus Shopify product ID. Idempotent upserts ride the UUID; the SKU is the human-facing match key, not the durable identity.The decision guide
Four ways to connect Akeneo and Shopify, and when each is right.
There are four ways to connect Akeneo to Shopify: the official Akeneo App, a third-party connector such as StrikeTru, an iPaaS platform such as Alumio or Patchworks, and a custom-built middleware integration. The right choice depends on edition, catalog complexity, locale footprint, and how much publishing control you need.
Option 01
Native Akeneo App
Akeneo's own SaaS app, no-code, one-way. Competent on the happy path, within documented limits.
- mappingfixed, PIM structure as-is
- localeone per store
- metafields250 defs, defs must pre-exist
- syncmax 2 scheduled runs/day
Right for straightforward one-way PIM-to-Shopify publishing within the limits, on a supported edition.
Option 02
Third-party connector
StrikeTru, WebKul and similar. Wider edition coverage and configurable mapping the native app can't express.
- mappingconfigurable, transformation
- governancejob-level retry + logs
- pricingper-SKU tier, dated range
- editionbroader than native app
Right for when you need mapping or transformation and broader edition coverage, but not a governed-publishing control plane.
Option 03
iPaaS platform
Alumio, Patchworks and similar. Subscription middleware on a shared platform for broad multi-system orchestration.
- mappingconfigurable, template-bound
- tenancyshared platform
- pricingannual fee, grows with volume
- PIM depthreference entities an afterthought
Right for orchestrating many systems where the PIM-specific depth fits a generic flow template.
Option 04 our build
Custom middleware
Built around your exact catalog model and publishing rules, owned by you, operated with a support agreement. Where Plus, multi-locale and B2B catalogs end up.
- mappingyour model, reference-to-metaobject
- tenancysingle-tenant, isolated
- recovery7 failure classes, DLQ, replay
- scopemulti-locale, deletion, near-real-time
Right for governed publishing, multi-locale-per-store routing, reference-entity-to-metaobject depth, deletion handling, or near-real-time event-driven sync the native app and connectors cannot model.
How long it takes
Timeline by scope, not a contact-us wall.
An Akeneo to Shopify Plus build lands in one of three bands depending on edition, catalog complexity, locale and market footprint, and how many of the break points above are in play.
Band 01 · foundation
3–5 weeks
single store · one channel and locale
- Products, options and variants one way, Akeneo to Shopify
- Attribute-to-field and metafield mapping, definitions created at build
- Completeness-gated publish keyed on the immutable uuid
- Dead-letter queue, daily reconciliation, the console
Band 02 · enriched catalog
6–9 weeks
reference entities · rich media
- Everything in foundation, plus reference entities to metaobjects
- N+1 hydration with caching, associations as reference metafields
- Asset Manager media via share_link and web variants
- Category tree mapped to smart-collection rules
Band 03 · multi-market
10–14 weeks
multi-locale · markets · B2B
- Everything in enriched, plus per-locale and per-market routing
- Channel-and-locale value selection into Shopify Markets
- Near-real-time Events API sync with the reconciliation backstop
- Deletion and lifecycle handling, B2B catalog segmentation
Cost · scoped per build
We price an Akeneo integration as an engineering engagement: a build with a support agreement, not a per-record meter or a platform seat that renews forever. For market context, custom PIM-to-storefront builds commonly run from the low tens into six figures, and a fixed-fee connector that lists around $149–$299/mo carries its own limits. Your exact figure is scoped to the band and the break points in play, and we put it in writing before anything starts.
Security posture
Built to pass your review, and your PIM admin's questions.
Credentials never in plain config
Akeneo and Shopify secrets are held as encrypted fields, isolated per tenant and rotatable without downtime. The Connection password is shown once and never sits in plaintext, anywhere.
AES-256-GCMInbound traffic is verified
Every Akeneo event is verified by its HMAC-SHA256 signature over the timestamp and body before it is trusted, then deduplicated, so a replayed event cannot publish twice.
X-Akeneo-Request-SignatureLeast-privilege access to Akeneo
Auth runs as an OAuth 2.0 password-grant Connection on a dedicated, read-only API user role scoped to exactly what the integration touches. A missing ACL returns HTTP 403, never silent partial data.
OAuth 2.0 ConnectionEverything is on the record
An append-only audit trail logs every operation, source-tagged, so you can prove exactly which value slice published, when, and why a product was held.
append-only auditThe questions we have already answered
Frequently asked questions about Akeneo and Shopify.
The details that separate a team that read the docs from a team that shipped against them. Open any one.
01Can Akeneo integrate with Shopify?+
Yes. Akeneo became a Shopify Premier Partner in June 2025 and offers an official Akeneo App for Shopify, available on both the Shopify and Akeneo app stores. It connects Akeneo PIM to a Shopify or Shopify Plus storefront and syndicates product data.
02Is the Akeneo–Shopify sync two-way?+
No. The official Akeneo App for Shopify is one-way: it pushes product data from Akeneo to Shopify. Shopify-to-Akeneo synchronization is not supported. Orders, customers, and inventory are not handled by the app and are typically integrated through your ERP or commerce layer.
03What data does the Akeneo app sync to Shopify?+
Product content only: products, product models, variants and options, attributes, media (images, videos, PDFs via Asset Manager), reference entities, and associations such as cross-sell and up-sell. It does not sync orders, inventory levels, or customers, and it cannot delete products in Shopify.
04How often does Akeneo sync to Shopify?+
You can sync manually on demand or on a schedule (daily, weekly, or monthly). The native app caps scheduled runs at two synchronizations per day and runs only one at a time, with full imports (entire catalog) and delta imports (only changed records). Schedules are set in UTC. A custom middleware build can sync near-real-time via Akeneo's Events API plus a reconciliation backstop.
05What are the limits of the Akeneo Shopify app?+
Up to 250 metafield definitions per store; mapping from the first ~10,000 eligible PIM attributes; metafields at product and variant level only; one language and locale per store; Community Edition not supported; categories synced as tags/metafields, not native collections; and the app is SaaS and not customizable.
06Native Akeneo app vs a connector vs middleware, which should I use?+
Use the official app for straightforward one-way PIM-to-Shopify publishing within its limits. Use a third-party connector like StrikeTru when you need advanced mapping, transformation, or broader edition coverage. Use custom middleware when you need governed publishing, multi-locale-per-store routing, reference-entity-to-metaobject depth, deletion/lifecycle handling, or near-real-time event-driven sync.
07Can one Akeneo instance feed multiple Shopify stores?+
Yes. A single Akeneo instance can publish to multiple Shopify stores, with each export job configured for its own channel, locale, and currency, which is what makes Akeneo a fit for multi-region and B2B/multi-entity setups.
08Do I need an agency to integrate Akeneo with Shopify?+
Not for a basic product-data push, the native app is no-code. You need an implementation partner when the project involves governed publishing, multi-store or multi-locale routing beyond one locale per store, attribute/metafield architecture beyond the native limits, reference-entity-to-metaobject modeling, or migration of an existing catalog. Makro Agency builds exactly that custom middleware layer.
The framework underneath
A proven platform. Akeneo is the next adapter on the wall.
Every system sits behind the same contract: authenticate, fetch master data, push the target, validate, report. The platform runs NetSuite in production today. Akeneo is a registered target on that same framework, its path fully mapped to Akeneo's REST, GraphQL, Events and Connection APIs.
We say this plainly: the credibility is a real platform and a precisely understood Akeneo path, not a decade of Akeneo traffic. That distinction is exactly what your architect can verify, which is why we lead with it.
adapter contractbase.ts
01authenticate()OAuth 2.0 Connection
02fetchMasterData()GraphQL / REST
03pushContent()Shopify Admin
04validate()completeness gate
05report()audit + status
NS
NetSuite
ERP adapter
AK
Akeneo
PIM adapter
D3
Dynamics 365 F&O
ERP adapter
The engineering standard
Claims you can check.
The platform's standard is the same on every adapter. These are the numbers in the repository, not rounded for a slide.
1,756
Test suiteAutomated tests across 139 suites, run on every change. No code reaches your production data without passing them.
85%
Coverage gate enforced before any deploy.
39
End-to-end browser tests across Chromium, Firefox and WebKit.
7
Failure classes, each with its own pre-decided policy.
0
Credentials stored in plaintext, anywhere, ever.
Platform proof
Where the platform proves itself. For Clarius, Makro built a unified account page integrating NetSuite ERP, Salesforce CRM and Shopify Plus, with Shopify Flow feeding order data into NetSuite, reported to save $100,000+ a year in third-party app fees. That is an ERP, CRM and storefront unification case, not a PIM case, and we frame it as one. Akeneo on this platform is path mapped: the architecture is fully understood and documented against Akeneo's own developer docs, sold on the platform that runs NetSuite in production today. We do not claim a live Akeneo deployment.
Bring your PIM lead and your catalog model. We will walk the platform, not a deck.
A real conversation about your Akeneo edition, your channel and locale model, and the three sharp questions you already have.