Inhoud van dit artikel
Een ERP stuurt 500 productwijzigingen tegelijk naar Shopify. De eerste tientallen slagen, daarna komen de fouten. De integratie logt ze en stopt, en een deel van je assortiment heeft nu verkeerde prijzen. Dat gebeurt bij elke koppeling die zonder rate limit-strategie is gebouwd. Dit artikel legt uit hoe de limieten van Shopify werken en hoe je er in Laravel een robuuste integratie omheen bouwt.
Hoe Shopify limiteert: de leaky bucket
Shopify gebruikt voor de meeste API's een leaky bucket. Elke app heeft per winkel een emmer met een maximale inhoud. Elk verzoek vult de emmer, en de emmer loopt met een vaste snelheid leeg. Zolang je gemiddeld onder die leksnelheid blijft, mag je kort pieken. Loopt de emmer over, dan word je afgeremd.
Twee dingen om te onthouden:
- De limiet geldt per app per winkel. Twee losse apps op dezelfde winkel hebben elk hun eigen emmer. Drie systemen die via dezelfde app-token werken, delen er één.
- Grootte en leksnelheid verschillen per API en per Shopify-plan. Lees de actuele waarden altijd uit de response in plaats van ze hard te coderen.
REST Admin API
De REST Admin API is sinds 1 oktober 2024 een legacy API. Shopify adviseert om alle nieuwe apps en integraties op de GraphQL Admin API te bouwen. Bestaande REST-koppelingen werken nog, maar plan de overstap.
De limieten volgens de documentatie van Shopify:
| Plan | Emmer | Leksnelheid |
|---|---|---|
| Standaard | 40 verzoeken per app per winkel | 2 per seconde |
| Shopify Plus | 400 verzoeken per app per winkel | 20 per seconde |
Elke response bevat de stand van de emmer, en bij overschrijding krijg je een 429 met een wachttijd:
HTTP/1.1 429 Too Many Requests
X-Shopify-Shop-Api-Call-Limit: 40/40
Retry-After: 2.0
X-Shopify-Shop-Api-Call-Limit toont het gebruik ten opzichte van de capaciteit. Retry-After geeft het aantal seconden dat je moet wachten. Verzoeken binnen die tijd worden ook geweigerd.
GraphQL Admin API: kosten in punten
GraphQL rekent niet per verzoek maar per punt. Shopify berekent vooraf de kosten van een query op basis van de velden die je opvraagt:
| Onderdeel | Kosten |
|---|---|
| Scalar en enum | 0 punten |
| Object | 1 punt |
| Connection | Afhankelijk van het first- of last-argument |
| Mutation | 10 punten |
| Interface en union | Maximum van de mogelijke selecties |
De herstelsnelheid per plan:
| Plan | Herstel |
|---|---|
| Standaard | 100 punten per seconde |
| Advanced Shopify | 200 punten per seconde |
| Shopify Plus | 1.000 punten per seconde |
| Shopify for enterprise (Commerce Components) | 2.000 punten per seconde |
Daarnaast geldt een harde grens: één query mag nooit meer dan 1.000 punten kosten, ongeacht je plan. Shopify toetst dat vooraf op de geschatte kosten en weigert de query met MAX_COST_EXCEEDED.
Elke response bevat de kosten in extensions:
{
"data": { "...": "..." },
"extensions": {
"cost": {
"requestedQueryCost": 122,
"actualQueryCost": 98,
"throttleStatus": {
"maximumAvailable": 2000.0,
"currentlyAvailable": 1902,
"restoreRate": 100.0
}
}
}
}
De waarden hierboven zijn een voorbeeld. Lees maximumAvailable en restoreRate uit de response, dan klopt je client automatisch voor elk plan.
Let op: een GraphQL-throttle komt meestal niet als HTTP 429 binnen, maar als een errors-array met code THROTTLED in een gewone response. Een client die alleen op statuscodes let, mist die.
Andere limieten die syncs breken
- Input-arrays mogen in elke Shopify-API maximaal 250 items bevatten.
- Paginering stopt bij 25.000 objecten, ook voor count-queries. Grotere sets haal je op met Bulk Operations.
- Varianten: heeft een winkel 500.000 varianten of meer, dan kun je er maximaal 10.000 per dag aanmaken. Dat geldt niet voor Shopify Plus.
De Laravel-client
Zet de configuratie in config/services.php, met een ondersteunde API-versie:
'shopify' => [
'domain' => env('SHOPIFY_SHOP_DOMAIN'),
'token' => env('SHOPIFY_ACCESS_TOKEN'),
'api_version' => env('SHOPIFY_API_VERSION', '2026-10'),
],
GraphQL-client met throttle-afhandeling
De client doet drie dingen: hij wacht proactief als het puntenbudget te laag is voor de volgende query, hij herkent THROTTLED in de body, en hij probeert alleen opnieuw bij fouten die tijdelijk zijn.
<?php
namespace App\Services\Shopify;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
class ShopifyGraphQL
{
private PendingRequest $http;
private ?float $available = null;
private float $restoreRate = 100.0;
public function __construct(
private readonly string $shopDomain,
private readonly string $accessToken,
private readonly string $apiVersion,
private readonly int $maxAttempts = 5,
) {
$this->http = Http::baseUrl("https://{$shopDomain}/admin/api/{$apiVersion}")
->withHeaders(['X-Shopify-Access-Token' => $accessToken])
->acceptJson()
->timeout(30);
}
public function query(string $query, array $variables = [], int $expectedCost = 50): array
{
for ($attempt = 1; $attempt <= $this->maxAttempts; $attempt++) {
$this->waitForBudget($expectedCost);
try {
$response = $this->http->post('/graphql.json', [
'query' => $query,
'variables' => $variables ?: new \stdClass(),
]);
} catch (ConnectionException $e) {
$this->sleepMs($this->backoffMs($attempt));
continue;
}
if ($response->status() === 429 || $response->serverError()) {
$retryAfter = (float) ($response->header('Retry-After') ?: 0);
$this->sleepMs($retryAfter > 0 ? (int) ($retryAfter * 1000) : $this->backoffMs($attempt));
continue;
}
$response->throw(); // overige 4xx: niet opnieuw proberen
$body = $response->json();
$this->updateBudget($body['extensions']['cost'] ?? null);
if ($this->isThrottled($body)) {
$cost = $body['extensions']['cost'] ?? [];
$needed = ($cost['requestedQueryCost'] ?? $expectedCost) - ($this->available ?? 0);
$waitMs = (int) ceil(max($needed, 0) / $this->restoreRate * 1000) + random_int(0, 250);
Log::warning('Shopify GraphQL throttled', ['attempt' => $attempt, 'wait_ms' => $waitMs]);
$this->sleepMs($waitMs);
continue;
}
if (! empty($body['errors'])) {
throw new \RuntimeException('Shopify GraphQL-fout: ' . json_encode($body['errors']));
}
return $body['data'];
}
throw new \RuntimeException("Shopify GraphQL: maximaal aantal pogingen ({$this->maxAttempts}) bereikt");
}
private function isThrottled(array $body): bool
{
foreach ($body['errors'] ?? [] as $error) {
if (($error['extensions']['code'] ?? null) === 'THROTTLED') {
return true;
}
}
return false;
}
private function updateBudget(?array $cost): void
{
if (! $cost) {
return;
}
$this->available = (float) $cost['throttleStatus']['currentlyAvailable'];
$this->restoreRate = (float) $cost['throttleStatus']['restoreRate'];
}
private function waitForBudget(int $expectedCost): void
{
if ($this->available !== null && $this->available < $expectedCost) {
$this->sleepMs((int) ceil(($expectedCost - $this->available) / $this->restoreRate * 1000));
$this->available = (float) $expectedCost;
}
}
private function backoffMs(int $attempt): int
{
// Exponential backoff met jitter: 1s, 2s, 4s, 8s... maximaal 30s
$base = 1000 * (2 ** ($attempt - 1));
return min($base + random_int(0, (int) ($base * 0.25)), 30_000);
}
private function sleepMs(int $ms): void
{
usleep($ms * 1000);
}
}
Waarom jitter: als tien workers tegelijk een throttle krijgen en allemaal precies twee seconden wachten, raken ze de limiet tegelijk opnieuw. Een willekeurige extra wachttijd spreidt ze.
Legacy REST-client
Heb je nog REST-koppelingen, gebruik dan het X-Shopify-Shop-Api-Call-Limit-header om de emmer bij te houden, en probeer alleen opnieuw bij 429, 5xx en verbindingsfouten. Met de retry()-helper van Laravel:
<?php
namespace App\Services\Shopify;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Client\Response;
use Illuminate\Support\Facades\Http;
class ShopifyRestClient
{
private PendingRequest $http;
private float $capacity = 40.0;
private float $used = 0.0;
public function __construct(string $shopDomain, string $accessToken, string $apiVersion)
{
$this->http = Http::baseUrl("https://{$shopDomain}/admin/api/{$apiVersion}")
->withHeaders(['X-Shopify-Access-Token' => $accessToken])
->acceptJson()
->timeout(30);
}
public function request(string $method, string $endpoint, array $data = []): Response
{
return retry(
times: 5,
callback: function () use ($method, $endpoint, $data) {
$this->throttle();
$response = $this->http->send($method, $endpoint, $method === 'GET'
? ['query' => $data]
: ['json' => $data]);
$this->readBucket($response);
if ($response->status() === 429) {
throw new ShopifyRateLimitException((float) ($response->header('Retry-After') ?: 2.0));
}
return $response->throw();
},
sleepMilliseconds: function (int $attempt, \Throwable $e): int {
if ($e instanceof ShopifyRateLimitException) {
return (int) ($e->retryAfter * 1000) + random_int(0, 500);
}
$base = 1000 * (2 ** ($attempt - 1));
return min($base + random_int(0, (int) ($base * 0.25)), 30_000);
},
when: fn (\Throwable $e) => $e instanceof ShopifyRateLimitException
|| $e instanceof ConnectionException
|| ($e instanceof RequestException && $e->response->serverError()),
);
}
private function readBucket(Response $response): void
{
if ($header = $response->header('X-Shopify-Shop-Api-Call-Limit')) {
[$used, $capacity] = array_map('floatval', explode('/', $header));
$this->used = $used;
$this->capacity = $capacity;
}
}
private function throttle(): void
{
// Houd ruimte over voor andere processen; leksnelheid is capaciteit / 20
$leakRate = $this->capacity / 20;
if ($this->capacity - $this->used < 5) {
usleep((int) ((5 - ($this->capacity - $this->used)) / $leakRate * 1_000_000));
}
}
}
<?php
namespace App\Services\Shopify;
class ShopifyRateLimitException extends \RuntimeException
{
public function __construct(public readonly float $retryAfter)
{
parent::__construct("Shopify rate limit bereikt. Wacht {$retryAfter} seconden.");
}
}
De leksnelheid als capaciteit gedeeld door 20 klopt voor beide plannen in de tabel hierboven (40 en 2 per seconde, 400 en 20 per seconde). Zonder de when-voorwaarde zou een 404 of 422 vijf keer opnieuw worden geprobeerd, wat alleen je emmer leegtrekt.
Meerdere workers: een gedeelde limiter in Redis
De client hierboven kent alleen zijn eigen verzoeken. Draai je meerdere queue workers, of delen ERP, PIM en orderverwerking dezelfde app, dan trekken ze samen aan één emmer. Een atomische limiter in Redis voorkomt dat. Dit script werkt met punten, dus voor GraphQL-kosten en voor REST (kosten 1 per verzoek):
<?php
namespace App\Services\Shopify;
use Illuminate\Support\Facades\Redis;
class DistributedRateLimiter
{
private const SCRIPT = <<<'LUA'
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local cost = tonumber(ARGV[4])
local state = redis.call('HMGET', key, 'tokens', 'ts')
local tokens = tonumber(state[1]) or capacity
local ts = tonumber(state[2]) or now
tokens = math.min(capacity, tokens + (now - ts) * rate)
if tokens >= cost then
redis.call('HSET', key, 'tokens', tokens - cost, 'ts', now)
redis.call('EXPIRE', key, 120)
return 0
end
redis.call('HSET', key, 'tokens', tokens, 'ts', now)
redis.call('EXPIRE', key, 120)
return math.ceil((cost - tokens) / rate * 1000)
LUA;
public function __construct(
private readonly string $shopDomain,
private readonly float $capacity, // bijv. maximumAvailable uit GraphQL
private readonly float $rate, // bijv. restoreRate uit GraphQL
) {}
public function acquire(int $cost = 1, int $maxWaitMs = 30_000): void
{
$waited = 0;
while (true) {
$waitMs = (int) Redis::eval(
self::SCRIPT,
1,
"shopify_bucket:{$this->shopDomain}",
$this->capacity,
$this->rate,
microtime(true),
$cost,
);
if ($waitMs === 0) {
return;
}
if ($waited + $waitMs > $maxWaitMs) {
throw new \RuntimeException("Rate limiter timeout na {$waited} ms");
}
usleep($waitMs * 1000);
$waited += $waitMs;
}
}
}
Het script geeft terug hoeveel milliseconden je moet wachten, in plaats van alleen ja of nee. Dat scheelt pollen. Stel de capaciteit iets lager in dan de echte emmer, zodat er ruimte blijft voor andere apps en voor de schatting die er een paar punten naast zit.
Queue-middleware als eenvoudiger alternatief
Voor één type job is de RateLimited-middleware van Laravel vaak genoeg:
// In AppServiceProvider::boot()
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;
RateLimiter::for('shopify-api', fn (object $job) => Limit::perSecond(2));
// In App\Jobs\ShopifyProductUpdateJob
use Illuminate\Queue\Middleware\RateLimited;
public function middleware(): array
{
return [new RateLimited('shopify-api')];
}
public function retryUntil(): \DateTime
{
return now()->addHour();
}
De middleware telt jobs, geen punten, en zet een afgeremde job terug op de queue. Elke release telt als poging, dus gebruik retryUntil() in plaats van een laag $tries, anders falen jobs die alleen maar wachtten.
Prioriteit tussen systemen
Delen meerdere systemen de limiet, geef ze dan elk een eigen queue en laat workers in volgorde van prioriteit werken, bijvoorbeeld php artisan queue:work --queue=orders,stock,products. Orderverwerking en voorraad gaan dan voor een nachtelijke productsync, terwijl ze allemaal dezelfde limiter gebruiken.
Bulk Operations voor grote datasets
Wil je de hele catalogus ophalen of tienduizenden varianten bijwerken, gebruik dan geen lus van losse calls. Bulk Operations draaien asynchroon bij Shopify en vallen buiten zowel de rate limits als de maximale querykosten van gewone queries.
Concurrency: vanaf API-versie 2026-01 kan een app per winkel tot vijf bulk query-operaties en vijf bulk mutation-operaties tegelijk draaien. In oudere versies is dat één per type.
Data ophalen
mutation {
bulkOperationRunQuery(
query: """
{
orders(query: "created_at:>2026-01-01") {
edges {
node {
id
name
createdAt
totalPriceSet { shopMoney { amount currencyCode } }
lineItems {
edges { node { title quantity sku } }
}
}
}
}
}
"""
) {
bulkOperation { id status }
userErrors { field message }
}
}
Het resultaat is een JSONL-bestand: één object per regel. Geneste items, zoals orderregels, staan op eigen regels na hun ouder, met een automatisch toegevoegd __parentId. De download-URL is een week geldig.
Weten wanneer hij klaar is
Abonneer je via webhookSubscriptionCreate op het topic bulk_operations/finish. De webhook gaat af bij voltooid, mislukt of geannuleerd. Twee valkuilen:
- De payload bevat geen download-URL. Haal
urlenpartialDataUrlop met een query op het ID. statusstaat in de payload in kleine letters (completed), in GraphQL in hoofdletters.
Levering van webhooks is niet gegarandeerd, dus poll als vangnet. Vanaf 2026-01 gebruik je daarvoor bulkOperation(id:); currentBulkOperation is deprecated. Poll niet vaker dan nodig, bijvoorbeeld eens per tien seconden.
public function handleBulkOperationFinished(array $payload): void
{
$operationId = $payload['admin_graphql_api_id'];
if (($payload['status'] ?? null) !== 'completed') {
Log::error('Shopify bulk operation niet voltooid', ['payload' => $payload]);
return;
}
ProcessBulkOperationResult::dispatch($operationId);
}
// In ProcessBulkOperationResult::handle(ShopifyGraphQL $graphql)
$node = $graphql->query(
'query($id: ID!) { node(id: $id) { ... on BulkOperation { status url partialDataUrl objectCount } } }',
['id' => $this->operationId],
)['node'];
$path = storage_path('app/shopify/' . md5($this->operationId) . '.jsonl');
Http::withOptions(['sink' => $path])->timeout(300)->get($node['url']);
$file = new \SplFileObject($path);
while (! $file->eof()) {
$line = trim($file->fgets());
if ($line === '') {
continue;
}
$record = json_decode($line, true, flags: JSON_THROW_ON_ERROR);
// verwerk $record; koppel kinderen aan ouders via $record['__parentId']
}
Download naar schijf met sink en lees regel voor regel. Een export van een grote catalogus in één keer in het geheugen laden, gaat bij de eerste grote winkel mis.
Data wegschrijven
Een bulk mutation gaat in vier stappen:
- Maak een JSONL-bestand met per regel de variabelen voor één uitvoering van de mutation. Maximaal 100 MB.
- Vraag een upload-URL aan met
stagedUploadsCreate(resourceBULK_MUTATION_VARIABLES, mimeTypetext/jsonl, httpMethodPOST) en upload het bestand als multipart-formulier, met hetfile-veld als laatste parameter. - Start
bulkOperationRunMutationmet de mutation en hetstagedUploadPath. - Wacht op de webhook en verwerk het resultaatbestand, waarin per regel de response en eventuele
userErrorsstaan.
Prijzen bijwerken doe je bijvoorbeeld met productVariantsBulkUpdate:
mutation {
bulkOperationRunMutation(
mutation: """
mutation call($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
productVariantsBulkUpdate(productId: $productId, variants: $variants) {
productVariants { id price }
userErrors { field message }
}
}
""",
stagedUploadPath: "<pad uit stagedUploadsCreate>"
) {
bulkOperation { id status }
userErrors { field message }
}
}
{"productId": "gid://shopify/Product/1", "variants": [{"id": "gid://shopify/ProductVariant/10", "price": "29.99"}]}
{"productId": "gid://shopify/Product/2", "variants": [{"id": "gid://shopify/ProductVariant/20", "price": "49.99"}]}
Shopify verwerkt de regels niet op volgorde. Bouw je sync dus zo dat elke regel op zichzelf staat.
Monitoring
Een integratie zonder monitoring is betrouwbaar tot de eerste piek. Meet per integratie:
- Aantal 429- en
THROTTLED-responses per uur - Gemiddeld aantal pogingen per verzoek
- Gemiddelde
actualQueryCostper query-type, zodat je ziet welke query duur wordt - Succes en duur van bulk operations, en het aantal
userErrorsper run - Lengte van de Shopify-queues
Een plotselinge stijging in throttles betekent dat een systeem meer stuurt dan gepland. Dat wil je in een dashboard zien, niet horen van een klant die belt over verkeerde prijzen.
Overzicht: welke aanpak wanneer
| Situatie | Aanpak |
|---|---|
| Losse lees- of schrijfactie | GraphQL-client met retry en budgetbewaking |
| Bestaande REST-koppeling | REST-client met header-tracking; plan migratie naar GraphQL |
| Gepagineerd ophalen van een beperkte set | GraphQL met first en cursors, onder de 25.000 objecten |
| Volledige catalogus of grote orderhistorie | Bulk query |
| Duizenden wijzigingen | Bulk mutation via staged upload |
| Meerdere workers of systemen op één app | Redis-limiter, eigen queues per prioriteit |
| Realtime wijzigingen | Webhooks in plaats van pollen |
Veelgestelde vragen
Wat is het verschil tussen een standaard winkel en Shopify Plus?
Bij de REST Admin API zijn emmer en leksnelheid bij Plus tien keer zo groot: 400 verzoeken en 20 per seconde, tegenover 40 en 2. Bij de GraphQL Admin API herstelt Plus 1.000 punten per seconde, tegenover 100 voor een standaard winkel. De maximale kosten van één query zijn voor elk plan 1.000 punten.
Kan ik de limiet verhogen?
Niet via een instelling. Een hoger plan geeft hogere limieten. Voor grote datasets zijn Bulk Operations bedoeld, die buiten de rate limits vallen.
Moet ik nog REST gebruiken?
Voor nieuwe koppelingen niet. REST Admin is sinds oktober 2024 legacy. GraphQL is ook voor eenvoudige acties prima te gebruiken, en voor bulkdata de enige goede optie.
Hoe test ik rate limiting?
Gebruik Http::fake() om 429-responses en THROTTLED-bodies te simuleren, en test of je client wacht en opnieuw probeert. Test de echte limieten op een development store met gesimuleerde load.
Mijn sync loopt steeds vast op limieten. Waar begin ik?
Controleer of je de kosten uit de response leest en of meerdere processen dezelfde app gebruiken zonder gedeelde limiter. Zet grote sets om naar Bulk Operations en vervang pollen door webhooks.
Verder lezen
Rate limiting en webhooks horen bij elkaar in een robuuste koppeling; lees ook ons artikel over webhooks betrouwbaar verwerken in Laravel. Verder:
- Shopify integraties met ERP, WMS en PIM: de complete integratiegids
- Shopify + Alumio: iPaaS-integraties: middleware voor complexe koppelingen
- Laravel als e-commerce middleware: eigen integraties bouwen
De actuele limieten staan in de Shopify API-documentatie over rate limits. Het algemene patroon achter de limiter is het leaky bucket-algoritme.
Meer over onze Shopify-diensten en Laravel-diensten, of neem contact op voor een technisch gesprek over je integratiearchitectuur.





