Shopify API rate limits: betrouwbare integraties vanuit Laravel

Je ERP stuurt honderden wijzigingen tegelijk en Shopify antwoordt met 429 of THROTTLED. Zo werken de REST- en GraphQL-limieten per plan, en zo bouw je in Laravel een client, queue-setup en bulk-sync die ze respecteren.

Coding.nl
Bijgewerkt 4 leestijd
Inhoud van dit artikel
  1. Hoe Shopify limiteert: de leaky bucket
  2. REST Admin API
  3. GraphQL Admin API: kosten in punten
  4. De Laravel-client
  5. Meerdere workers: een gedeelde limiter in Redis
  6. Bulk Operations voor grote datasets
  7. Monitoring
  8. Overzicht: welke aanpak wanneer
  9. Veelgestelde vragen
  10. Verder lezen

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:

PlanEmmerLeksnelheid
Standaard40 verzoeken per app per winkel2 per seconde
Shopify Plus400 verzoeken per app per winkel20 per seconde

Elke response bevat de stand van de emmer, en bij overschrijding krijg je een 429 met een wachttijd:

http
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:

OnderdeelKosten
Scalar en enum0 punten
Object1 punt
ConnectionAfhankelijk van het first- of last-argument
Mutation10 punten
Interface en unionMaximum van de mogelijke selecties

De herstelsnelheid per plan:

PlanHerstel
Standaard100 punten per seconde
Advanced Shopify200 punten per seconde
Shopify Plus1.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:

json
{
  "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:

php
'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
<?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
<?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
<?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
<?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:

php
// In AppServiceProvider::boot()
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('shopify-api', fn (object $job) => Limit::perSecond(2));
php
// 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

graphql
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 url en partialDataUrl op met een query op het ID.
  • status staat 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.

php
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);
}
php
// 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:

  1. Maak een JSONL-bestand met per regel de variabelen voor één uitvoering van de mutation. Maximaal 100 MB.
  2. Vraag een upload-URL aan met stagedUploadsCreate (resource BULK_MUTATION_VARIABLES, mimeType text/jsonl, httpMethod POST) en upload het bestand als multipart-formulier, met het file-veld als laatste parameter.
  3. Start bulkOperationRunMutation met de mutation en het stagedUploadPath.
  4. Wacht op de webhook en verwerk het resultaatbestand, waarin per regel de response en eventuele userErrors staan.

Prijzen bijwerken doe je bijvoorbeeld met productVariantsBulkUpdate:

graphql
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 }
  }
}
jsonl
{"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 actualQueryCost per query-type, zodat je ziet welke query duur wordt
  • Succes en duur van bulk operations, en het aantal userErrors per 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

SituatieAanpak
Losse lees- of schrijfactieGraphQL-client met retry en budgetbewaking
Bestaande REST-koppelingREST-client met header-tracking; plan migratie naar GraphQL
Gepagineerd ophalen van een beperkte setGraphQL met first en cursors, onder de 25.000 objecten
Volledige catalogus of grote orderhistorieBulk query
Duizenden wijzigingenBulk mutation via staged upload
Meerdere workers of systemen op één appRedis-limiter, eigen queues per prioriteit
Realtime wijzigingenWebhooks 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:

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.

Ruthger Idema

Geschreven door Ruthger Idema

Eigenaar van Coding.nl. 15+ jaar e-commerce met Magento, Shopify en Laravel, samen met het vaste team in Emmen.

Wil je dit voor jouw shop laten uitzoeken? Plan een half uur

Een half uur via video met de mensen die het werk ook echt doen. Kies hieronder een moment dat jou past.

  • Direct met het vaste team, geen tussenlagen
  • Concrete feedback op je huidige situatie of plannen
  • Eerlijk advies, ook als het antwoord "niet doen" is
  • Indicatie van kosten en tijdlijn
Liever bellen? 0591-239 299
Beschikbaar deze week

Plan een gratis Tech Check

Vrijblijvend jouw uitdagingen bespreken

Of bel direct: 0591-239 299