Skip to main content
The v3 API uses query-cost rate limiting, the same calculated-cost model as Shopify’s GraphQL API. Each request is assigned a cost in points based on the shape of the query, and every store draws from a continuously replenishing bucket of points. Only queries are charged; mutations and introspection cost nothing.

​
The bucket

Each store has its own bucket of points, shared across all of the store’s API tokens:
  • Capacity — the maximum points available at once. Default 10,000.
  • Restore rate — points added back each second. Default 500 / second.
The bucket refills continuously up to capacity. A request runs only if the bucket holds enough points to cover its cost; otherwise it is throttled.
The capacity and restore rate may change. Read your store’s live limits from throttleStatus in each response (see below) rather than hard-coding them.

​
Query cost

Cost follows an object-reads model: it tracks how many objects (rows) a query materializes: So paging a connection with first: 50 costs roughly 50 × 10 = 500 points for the nodes, plus their selected fields. Requesting fewer results — or fewer fields, costs less. Some types carry a custom weight, and the total is rounded.

​
Requested vs. actual cost

  • Requested cost is estimated from the query shape before it runs, using your first values (an unpaged connection assumes a default page size). This is what’s reserved from your bucket up front.
  • Actual cost is computed from what actually came back: a null to-one costs nothing. The difference (requested − actual) is refunded to your bucket after execution.

​
Reading your limits

Every query response includes an extensions.cost object:
Use currentlyAvailable and restoreRate to pace your requests.

​
Throttled responses

If a query’s requested cost exceeds the points currently available, it is rejected before it touches the database with HTTP 429, a Retry-After header (seconds to wait), and the error code THROTTLED:
A throttled query consumes no points. Wait the number of seconds in Retry-After, then retry, ideally with a smaller query.

​
Staying under the limit

Request smaller pages (first), select only the fields you need, and avoid deeply nested connections in a single query. Split large reads across several paged requests and pace them using throttleStatus.
  • Read throttleStatus after each request and back off as currentlyAvailable drops toward zero.
  • Handle 429 / THROTTLED by honoring Retry-After, with exponential backoff as a fallback.
  • Prefer several small paged requests over one large query. The unused-cost refund means narrow requests are cheap.