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.

Visão geral do serviço de segmentação por lista de clientes de fidelidade

Neste guia, descrevemos como usar o serviço de Segmentação por Lista de Clientes de Fidelidade na API Merchant. Esse serviço permite que comerciantes e provedores de fidelidade terceirizados que atuam em nome de comerciantes gerenciem dados de fidelidade do cliente, como identificadores de usuário e informações de nível, para personalização orgânica na Pesquisa Google, sem precisar de uma conta ativa do Google Ads.

Visão geral

Use o serviço de Segmentação por Lista de Clientes com Fidelidade para fazer upload de dados de fidelidade, que são usados para oferecer recursos de personalização de fidelidade orgânica na Pesquisa Google, como mostrar preços específicos para membros. Use o método personalizado ManageLoyaltyCustomerMatch para associar seus clientes aos níveis do programa de fidelidade, permitindo inserir, atualizar ou remover o status de fidelidade deles com base em identificadores de usuário.

Principais conceitos

Interface unificada: um endpoint exclusivo para adicionar, atualizar ou remover detalhes do nível de fidelidade do cliente.
Design com foco em privacidade: para proteger a privacidade do usuário e evitar sondagens não autorizadas de contas, a API não oferece suporte às operações GET ou LIST, garantindo que os dados sejam gerenciados sem recuperação ou auditoria.
Identificação flexível: faça a correspondência de usuários usando pelo menos um identificador válido, como endereço de e-mail, endereço físico ou número de telefone.
Processamento com base em consentimento: o serviço armazena e usa os dados do cliente somente quando o usuário final concede o consentimento necessário ao Google. Para proteger e evitar a sondagem da existência da conta ou o status de consentimento, o serviço retorna um sucesso silencioso se não houver correspondência ou se o consentimento não for concedido.

Pré-requisitos

Siga estes requisitos para usar o serviço de Segmentação por Lista de Clientes com Fidelidade:

Configuração da conta: verifique se você tem uma conta ativa do Merchant Center (ou acesso autorizado à conta do comerciante, se você for um provedor de fidelidade terceirizado). Não é necessário criar uma conta do Google Ads para usar o serviço de Segmentação por Lista de Clientes de Fidelidade.
Configuração do programa de fidelidade: ative o programa de fidelidade na sua conta do Merchant Center e defina os níveis de fidelidade.
Ordem dos níveis: preste atenção à ordem em que os níveis de fidelidade são definidos na interface do Merchant Center. A API usa essa sequência exata para o mapeamento de tipo enumerado.

Método: `ManageLoyaltyCustomerMatch`

O método ManageLoyaltyCustomerMatch serve como a interface central para gerenciar associações de fidelidade do cliente. Com base na entrada fornecida, o serviço determina automaticamente se o status do nível de fidelidade de um cliente será inserido, atualizado ou removido. A operação é idempotente: solicitações idênticas repetidas têm o mesmo efeito que uma única solicitação.

A solicitação a seguir demonstra como gerenciar associações de fidelidade do cliente pela API:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

Essa solicitação define os seguintes parâmetros de caminho obrigatórios:

API_VERSION: a versão da API, como v1.
ACCOUNT_ID: o ID da conta do Merchant Center.

Inclua um objeto loyaltyCustomer no corpo da solicitação.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

Campos loyaltyCustomer

userIdentifier: o conjunto de identificadores usados para corresponder ao cliente. Pelo menos um campo em userIdentifier precisa ser fornecido e válido.
loyaltyTier: o nível de fidelidade a ser associado ao cliente. É associado à ordem do nível na configuração do Merchant Center. Para mais detalhes, consulte Noções básicas sobre o mapeamento do loyaltyTier. Use NON_MEMBER para remover uma associação.
pointBalance: o saldo de pontos atual do cliente.

Campos userIdentifier

Informe pelo menos um dos seguintes campos:

emailAddress: o endereço de e-mail do cliente.
address: o endereço físico do cliente. O campo PostalCode é obrigatório.
phoneNumber: o número de telefone do cliente. O formato E.164 é recomendado.

Entender o mapeamento do `loyaltyTier`

A API não usa os nomes personalizados. Os valores de tipo enumerado loyaltyTier (TIER1 a TIER7) são rótulos semânticos. Eles não usam os nomes personalizados (por exemplo, "Gold Rewards") ou os rótulos personalizados (por exemplo, "gold_tier") que você atribuiu na interface do Merchant Center. Em vez disso, eles são mapeados estritamente para a ordem em que você definiu os níveis nas configurações do programa de fidelidade no Merchant Center:

