This document lists the quotas that apply to the Merchant API. The Merchant API uses quotas to help ensure a stable and fair environment for all users. Quotas prevent any single API user from placing an excessive load on the system, ensuring high performance. Understanding these quotas is key to managing your product data and scaling your business on Google. ## General concepts Merchant API quotas are managed through quota groups. > [!IMPORTANT] > **Key Term:** A quota group defines the number of requests allowed for a specific set of API methods. When you make an API call, it consumes quota from the assigned quota group. API methods are mapped to quota groups. The structure of this mapping can vary: - **Single method per group:** Some quota groups apply to a single API method. For example, the listing data sources method [`accounts.dataSources.list`](https://developers.google.com/merchant/api/reference/rest/datasources_v1/accounts.dataSources/list) has its own dedicated quota group. - **Multiple methods per group (bundling):** Often, related methods are bundled together into a single quota group. All methods within that group share the same daily and per-minute limits. Common examples include: - Grouping all read operations for related methods and resources, such as `merchant-accounts-read-methods`. - Grouping all write operations for related methods and resources, such as `merchant-accounts-write-methods`. Each method call counts once, regardless of its type. A `list` request of 250 items counts only once, not as 250 `get` requests. Built-in [HTTP batching](https://developers.google.com/merchant/api/guides/send-multiple-requests#write-batch-request) does not influence quota. Each single request within a batch of requests counts as one against the quota. For example, a batch request containing 500 `insert` requests is charged as 500 individual `insert` method requests. **Exception for dedicated region batching:** Specialized region batch methods ([`batchCreate`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.regions/batchCreate), [`batchUpdate`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.regions/batchUpdate), [`batchDelete`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts.regions/batchDelete)) count as a single API call against the `merchant_regions` quota group, regardless of the number of region operations contained in the payload. To effectively manage your integration, you should review the specific quota group associated with each API method you intend to use. You can find these details in the quotas list method. For more information, see [Monitoring and Visibility](https://developers.google.com/merchant/api/guides/quotas-limits/quotas#monitoring-and-visibility). ## Update policy The Merchant API enforces the following policies in terms of updates: - By default, you can update your products up to twice per day. You should evenly spread the calls throughout the day to comply with the per minute quota. - By default, you can only update your sub-accounts up to twice per day. Your daily sub-account update quota is an aggregate limit based on your total allowed sub-accounts. - By default, you can only call data source methods for your sub-accounts such as `list` or `create` up to twice per sub-account per day. > [!IMPORTANT] > **Important:** Quotas and limits are subject to elimination, reduction, or change at any time, without notice. ## Rate quotas Each quota group has two types of limits (and daily usage): - **Daily Limit (`quotaLimit`):** The maximum number of requests allowed per day. The daily quota limits reset at **12:00 PM midday UTC**. - **Per-Minute Limit (`quotaMinuteLimit`):** The maximum number of requests allowed per minute, controlling the rate of requests. The per-minute quota limits use a rolling window, where the enforcement period starts from the moment the first API call for that method and resource is made. For example, if you make a call at **10:01:30 AM** , the per-minute quota window for that method runs until **10:02:30 AM**. - **Daily Usage (`quotaUsage`):** The number of requests that have already been made and counted against the daily limit for the current day. If the field is missing, then no quota has been consumed for this group yet. You can find the three fields described previously (`quotaLimit`, `quotaMinuteLimit`, and `quotaUsage`) in the response of the [`quotas.list`](https://developers.google.com/merchant/api/reference/rest/quota_v1/accounts.quotas/list) method. The specific daily and per-minute limits vary significantly between different quota groups. Operations with higher expected volume or lower system cost, such as reading product data, typically have higher limits. Conversely, more intensive or sensitive operations, such as account modifications, might have lower limits. ## Quota allocation and hierarchy This section explains on whose behalf the Merchant API tracks and applies quota usage: In general, quota is charged based on the user who makes the API request. - **Stand-alone accounts:** For stand-alone accounts authenticating an API call, that request counts against that account's quota. - *Example:* A merchant **Shoe Store A** (Account ID: 12345) authenticates using its own service account to call `products.insert` targeting its own account (`accounts/12345`). The quota is consumed from **Shoe Store A's** quota pool. - **Advanced-accounts:** Authenticating as an [advanced account](https://support.google.com/google-ads/answer/14089347) consumes quota from the advanced account's pool, even when targeting a [sub-account](https://developers.google.com/merchant/api/guides/accounts/create-accounts). - *Example:* An agency **Retail Management Account** (Advanced Account ID: 12345) manages a sub-account **Clothing Store B** (Account ID: 11111). The agency authenticates using its own credentials and calls `products.insert` targeting **Clothing Store B** (`accounts/11111`). The quota is consumed from the parent agency's pool (Advanced Account ID: 12345), not the sub-account's pool. - **Sub-accounts:** When API calls are authenticated using a sub-account's credentials, quota is charged to that sub-account's individual pool. This operates the same way as a stand-alone account, even though it is managed by a parent advanced account. - *Example:* Using the same setup as previous, if **Clothing Store B** (Account ID: 11111) authenticates using credentials set up specifically for their sub-account to call `products.insert` targeting their own account (`accounts/11111`), the quota is consumed from **Clothing Store B's** individual quota pool, leaving the parent agency's pool untouched. ### Exceptions to the general rules There are a few specific exceptions that apply to the quota allocation general rules: - [**Accounts.list**](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts/list): The quota for this method is charged against the authenticated user or service account making the call, not the Merchant Center account ID. Its quota usage won't be visible in the standard [Merchant Center API diagnostics page](https://support.google.com/merchants/answer/14173602#API_diagnostics). If you have an advanced account, we recommend using the [`accounts.listSubaccounts`](https://developers.google.com/merchant/api/reference/rest/accounts_v1/accounts/listSubaccounts) method, which counts towards your advanced accounts quota. - [**Issueresolution methods**](https://developers.google.com/merchant/api/reference/rest/issueresolution_v1/issueresolution): These methods always count against the quota for the account whose issues are being requested, even if a different account is authenticating the request. ### Allocation Hierarchy - **Comparison Shopping Services (CSS):** CSS are websites that aggregate product offers and direct users to retailers' websites to make purchases. When making API calls, quotas are applied to the specific CSS group, CSS domain, account, or sub-account you authenticate against. *Examples:* - A CSS Group named **Europe Shopping Group** (Account ID: 10001) wants to list its associated CSS domains. By authenticating with its own credentials to make this API call, the quota is consumed directly from the **Europe Shopping Group** quota pool. - A CSS Domain **TopDeals CSS** (Account ID: 20002) authenticates to call a method targeting one of its associated merchant accounts (`accounts/30003`) to assign a label. The quota is consumed from **TopDeals CSS's** quota pool, not the merchant account's pool. - **Marketplaces:** Marketplaces are online platforms hosting multiple individual merchants. They function as special advanced accounts that allow you to create individual sub-accounts for each of your sellers. The following diagram shows the hierarchy of CSS groups, CSS, Marketplaces, advanced accounts, standalone accounts and sub-accounts. ![A CSS group is the overarching authentication level, with the possibility of individual CSS within it, accounts within those and sub-accounts as the most individual level.](https://developers.google.com/static/merchant/api/guides/images/accounts-hierarchy-v2.png) ## Automatic Quota Adjustment The Merchant API has an automatic quota management system for specific services, which adjusts quota limits for growing merchants based on your usage, offer and account size. The Merchant API recomputes these quotas daily. The quota groups included in automatic quotas adjustments are: ### Products services - All quota groups of methods related to the `products` and `productInputs` resources. - The daily call quota is generally set to 2 times the number of offer quota the merchant has. This assumes a merchant might need to update each of their products up to twice per day. - Individual products can be updated more than twice, but your overall daily API calls cannot exceed the aggregate daily call quota. ### Accounts services - All quota groups of methods related to the various granular account-related resources in the Merchant API. - The daily call quota is set to the maximum number of sub-accounts allowed for that account. This allows for up to two times of read calls per sub-account per day. ### Data sources services - All quota groups of methods related to the data source related resources in the Merchant API such as `list` or `create` that an advanced account performs on their sub-accounts. - The daily call quota is generally set to 2 times the number of sub-accounts the advanced account has. This assumes a merchant can update each of their sub-accounts' data sources up to twice per day. Only the services described previously have automatic quotas adjustments. Other services have a default quota, and any increases must be requested manually. For more information, see the [Quota increase process section](https://developers.google.com/merchant/api/guides/quotas-limits/quotas#quota-increase-process). ## What happens when quotas have been exceeded After a quota has been exceeded, errors will appear in the API responses and in the diagnostics page within your Merchant Center account: - **Per minute:** `quota/request_rate_too_high` { "error": { "code": 429, "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "quotaExceeded", "domain": "merchantapi.googleapis.com", "metadata": { "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits", "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH" } } ] } } - **Per day:** `quota/daily_limit_exceeded` { "error": { "code": 429, "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "quotaExceeded", "domain": "merchantapi.googleapis.com", "metadata": { "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits", "REASON": "QUOTA_TOO_MANY_REQUESTS" } } ] } } The following errors are Merchant Center limits, and are not related to Merchant API quotas. You can try to [request additional quota of items, feeds or sub-accounts](https://support.google.com/merchants/contact/additional_items): - `too_many_items`: Merchant quota exceeded - `too_many_subaccounts`: Maximum number of sub-accounts reached ## Monitoring and visibility To check the current call quotas and usage for an account, call [`quotas.list`](https://developers.google.com/merchant/api/reference/rest/quota_v1/accounts.quotas/list) with the name of the account. POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas Content-Type: application/json Authorization: Bearer {ACCESS_TOKEN} Replace the following: - `ACCOUNT_ID`: your Merchant Center ID - `ACCESS_TOKEN`: the authorization token to make the API call Upon a successful request, the API returns a list of [quotaGroups](https://developers.google.com/merchant/api/reference/rest/quota_v1/accounts.quotas#QuotaGroup) resources containing the resource `name` of the quota group, the different quotas and the methods to which the group quota applies to. { "quotaGroups": [ { "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups", "quotaUsage": "2", "quotaLimit": "1000", "methodDetails": [ { "method": "quotaservice.listquotagroups", "version": "v1", "subapi": "quota", "path": "quota/v1/quotaservice.listquotagroups" } ], "quotaMinuteLimit": "10" }, { "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list", "quotaLimit": "10000", "methodDetails": [ { "method": "commissiongroupservice.listcommissiongroups", "version": "v1", "subapi": "youtube", "path": "youtube/v1/commissiongroupservice.listcommissiongroups" } ], "quotaMinuteLimit": "60" }, { "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list", "quotaLimit": "20000000", "methodDetails": [ { "method": "merchantreviewsservice.listmerchantreviews", "version": "v1", "subapi": "reviews", "path": "reviews/v1/merchantreviewsservice.listmerchantreviews" } ], "quotaMinuteLimit": "60000" } ] } ## Quota increase process To request additional quota, open the [Contact support form](https://support.google.com/merchants/contact/shopping_api_support_form), select Quota increase request for the required "What is the Issue/Question" field, and fill out all required fields, including your Merchant Center ID, target methods, and business justification. - **For resources with automatic quotas (`products`, `accounts`, and `datasources` for advanced accounts)):** You can request only a temporary increase for special scenarios such as launching in a new market or during high-traffic shopping seasons. We don't accept permanent quota increases for these types of resources. - **For all other resources without automatic quotas:** Request quota increases as needed. > [!IMPORTANT] > **Important:** We don't guarantee that quota increase requests will be granted. We recommend checking your quotas periodically to ensure you have sufficient quota for your implementation, and see how your quota is adjusted automatically. Use the `quotas.list` method to see your current daily quota limit, minute limit, and current daily usage for each API method group. ## Best Practices Implementing these best practices helps ensure your integration runs smoothly, avoids unexpected quota errors, and utilizes Merchant Center resources efficiently. ### Optimize Request Distribution - **Spread Requests Evenly:** Avoid sending large bursts of requests. Spread your daily API calls evenly throughout the day to stay within the per-minute quota limits (`quotaMinuteLimit`). - **Proactive Throttling:** Implement client-side rate limiting (throttling) in your application. Don't rely solely on Google's servers to reject excess traffic. Control your request rate at the source. ### Graceful Error Handling - **Handle HTTP 429:** Your application must be prepared to handle 429 Too Many Requests errors (`quota/request_rate_too_high`). - **Exponential Backoff with Jitter:** When retrying failed requests (especially after a 429), use exponential backoff (increasing wait times) and add "jitter" (random delay). Jitter prevents "retry storms," where multiple client instances retry at the exact same time, overloading the server again. - **Respect Retry Hints:** If the API response contains retry details or headers, use them to determine when to resume calls. ### Minimize Redundant Calls - **Prevent Stale Calls (404 NOT_FOUND):** Avoid requesting or deleting resources that no longer exist. Even failed calls consume API quota. Monitor `NOT_FOUND` errors in Merchant Center API Diagnostics to detect stale state tracking or unnecessary polling. - **Verify Before Update:** Before sending an update request, check if the data has actually changed. Avoid sending updates that write the same values. - **Use Caching:** Cache read responses (e.g., product details, settings) locally when appropriate to avoid repetitive `get` or `list` calls for unchanged data. ### Navigate Quota Hierarchy and Exceptions - **Advanced Accounts and Sub-accounts:** If you are an advanced account, authenticate at the advanced account level if you want calls to count against the advanced accounts shared pool. - **Use `listSubaccounts`:** For advanced accounts, use `accounts.listSubaccounts` instead of `accounts.list`. The `accounts.list` quota is charged to the calling user (not the MC ID) and is not visible in standard diagnostics. `listSubaccounts` counts against your MCA quota.