Importante: a API Content for Shopping foi desativada em 18 de agosto de 2026.

A partir de 1º de setembro de 2026, os pedidos da API Content for Shopping vão apresentar erros progressivos. Consulte o guia de desativação da API Content.

Se você precisar de mais tempo para migrar para a API Merchant, solicite acesso estendido à API Content for Shopping.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Cotas

Neste documento, listamos as cotas que se aplicam à API Merchant.

A API Merchant usa cotas para garantir um ambiente estável e justo para todos os usuários. As cotas impedem que um único usuário da API coloque uma carga excessiva no sistema, garantindo um alto desempenho. Entender essas cotas é fundamental para gerenciar os dados de produtos e dimensionar sua empresa no Google.

Conceitos gerais

As cotas da API Merchant são gerenciadas por grupos de cotas.

Os métodos de API são mapeados para grupos de cotas. A estrutura desse mapeamento pode variar:

Método único por grupo: alguns grupos de cotas se aplicam a um único método de API. Por exemplo, o método de listagem de fontes de dados accounts.dataSources.list tem o próprio grupo de cotas dedicado.
Vários métodos por grupo (agrupamento): muitas vezes, métodos relacionados são agrupados em um único grupo de cotas. Todos os métodos desse grupo compartilham os mesmos limites diários e por minuto. São exemplos comuns:
- Agrupamento de todas as operações de leitura para métodos e recursos relacionados, como merchant-accounts-read-methods.
- Agrupar todas as operações de gravação para métodos e recursos relacionados, como merchant-accounts-write-methods.

Cada chamada de método conta uma vez, independentemente do tipo. Uma solicitação list de 250 itens é contabilizada apenas uma vez, não como 250 solicitações get.

O lote HTTP integrado não influencia a cota. Cada solicitação individual em um lote de solicitações conta como uma em relação à cota. Por exemplo, uma solicitação em lote que contém 500 solicitações insert é cobrada como 500 solicitações individuais do método insert.

Exceção para lotes de região dedicada: os métodos de lote de região especializada (batchCreate, batchUpdate, batchDelete) contam como uma única chamada de API no grupo de cotas merchant_regions, independentemente do número de operações de região contidas no payload.

Para gerenciar sua integração de forma eficaz, revise o grupo de cotas específico associado a cada método de API que você pretende usar. Esses detalhes estão no método de lista de cotas. Para mais informações, consulte Monitoramento e visibilidade.

Atualizar política

A API Merchant aplica as seguintes políticas em termos de atualizações:

Por padrão, é possível atualizar seus produtos até duas vezes por dia. Distribua as chamadas de maneira uniforme ao longo do dia para obedecer à cota por minuto.
Por padrão, só é possível atualizar as subcontas até duas vezes por dia. Sua cota diária de atualização de subcontas é um limite agregado com base no total de subcontas permitidas.
Por padrão, só é possível chamar métodos de fonte de dados para suas subcontas, como list ou create, até duas vezes por subconta por dia.

cotas de taxa.

Cada grupo de cotas tem dois tipos de limites (e uso diário):

Limite diário (quotaLimit): o número máximo de solicitações permitidas por dia. Os limites de cota diária são redefinidos às 12h UTC.
Limite por minuto (quotaMinuteLimit): o número máximo de solicitações permitidas por minuto, controlando a taxa de solicitações. Os limites de cota por minuto usam uma janela contínua, em que o período de restrição começa no momento em que a primeira chamada de API para esse método e recurso é feita. Por exemplo, se você fizer uma chamada às 10h01min30s, a janela de cota por minuto para esse método será executada até as 10h02min30s.
Uso diário (quotaUsage): o número de solicitações que já foram feitas e contabilizadas em relação ao limite diário do dia atual. Se o campo estiver ausente, nenhuma cota foi consumida para esse grupo ainda.

Os três campos descritos anteriormente (quotaLimit, quotaMinuteLimit e quotaUsage) estão na resposta do método quotas.list.

Os limites específicos diários e por minuto variam significativamente entre diferentes grupos de cotas. Operações com maior volume esperado ou menor custo do sistema, como ler dados do produto, normalmente têm limites mais altos. Por outro lado, operações mais intensas ou sensíveis, como modificações de conta, podem ter limites mais baixos.

Alocação e hierarquia de cotas

Nesta seção, explicamos em nome de quem a API Merchant rastreia e aplica o uso da cota:

Em geral, a cota é cobrada com base no usuário que faz a solicitação de API.

