Shopify API limieten: punten, emmers en bulk operations

Hoe Shopify een koppeling begrenst

Shopify begrenst elke app per winkel. Een koppeling met een ERP, magazijn of PIM gebruikt de Admin API, en die bestaat in twee vormen met elk een eigen telling.

De GraphQL Admin API telt kostenpunten. Elk veld in een query heeft een prijs in punten, en de app heeft een emmer die met een vaste snelheid per seconde bijvult. De REST Admin API telt verzoeken: elk verzoek is er één, wat het ook oplevert. Shopify noemt REST sinds 1 oktober 2024 legacy. Wij bouwen een Shopify koppeling daarom op GraphQL.

Beide werken met een lekkende emmer. Een korte piek boven het tempo lukt zolang er ruimte in de emmer is; over een langere ronde telt alleen het tempo. De emmer hoort bij één app op één winkel. Een tweede app in dezelfde winkel heeft een eigen emmer, maar alles wat jouw koppeling doet deelt er één.

De limieten per abonnement

Nagelezen op 3 oktober 2026 in de documentatie van Shopify over GraphQL-limieten en de pagina over de REST Admin API.

Shopify publiceert per abonnement het bijvultempo, niet de grootte van de emmer. Die staat in elk antwoord, in throttleStatus.maximumAvailable.

Daarnaast gelden grenzen die op elk abonnement hetzelfde zijn:

Shopify schrijft er zelf bij dat het de limieten tijdelijk kan verlagen om het platform te beschermen. Een koppeling die precies op het gepubliceerde tempo draait, wordt op zulke dagen afgeknepen.

Wat een query kost

Shopify rekent standaard 0 punten voor een enkel veld (een SKU, een prijs, een status), 1 punt voor een object (een variant, een inventory item) en 10 punten voor een mutatie. Een lijst kost naar het aantal dat je opvraagt met first of last.

Een pagina van 250 varianten met per variant het bijbehorende inventoryItem vraagt zo ruim 500 punten aan; in het diagram hieronder 502. Vraag je 250 producten met elk 100 varianten op, dan vraag je 25.000 objecten. Dat is ver boven de 1.000 punten van één query en Shopify weigert hem voordat hij draait.

Shopify rekent twee keer. Vooraf moet de gevraagde prijs (requestedQueryCost) in de emmer passen. Achteraf krijgt de app het verschil terug met wat de query echt kostte (actualQueryCost). Een pagina die 250 varianten vraagt en er 30 terugkrijgt, kost uiteindelijk naar die 30.

THROTTLED in plaats van 429

Raakt de emmer leeg, dan antwoordt de GraphQL Admin API niet met een 429. Shopify's pagina met statuscodes zegt het letterlijk: de GraphQL Admin API geeft 200 OK en zet de fout in de body.

{
  "errors": [
    { "message": "Throttled", "extensions": { "code": "THROTTLED" } }
  ],
  "extensions": {
    "cost": {
      "requestedQueryCost": 502,
      "throttleStatus": { "currentlyAvailable": 120, "restoreRate": 100.0 }
    }
  }
}

Een koppeling die alleen naar de HTTP-status kijkt, boekt dit als gelukt. De voorraadwijziging die erin zat is nooit uitgevoerd en er staat niets in een log. De koppeling moet dus elk antwoord op THROTTLED controleren, en uit hetzelfde antwoord de wachttijd halen: tekort gedeeld door bijvultempo.

Een 429 bestaat bij Shopify wel, op twee plekken. De REST Admin API geeft 429 Too Many Requests met een Retry-After-header in seconden. En de GraphQL Admin API geeft een 429 bij de daglimiet op nieuwe varianten: een winkel met 500.000 varianten of meer mag er per dag 10.000 bijmaken, via productCreate, productUpdate en productVariantCreate. Plus is van die daglimiet vrijgesteld. Hoe nieuwe pogingen met oplopende pauzes werken staat in wat is een rate limit.

Een rekenvoorbeeld: 30.000 varianten

Een groothandel heeft 6.000 producten met elk 5 varianten, samen 30.000 varianten, op een standaardplan. Elke nacht komen uit het ERP nieuwe voorraadstanden en nieuwe prijzen. Bij de standaardprijs van 10 punten per mutatie:

De sommen: 30.000 gedeeld door 250 is 120 aanroepen, maal 10 punten is 1.200 punten, gedeeld door 100 per seconde is 12 seconden. Voor de prijzen werkt bundelen anders. productVariantsBulkUpdate werkt varianten bij van één product per aanroep, dus 6.000 producten zijn 6.000 aanroepen. Op Plus is dat 60 seconden, op een standaardplan 10 minuten. Dezelfde mutatie kan ook als bulk mutatie: één JSONL-bestand met 6.000 regels, buiten de puntenlimiet, binnen 24 uur verwerkt.

Voorraad schrijft de koppeling met inventorySetQuantities, 250 regels per aanroep:

{
  "input": {
    "name": "available",
    "reason": "correction",
    "quantities": [
      { "inventoryItemId": "gid://shopify/InventoryItem/41022",
        "locationId": "gid://shopify/Location/7781",
        "quantity": 14, "changeFromQuantity": 20 }
    ]
  },
  "idempotencyKey": "4f1c0e2a-9b7d-4e55-a1f3-0c6d2b8e7a19"
}

changeFromQuantity maakt de schrijfactie voorwaardelijk: Shopify zet de voorraad alleen op 14 als hij nog op 20 staat. Kwam er tijdens de ronde een order binnen, dan faalt die regel met CHANGE_FROM_QUANTITY_STALE en rekent de koppeling hem opnieuw uit. Vanaf API-versie 2026-04 is de idempotency key verplicht, zodat een aanroep die na een time-out opnieuw gaat maar één keer wordt uitgevoerd.

Lezen loopt vast op 25.000

Lezen kent een andere grens. Bladeren door een lijst stopt bij 25.000 objecten, dus een koppeling die alle 30.000 varianten pagina voor pagina ophaalt, haalt de laatste 5.000 nooit op. De route voor een volledige vergelijking is een bulk query: één bulkOperationRunQuery, Shopify draait hem zelf buiten de puntenlimiet, en het resultaat is een JSONL-bestand met één object per regel. De downloadlink blijft een week geldig. Voor wijzigingen tussendoor gebruikt de koppeling webhooks, met hun eigen regels: zie wat is een webhook. Hoe je een volledige ronde met beide kanten doorrekent, staat in doorvoer berekenen.

Wat betekent dit voor je koppeling?

De kant van Shopify bouwen we op de GraphQL Admin API met deze limieten als uitgangspunt: bulk queries voor volledige rondes, 250 regels per voorraadaanroep, een controle op THROTTLED in elk antwoord, en een wachtrij die zijn tempo afstemt op currentlyAvailable. Een afgeknepen aanroep blijft in de wachtrij en gaat opnieuw, en elke poging staat in de log van het dashboard. Voor de eerste live ronde laat een dry run zien welke varianten naar welke waarde gaan.

Hoe Shopify aan de systemen erachter hangt, staat op de pagina over de Shopify koppeling. De voorraadstroom met locaties en buffers staat bij voorraad en beschikbaarheid. Noem je abonnement, je aantal varianten en je ERP, dan rekenen we uit wat een volledige ronde en een piekuur voor jouw winkel kosten.