Akeneo Shopify koppeling

Wat je tussen Akeneo en Shopify koppelt

De stroom loopt één kant op: van Akeneo naar Shopify. Akeneo is leidend voor wat een product is, Shopify toont het. De koppeling leest via de REST API van Akeneo en schrijft via de GraphQL Admin API van Shopify. De REST Admin API van Shopify is sinds 1 oktober 2024 een legacy-API.

Akeneo adresseert producten met een uuid. De identifier, meestal de SKU, is sinds november 2022 optioneel, en het oude endpoint /products geeft producten zonder identifier niet terug. De koppeling leest daarom via /products-uuid en bewaart per product het paar van Akeneo-uuid en Shopify-ID. Hoe productdata in het algemeen loopt staat op productdata koppelen.

Welk systeem is leidend, per gegeven

De laatste regel is een keuze die je vooraf maakt. Een product dat in Akeneo is verwijderd of uitgeschakeld krijgt in Shopify de status ARCHIVED. De orderhistorie blijft zo aan het product hangen.

Wat Akeneo en Shopify anders bewaren

Scope en locale tegenover één waarde met vertalingen

In Akeneo kan één attribuut meerdere waarden hebben: per locale, per kanaal, of allebei. Een kanaal, in de API scope, heeft eigen locales, valuta's en een eigen categorieboom.

{
  "identifier": "10482-BL-M",
  "family": "werkkleding",
  "parent": "10482-BL",
  "values": {
    "name": [
      { "locale": "nl_NL", "scope": "ecommerce", "data": "Werkjas Storm" },
      { "locale": "de_DE", "scope": "ecommerce", "data": "Arbeitsjacke Storm" }
    ],
    "weight": [
      { "locale": null, "scope": null, "data": { "amount": "1.2", "unit": "KILOGRAM" } }
    ],
    "material": [
      { "locale": null, "scope": null, "data": "cotton" }
    ]
  }
}

Shopify heeft per veld één waarde in de hoofdtaal van de winkel, en daarnaast vertalingen. De koppeling kiest dus per winkel één kanaal en één hoofdlocale. De andere locales gaan als vertaling mee met translationsRegister. Die mutatie vraagt per veld de translatableContentDigest: een hash van de huidige tekst in de hoofdtaal. Wijzigt de Nederlandse titel, dan verandert de digest en moeten de vertalingen opnieuw worden aangeboden. De koppeling schrijft daarom eerst de hoofdtaal, leest de nieuwe digest en schrijft daarna de vertalingen.

Een waarde met locale en scope op null geldt overal en gaat één keer mee. Ontbreekt de Duitse naam, dan is het product voor de_DE niet compleet. Het krijgt geen lege vertaling: Shopify valt dan terug op de hoofdtaal.

Optiecodes en eenheden

Een keuzeattribuut bevat in Akeneo de code van de optie, cotton, niet het label. De labels per taal staan bij de optie zelf, onder /attributes/{code}/options. De koppeling zoekt het label op in de taal van de winkel en schrijft Katoen. Een maatattribuut bevat een bedrag en een eenheid uit een meetfamilie: 1.2 en KILOGRAM. De eenheid wordt omgezet naar wat het Shopify-veld of het metafield verwacht.

Voor alles wat Shopify niet als eigen veld heeft, zijn er metafields. Per app zijn er 256 metafield-definities per soort object, een waarde is maximaal 64 KB en metafieldsSet neemt 25 metafields per aanroep aan. Een product met 60 attributen is dus 3 aanroepen. Meer over de keuzes per veld staat in wat is veldmapping.

Productmodellen tegenover opties en varianten

Akeneo bouwt varianten op met een family variant van 1 of 2 niveaus. Bij twee niveaus heeft het hoofdmodel de gedeelde attributen, het submodel de attributen per kleur, zoals de afbeeldingen, en het variantproduct de maat en de SKU. Per niveau zijn 10 assen mogelijk, 20 in totaal.

Shopify heeft twee lagen: product en variant, met maximaal 3 opties en 2.048 varianten per product. De attributen van het submodel bestaan daar niet als eigen laag. De koppeling zet ze op elke variant van die kleur.