TIER1: corresponde ao primeiro nível listado na configuração do programa de fidelidade do Merchant Center.
TIER2: corresponde ao segundo nível listado na configuração do programa de fidelidade do Merchant Center.
TIER3 a TIER7: correspondem do terceiro ao sétimo nível listados na configuração do programa de fidelidade do Merchant Center.

Exemplo:

Se o programa de fidelidade do Merchant Center tiver níveis definidos nesta ordem:

Nome do nível: "Status Prata", rótulo do nível: "prata"
Nome do nível: "Membro Ouro", rótulo do nível: "ouro"
Nome do nível: "Platinum Elite", rótulo do nível: "platinum"

Em seguida, nas chamadas de API accounts.loyaltyCustomers.manage:

Para atribuir um cliente ao "Status Prata", use loyaltyTier: TIER1.
Para atribuir um cliente a "Membro Gold", use loyaltyTier: TIER2.
Para atribuir um cliente à categoria "Platinum Elite", use loyaltyTier: TIER3.

Valores de tipo enumerado LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (usado para sinalizar a remoção da associação de fidelidade do cliente)

Entender o corpo da resposta de ManageLoyaltyCustomerMatch

O método ManageLoyaltyCustomerMatch retorna um objeto ManageLoyaltyCustomerMatchResponse:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Considerações importantes para respostas

Upsert bem-sucedido (dados armazenados): para armazenar ou atualizar a associação de nível de fidelidade de um cliente, atenda às seguintes condições:
- você faz a correspondência de um usuário do Google com o userIdentifier fornecido.
- você definir o loyaltyTier na solicitação como um valor válido diferente de NON_MEMBER;
- o usuário correspondente consentiu com o uso de dados de fidelidade

A resposta contém o objeto loyaltyCustomer da sua solicitação, indicando que o serviço processou e armazenou os dados:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

Exclusão bem-sucedida: para remover qualquer associação de fidelidade existente do cliente com esse comerciante, as seguintes condições precisam ser atendidas:
- você faz a correspondência de um usuário do Google com o userIdentifier fornecido.
- você definir o loyaltyTier na solicitação como NON_MEMBER;

A resposta é um objeto JSON vazio:

{}

Nenhuma correspondência / nenhum consentimento (sucesso silencioso): se o userIdentifier fornecido não corresponder a uma Conta do Google ou se o usuário correspondente não tiver consentido com o uso de dados de fidelidade, a API vai retornar um status HTTP 200 OK com um objeto JSON vazio: {}. Isso acontece tanto para tentativas de upsert quanto de remoção.

Exemplos

TIER1 corresponde ao primeiro nível definido (por exemplo, 'Basic'), e TIER2 corresponde ao segundo nível (por exemplo, 'Premium').

Para adicionar um cliente ao TIER2 ou atualizar o status dele usando um endereço de e-mail, envie a seguinte solicitação:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Quando um usuário é correspondido e dá o consentimento, a API retorna a seguinte resposta:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Quando não há correspondência ou o usuário não deu consentimento, a API retorna a seguinte resposta:

{}

Para remover a associação de fidelidade de um cliente usando um número de telefone, envie a seguinte solicitação:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Independentemente de um registro existir, a API retorna a seguinte resposta de sucesso:

{}

Para adicionar ou atualizar um cliente usando vários identificadores, envie a seguinte solicitação:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

A resposta é semelhante à do primeiro exemplo, dependendo da correspondência e do consentimento.

Tratamento de erros

A API usa códigos HTTP padrão. As strings de erro comuns incluem:

Código HTTP	String de erro	Descrição
400	INVALID_ARGUMENT	user_identifier ou loyalty_tier ausente, ou o identificador está vazio.
401	UNAUTHENTICATED	Credenciais inválidas ou ausentes.
403	PERMISSION_DENIED	O usuário autenticado não tem acesso à conta do Merchant Center especificada.
404	NOT_FOUND	O rótulo do nível de fidelidade especificado não existe na sua configuração.
412	FAILED_PRECONDITION	Você não configurou um programa de fidelidade na sua conta.
429	RESOURCE_EXHAUSTED	Limite de cota atingido.

Exemplos de erro

Exemplo de 404 NOT_FOUND:

Qualquer solicitação válida para um ID da conta que não tenha um programa de fidelidade configurado.