WooCommerce REST API koppelen: sleutels, eisen en de eerste aanroep

Wat je nodig hebt voordat de koppeling kan praten

De REST API zit in WooCommerce zelf; er is geen aparte plugin nodig. De huidige versie heet wc/v3 en staat op https://jouwshop.nl/wp-json/wc/v3. Vier dingen moeten in orde zijn, nagelezen in de documentatie van de REST API op 3 oktober 2026:

In de praktijk liggen de ondergrenzen veel hoger: WooCommerce 11.1.2, de versie van 22 september 2026, vraagt WordPress 7.0 en PHP 7.4. Een winkel die zo ver achterloopt dat wc/v3 ontbreekt, heeft een update nodig voordat er iets te koppelen valt.

Sleutels aanmaken en het juiste recht kiezen

Een sleutel maak je onder WooCommerce, Instellingen, Geavanceerd, REST API. Je kiest een WordPress-gebruiker en een recht: Lezen, Schrijven of Lezen/Schrijven. Drie regels uit WooCommerce's eigen documentatie bepalen hoe je dat doet:

• Het Consumer Secret wordt één keer getoond. Wie de pagina verlaat zonder het te kopiëren, maakt een nieuwe sleutel.
• De sleutel volgt de rollen en rechten van de gekozen gebruiker. Een sleutel met Lezen/Schrijven op een gebruiker die geen orders mag zien, leest geen orders.
• Wordt de gebruiker verwijderd, dan werkt de sleutel niet meer. Sleutels gaan niet over op een andere gebruiker.

Maak de sleutel daarom aan op een eigen gebruiker voor de koppeling, niet op het account van een medewerker die ooit vertrekt. Welk recht per stroom nodig is:

Zodra één stroom terugschrijft, wordt het Lezen/Schrijven. Meer sleutels dan nodig maken het lastiger om bij te houden welke nog in gebruik is; één sleutel per koppeling is overzichtelijk. Een app kan ook zelf een sleutel aanvragen via /wc-auth/v1/authorize, met scope op read, write of read_write en een callback_url die over HTTPS moet lopen. De gebruiker geeft daarvoor in de browser toestemming, en de sleutels gaan in een apart verzoek naar dat adres.

De eerste aanroep en wat er terug kan komen

Over HTTPS gaan de Consumer Key en het Consumer Secret mee als gebruikersnaam en wachtwoord (basic authentication). De eerste test is één order:

GET /wp-json/wc/v3/orders?per_page=1 HTTP/1.1
Host: shop.bakkerinstallatie.example
Authorization: Basic Y2tfNGY...ZWQ=

Komt er een order met id, number en billing terug, dan werken sleutel, permalinks en rechten. Komt er een fout, dan zegt de combinatie van status en code waar het zit:

Zo ziet de 404 eruit als de permalinks op Eenvoudig staan:

{
  "code": "rest_no_route",
  "message": "No route was found matching the URL and request method",
  "data": { "status": 404 }
}

Voor de "Consumer key is missing" documenteert WooCommerce een uitweg: de sleutel en het secret als consumer_key en consumer_secret in de URL. Dat werkt, maar dan staan ze in de toegangslogs van de server. Wij laten liever de header doorgeven. Over HTTP vraagt WooCommerce OAuth 1.0a met een handtekening per verzoek, en weigert het verzoeken met een tijdstempel die meer dan 15 minuten afwijkt. Loopt de klok van de server van de koppeling meer dan 15 minuten uit de pas, dan krijgt elk verzoek een 401.

Orders ophalen in pagina's van 100

Een lijst komt standaard terug in pagina's van 10. Met per_page vraag je er meer, tot 100 per pagina in de REST-laag van WordPress. Het totaal staat in de headers X-WP-Total en X-WP-TotalPages, en de link naar de volgende pagina in de Link-header.

Een rekenvoorbeeld. Bij de start haalt de koppeling de orderhistorie op: 18.400 orders.

Duurt een pagina van 100 op jouw hosting 2 seconden (een aanname; meet het op je eigen server), dan kost de eerste import 184 x 2 = 368 seconden, ruim 6 minuten. Met pagina's van 10 zou hetzelfde 3.680 seconden zijn, ruim een uur, en tien keer zoveel verzoeken die de shop voor bezoekers vertragen.

Na de eerste import vraagt de koppeling alleen wat gewijzigd is, met modified_after. Twee instellingen voorkomen dat er orders tussendoor glippen:

• dates_are_gmt=true. Zonder die parameter leest WooCommerce de datum als tijd van de site. Stuurt de koppeling een tijd in UTC zonder die parameter, dan ligt de grens in de zomertijd 2 uur verkeerd. Ligt hij te vroeg, dan komen orders dubbel binnen; ligt hij te laat, dan mist de ronde de wijzigingen van 2 uur. De order heeft daarom ook twee datumvelden: date_modified in de tijd van de site en date_modified_gmt in GMT. Zie datums en tijdzones.
• Een vaste sortering. Standaard sorteert de API aflopend op datum. Komt er tijdens het bladeren een order bij, dan schuift alles een plek op en verschijnt dezelfde order op twee pagina's. Met orderby=modified en order=asc komen nieuwe wijzigingen achteraan.

Voor wijzigingen tussen twee rondes heeft WooCommerce webhooks, die op de achtergrond via wp-cron worden verstuurd; hoe je daar een controleronde naast zet staat in wat is een webhook.

Versies, Legacy API en HPOS

Er zijn vier generaties van de API in omloop:

Een koppeling of webhook die nog op de Legacy API draait, stopt bij een update naar 9.0 of hoger tenzij die plugin geïnstalleerd is. Dat is een van de eerste dingen die we nakijken als we een bestaande koppeling vervangen.

Sinds WooCommerce 8.2 (oktober 2023) staat High-Performance Order Storage standaard aan bij nieuwe installaties. Orders staan dan in eigen tabellen zoals wp_wc_orders. Voor de REST API verandert er niets. Een script dat orders rechtstreeks met SQL uit de tabel met berichten leest, vindt na de overstap niets meer en meldt geen fout: het ziet nul nieuwe orders.

Wat betekent dit voor je koppeling?

De verbinding zelf is een sleutel en een adres. Het werk zit in wat er omheen hoort: een eigen gebruiker met precies de rechten die de stromen nodig hebben, ophalen in pagina's van 100 met een vaste sortering en GMT-datums, een tempo dat de shop niet vertraagt, en een controleronde naast de webhooks. Dat bouwen wij als onderdeel van de koppeling, en daarna draaien en bewaken we hem. Elke ronde staat met zijn verzoeken en antwoorden in de log van het dashboard.

Wat we verder met WooCommerce koppelen, van btw in vier decimalen tot gastbestellingen, staat op de pagina over de WooCommerce koppeling. De orderstroom naar ERP en boekhouding staat bij orders, klanten en verzending. Vertel welke WooCommerce-versie en welke systemen je gebruikt, dan kijken we welke stromen met welke rechten nodig zijn.