Contas independentes: para contas independentes que autenticam uma chamada de API, essa solicitação é contabilizada na cota da conta.
- Exemplo: um comerciante Loja de Sapatos A (ID da conta: 12345) faz a autenticação usando a própria conta de serviço para chamar products.insert segmentando a própria conta (accounts/12345). A cota é consumida do pool de cotas da Loja de Sapatos A.
Contas avançadas: a autenticação como uma conta avançada consome a cota do pool da conta avançada, mesmo quando o destino é uma subconta.
- Exemplo: uma Conta de gerente de varejo de uma agência (ID da conta avançada: 12345) gerencia uma subconta da Loja de roupas B (ID da conta: 11111). A agência se autentica usando as próprias credenciais e chama products.insert segmentando a Loja de roupas B (accounts/11111). A cota é consumida do pool da agência principal (ID da conta avançada: 12345), não do pool da subconta.
Subcontas: quando as chamadas de API são autenticadas usando as credenciais de uma subconta, a cota é cobrada do pool individual dessa subconta. Ela funciona da mesma forma que uma conta independente, mesmo que seja gerenciada por uma conta avançada principal.
- Exemplo: usando a mesma configuração anterior, se a Loja de roupas B (ID da conta: 11111) se autenticar usando credenciais configuradas especificamente para a subconta dela para chamar products.insert segmentando a própria conta (accounts/11111), a cota será consumida do pool de cotas individual da Loja de roupas B, deixando o pool da agência principal intocado.

Exceções às regras gerais

Há algumas exceções específicas que se aplicam às regras gerais de alocação de cotas:

Accounts.list: a cota desse método é cobrada do usuário autenticado ou da conta de serviço que faz a chamada, não do ID da conta do Merchant Center. O uso da cota não vai aparecer na página de diagnóstico padrão da API Merchant Center. Se você tiver uma conta avançada, recomendamos usar o método accounts.listSubaccounts, que é contabilizado na sua cota de contas avançadas.
Métodos de resolução de problemas: esses métodos sempre são contabilizados na cota da conta que está solicitando a resolução de problemas, mesmo que uma conta diferente esteja autenticando a solicitação.

Hierarquia de alocação

Serviços de comparação de preços (CSSs): são sites que agregam ofertas de produtos e direcionam os usuários aos sites dos varejistas para fazer compras. Ao fazer chamadas de API, as cotas são aplicadas ao grupo do CSS, domínio do CSS, conta ou subconta específica que você autentica.

Exemplos:
- Um grupo do CSS chamado Europe Shopping Group (ID da conta: 10001) quer listar os domínios do CSS associados. Ao se autenticar com as próprias credenciais para fazer essa chamada de API, a cota é consumida diretamente do pool de cotas do Europe Shopping Group.
- Um domínio do CSS TopDeals CSS (ID da conta: 20002) se autentica para chamar um método que segmenta uma das contas do comerciante associadas (accounts/30003) para atribuir um rótulo. A cota é consumida do pool de cotas do CSS TopDeals, não do pool da conta do comerciante.
Marketplaces: são plataformas on-line que hospedam vários comerciantes individuais. Elas funcionam como contas avançadas especiais que permitem criar subcontas individuais para cada um dos seus vendedores.

O diagrama a seguir mostra a hierarquia de grupos do CSS, CSS, marketplaces, contas avançadas, contas independentes e subcontas.

Um grupo do CSS é o nível de autenticação geral,
com a possibilidade de CSSs individuais, contas dentro deles e
subcontas como o nível mais individual.

Ajuste automático de cotas

A API Merchant tem um sistema de gerenciamento automático de cotas para serviços específicos, que ajusta os limites de cota para comerciantes em crescimento com base no uso, na oferta e no tamanho da conta. A API Merchant recalcula essas cotas diariamente.

Os grupos de cotas incluídos nos ajustes automáticos são:

Serviços de produtos

Todos os grupos de cotas de métodos relacionados aos recursos products e productInputs.
A cota diária de chamadas geralmente é definida como duas vezes o número de ítens que o comerciante tem. Isso pressupõe que um comerciante pode precisar atualizar cada um dos produtos até duas vezes por dia.
Os produtos individuais podem ser atualizados mais de duas vezes, mas o total de chamadas de API diárias não pode exceder a cota agregada de chamadas diárias.

Serviços de contas

Todos os grupos de cotas de métodos relacionados aos vários recursos granulares relacionados à conta na API Merchant.
A cota diária de chamadas é definida como o número máximo de subcontas permitido para essa conta. Isso permite até duas chamadas de leitura por subconta por dia.

Serviços de fontes de dados

Todos os grupos de cotas de métodos relacionados aos recursos relacionados à fonte de dados na API Merchant, como list ou create, que uma conta avançada realiza nas subcontas.
A cota diária de chamadas geralmente é definida como o dobro do número de subcontas da conta avançada. Isso pressupõe que um comerciante pode atualizar as fontes de dados de cada uma das subcontas até duas vezes por dia.

Somente os serviços descritos anteriormente têm ajustes automáticos de cotas. Outros serviços têm uma cota padrão, e qualquer aumento precisa ser solicitado manualmente. Para mais informações, consulte a seção sobre o processo de aumento de cota.

