Customer Account API / Rate limits

The Customer Account API gets
a "per-customer, 3,000 per minute" limit

Up to 3,000 requests per minute per customer on a store. The limit is shared across all apps and applies on top of the existing cost-based limits. Typical buyer traffic needs no changes, but review your retry handling.

On this page
  1. What's changing (in 30 seconds)
  2. How it works: how the two limits relate
  3. The response when you exceed the limit
  4. Before vs. after
  5. Who's affected
  6. What to do: 3 steps for retry handling
  7. 5 key points for engineers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

The Customer Account API now has a new limit of "3,000 requests per minute per customer, per store" .
This limit is shared across all apps installed on the store, and appliesin addition tothe existing cost-based rate limits.
3000

3,000 per minute

Request limit per customer, per store.

Shared across all apps

No matter which app sends the request, the same customer on the same store uses the same quota.

Most stores need no changes

Typical buyer traffic is expected to stay well below this limit.

2How it works: how the two limits relate

App A App B App C ① Per-customer limit (new) 3000 / min Per customer × store Counted across all apps combined ② Cost-based limit (existing) Continues as before Customer Account API Both limits apply together (the new cap is in addition to the existing limit)
Key point: it's a shared quota : Even if your own app makes few requests, if other apps are also calling the Customer Account API for the same customer, they all draw from the same 3,000 requests/minute quota.

3Response when the limit is exceeded

429
HTTP 429
Too Many Requests
THROTTLED error
Returned as the error code
Retry-After header
Tells you how long to wait
The article points to the Customer Account API rate limits documentation for details. It doesn't specify the exact JSON format of the response body.

4Before vs. after

ItemBeforeAfter
Cost-based rate limit Yes Yes Unchanged
Per-customer request limit None New 3,000 requests per minute / store
Counting unit — Customer × store (all apps combined)
Behavior when exceeded — HTTP 429 + THROTTLED + Retry-After
Start date / transition period Not stated (the article says it "now enforces" the limit, meaning it's already in effect)

5Scope of impact

Applies to: all apps that call the Customer Account API

Every app that calls the Customer Account API is affected, on any store.

Real-world impact: none in most cases

Normal buyer traffic stays well below the limit, so in most cases no action is needed.

The article doesn't say how to check your current usage (for example, a header or dashboard showing the remaining quota).

6What to do: 3 steps for retry handling

If your app uses the Customer Account API, make sure your retry logic does the following.

1

Detect HTTP 429

Check the response status code for 429.

2

Read Retry-After

Get the wait time from the response header.

3

Wait, then retry

Wait for the duration in Retry-After, then resend the same request.

If these 3 points are covered, your app can recover automatically on the rare occasions it hits the limit.The article doesn't call for any other code changes.

75 key points for developers

① ②

1. Limits now have two layers

The existing cost-based limit stays in place, with a per-customer request limit added on top. Design on the assumption that you can hit either one.

2. The quota is shared with other apps

Your own app's call volume isn't enough to predict it. Depending on how much other apps on the same store consume, you may get a 429.

3. The key is "customer × store"

Requests are counted per customer on a store, not per app or per IP. Bulk processing and polling against a single customer are the patterns to watch out for.

429

4. A 429 means "wait and it will recover"

THROTTLED is not a permanent error. Instead of hammering immediate retries, you're expected to follow Retry-After.

? ? ?

5. What the article doesn't say

The start date and any grace period, how to check remaining quota, whether you can request a higher limit, and the range of Retry-After values arenot stated. If needed, check the Customer Account API rate limit documentation.

83 practical use cases

USE CASE 1

Audit 429 handling in existing apps and custom implementations

Challenge
You maintain customer account page extensions or custom apps that use the Customer Account API, but you're not sure whether their retry logic handles 429 / Retry-After.
Action
Find the relevant code and check that it covers all 3 points: detect 429 → read Retry-After → wait, then retry.
Impact
On the rare occasions you hit the limit, the app recovers automatically instead of showing an error.
Technical note
Implement it once in your shared HTTP client layer and it applies to every call.
Shared quota
USE CASE 2

Review API call volume on stores running multiple apps

Challenge
Customer-facing features are built from multiple apps, and each one calls the Customer Account API for the same customer.
Action
Map out which apps call the API and how many times when a customer account page loads, then cut duplicate fetches and polling.
Impact
Less waste of the shared quota, which lowers both the risk of hitting the limit and a source of slow page loads.
Technical note
Because the quota is shared across all apps, a 429 can still happen because of other apps even if you optimize your own. Retry logic is a must regardless.
USE CASE 3

Add to design review checklists for app development and client projects

Challenge
When building new integrations with the Customer Account API, rate-limit considerations are easy to miss during reviews.
Action
Add "3,000 requests/min per customer, shared across all apps" and "on 429, honor Retry-After" to the design review checklist.
Impact
Prevents throttling-related bugs after release and gives you a clear basis for explaining behavior to clients.
Technical note
Cost-based limits still apply alongside this one, so design test cases that account for both limits.

9One-line summary for proposals

"The Customer Account API now enforces a limit of 3,000 requests per minute per customer, shared across all apps .
Normal usage is unaffected; as long as youdetect 429s and retry after waiting for the Retry-After interval, you're fine."