De rekensom. Een werkjas in 12 kleuren, 8 maten en 3 lengtes is 12 keer 8 keer 3: 288 varianten op 3 opties. Dat past. Komt er een vierde as bij, pasvorm in 2 uitvoeringen, dan zijn het 576 varianten. Het aantal past nog, het aantal opties niet. Zie varianten koppelen.

De technische werkelijkheid van deze combinatie

De getallen zijn op 3 oktober 2026 nagelezen in de documentatie van Akeneo en Shopify.

Lezen uit Akeneo. 6.000 productmodellen met gemiddeld 10 varianten zijn 60.000 variantproducten. Bij 100 per pagina zijn dat 600 pagina's voor de varianten en 60 voor de modellen: 660 verzoeken. Paginering met een paginanummer stopt na het 10.000ste product met een 422. De koppeling gebruikt daarom search_after. Het aanmaken van attribuutopties heeft in Akeneo een eigen grens van 3 verzoeken per seconde.

Schrijven naar Shopify. Een mutatie kost standaard 10 punten. Vertalingen voor 6.000 producten in 3 extra talen zijn 18.000 mutaties, dus 180.000 punten. Bij 100 punten per seconde is dat 1.800 seconden: 30 minuten. Op Plus, met 1.000 punten per seconde, 3 minuten. De eerste vulling van de catalogus gaat via een bulkbewerking, die buiten het puntenbudget valt. Daarna gaan alleen gewijzigde producten mee. De rekenregels staan in Shopify API-limieten.

Alleen wat compleet is. De koppeling vraagt producten op met een filter: {"completeness":[{"operator":"=","value":100,"scope":"ecommerce"}]}, samen met een filter op updated. Een product van 80% komt niet in de winkel.

Varianten per dag. Een winkel met 500.000 of meer varianten mag er 10.000 per dag bij aanmaken; op Plus geldt die grens niet. Een uitbreiding met 60.000 varianten duurt daar 6 dagen en wordt vooraf ingepland.

Events. De oude Events API van Akeneo wordt tot 31 december 2026 ondersteund en is vervangen door het Event Platform, met maximaal 20 abonnees per PIM en 20 abonnementen per abonnee.

Wat een standaardkoppeling hier niet doet

Akeneo levert zelf een app voor Shopify en documenteert wat die wel en niet doet. Op 3 oktober 2026 stond er:

• Eén kanaal, één hoofdlocale en één hoofdvaluta per winkel, met maximaal 20 extra locales voor vertalingen.
• Verwijderen gaat niet mee. Een product dat uit Akeneo verdwijnt blijft in Shopify staan, en varianten worden nooit verwijderd.
• Bestandsattributen en categorieën gaan niet mee. Een pdf met een handleiding komt niet in Shopify, en categorieën worden geen collecties.
• Twee geplande synchronisaties per dag per scope, of 24 als synchronisatie per uur is ingeschakeld.
• Assen van het type tekst, getal of meerkeuze worden niet ondersteund als variantas.
• De Community Edition wordt niet ondersteund.

Een gebouwde koppeling volgt jouw families: welk attribuut een metafield wordt, welke as een optie, wat er gebeurt met een verwijderd product en of een handleiding als bestand meegaat. Een overzicht van de keuzes staat in PIM koppelen aan je webshop.

Als het misgaat

Een product dat blijft falen bewaart de koppeling met de oorspronkelijke inhoud, en na een correctie in Akeneo gaat het opnieuw mee. Voor livegang draait de koppeling als dry run: hij leest Akeneo en laat per product zien wat hij in Shopify zou aanmaken of wijzigen, zonder te schrijven. Daarna laat elke run per product en per veld zien wat er is veranderd.

Wij hosten en bewaken de koppeling en passen hem aan als Akeneo of Shopify een interface wijzigt; Shopify brengt elk kwartaal een nieuwe API-versie uit. De systeemkant staat op Akeneo koppeling, de platformkant op Shopify koppeling, en alle stromen op koppelingen. Verwante combinaties: Akeneo Magento koppeling en Akeneo WooCommerce koppeling. Vertel hoeveel producten, talen en families je hebt.