O que acontece quando as cotas são excedidas

Depois que uma cota é excedida, erros aparecem nas respostas da API e na página de diagnóstico da sua conta do Merchant Center:

Por minuto: 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"
                }
            }
        ]
    }
}

Por dia: 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"
                }
            }
        ]
    }
}

Os erros a seguir são limites do Merchant Center e não estão relacionados às cotas da API Merchant. Você pode tentar solicitar uma cota adicional de itens, feeds ou subcontas:

too_many_items: cota do comerciante excedida
too_many_subaccounts: Número máximo de subcontas atingido

Monitoramento e visibilidade

Para verificar as cotas de chamada e o uso atuais de uma conta, chame quotas.list com o nome da conta.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Substitua:

ACCOUNT_ID: seu ID do Merchant Center
ACCESS_TOKEN: o token de autorização para fazer a chamada de API.

Após uma solicitação bem-sucedida, a API retorna uma lista de recursos quotaGroups que contêm o recurso name do grupo de cotas, as diferentes cotas e os métodos aos quais a cota do grupo se aplica.

{
    "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"
        }
    ]
}

Processo de aumento de cotas

Para solicitar mais cota, abra o formulário de contato com o suporte, selecione "Solicitação de aumento de cota" no campo obrigatório "Qual é o problema/pergunta" e preencha todos os campos obrigatórios, incluindo o ID do Merchant Center, os métodos de segmentação e a justificativa comercial.

Para recursos com cotas automáticas (products, accounts e datasources para contas avançadas): é possível solicitar apenas um aumento temporário para cenários especiais, como o lançamento em um novo mercado ou durante temporadas de compras com alto tráfego. Não aceitamos aumentos permanentes de cota para esses tipos de recursos.
Para todos os outros recursos sem cotas automáticas: solicite aumentos de cota conforme necessário.

Recomendamos verificar suas cotas periodicamente para garantir que você tenha cota suficiente para sua implementação e ver como sua cota é ajustada automaticamente. Use o método quotas.list para ver o limite de cota diária atual, o limite por minuto e o uso diário atual de cada grupo de métodos de API.

Práticas recomendadas

A implementação dessas práticas recomendadas ajuda a garantir que sua integração funcione sem problemas, evita erros de cota inesperados e usa os recursos do Merchant Center com eficiência.

Otimizar a distribuição de solicitações

Distribua as solicitações de maneira uniforme: evite enviar grandes picos de solicitações. Distribua suas chamadas de API diárias de maneira uniforme ao longo do dia para não ultrapassar os limites de cota por minuto (quotaMinuteLimit).
Limitação proativa: implemente a limitação de taxa do lado do cliente (limitação) no aplicativo. Não dependa apenas dos servidores do Google para rejeitar o excesso de tráfego. Controle a taxa de solicitação na origem.

Tratamento de erros elegante

Processar HTTP 429: seu aplicativo precisa estar preparado para processar erros 429 de excesso de solicitações (quota/request_rate_too_high).
Espera exponencial com instabilidade: ao repetir solicitações com falha (especialmente após um erro 429), use a espera exponencial (aumentando os tempos de espera) e adicione "instabilidade" (atraso aleatório). A instabilidade evita "tempestades de novas tentativas", em que várias instâncias de cliente tentam novamente ao mesmo tempo, sobrecarregando o servidor de novo.
Respeite as dicas de nova tentativa: se a resposta da API tiver detalhes ou cabeçalhos de nova tentativa, use-os para determinar quando retomar as chamadas.

Minimizar chamadas redundantes

Evitar chamadas desatualizadas (404 NOT_FOUND): evite solicitar ou excluir recursos que não existem mais. Até mesmo as chamadas com falha consomem a cota da API. Monitore os erros NOT_FOUND no Diagnóstico de API do Merchant Center para detectar rastreamento de estado desatualizado ou sondagem desnecessária.
Verifique antes de atualizar: antes de enviar uma solicitação de atualização, confira se os dados realmente mudaram. Evite enviar atualizações que gravam os mesmos valores.
Use o armazenamento em cache: armazene em cache as respostas de leitura (por exemplo, detalhes do produto, configurações) localmente quando apropriado para evitar chamadas repetitivas de get ou list para dados inalterados.

Navegar pela hierarquia de cotas e exceções

Contas avançadas e subcontas: se você tiver uma conta avançada, faça a autenticação no nível dela se quiser que as chamadas sejam contabilizadas no pool compartilhado de contas avançadas.
Use listSubaccounts: para contas avançadas, use accounts.listSubaccounts em vez de accounts.list. A cota de accounts.list é cobrada do usuário que faz a chamada (não do ID do MC) e não fica visível no diagnóstico padrão. listSubaccounts é contabilizado na sua cota de MCA.

Overview

Avançar

Merchant Center limits