Quotas

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.

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 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 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, batchUpdate, 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.

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.

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 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 consumes quota from the advanced account's pool, even when targeting a sub-account.
  • 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: 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. If you have an advanced account, we recommend using the accounts.listSubaccounts method, which counts towards your advanced accounts quota.
• Issueresolution methods: 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.

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.

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:

• 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 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 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, 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.

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.