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

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

Este guia descreve 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 dos 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 exigir uma conta ativa do Google Ads.

Visão geral

Use o serviço de Segmentação por lista de clientes de fidelidade para fazer upload de dados de fidelidade, que são usados para oferecer recursos de personalização orgânica de fidelidade na Pesquisa Google, como mostrar preços específicos para membros. Você usa o método personalizado ManageLoyaltyCustomerMatch para associar seus clientes a níveis do programa de fidelidade, permitindo inserir, atualizar ou remover o status de fidelidade com base nos 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 na privacidade:para proteger a privacidade do usuário e evitar sondagens não autorizadas de contas, a API não oferece suporte a 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 um endereço de e-mail, endereço físico ou número de telefone.
Tratamento com base em consentimento:o serviço armazena e usa dados do cliente somente quando o usuário final concedeu o consentimento necessário ao Google. Para proteger e evitar a sondagem da existência da conta ou do status de consentimento, o serviço retorna um sucesso silencioso se uma correspondência não for feita ou o consentimento não for concedido.

Pré-requisitos

Siga estes requisitos para usar o serviço de Segmentação por lista de clientes de fidelidade:

Configuração da conta:verifique se você tem uma conta ativa do Merchant Center ou acesso autorizado à conta do comerciante, caso seja 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 níveis de fidelidade.
Ordem dos níveis:saiba a 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 enumeração.

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 é necessário inserir, atualizar ou remover o status de um cliente no nível de fidelidade. 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. Corresponde à 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

Forneça pelo menos um dos seguintes campos:

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

Entender o mapeamento `loyaltyTier`

A API não usa os nomes personalizados. Os valores de enumeração loyaltyTier (TIER1 a TIER7) são rótulos semânticos. Eles não usam os nomes personalizados (por exemplo, "Recompensas Ouro") ou os rótulos personalizados (por exemplo, "nível_ouro") 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 aos níveis do terceiro ao sétimo 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: "Silver Status", Rótulo do nível: "silver"
Nome do nível: "Membro Gold", rótulo do nível: "gold"
Nome do nível: "Platinum Elite", Rótulo do nível: "platinum"

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

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

Valores de enumeração 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 ManageLoyaltyCustomerMatch

O método ManageLoyaltyCustomerMatch retorna um objeto ManageLoyaltyCustomerMatchResponse:

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

Considerações importantes sobre as respostas

Upsert bem-sucedido (dados armazenados): para armazenar ou atualizar com êxito uma associação de nível de fidelidade de um cliente, atenda às seguintes condições:
- você corresponde a um usuário do Google com o userIdentifier fornecido
- você define o loyaltyTier na solicitação com um valor válido diferente de NON_MEMBER
- o usuário correspondente deu consentimento para 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 uma associação de fidelidade existente do cliente com o comerciante, as seguintes condições precisam ser atendidas:
- você corresponde a um usuário do Google com o userIdentifier fornecido
- você define 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 nas tentativas de upsert e 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á 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"
  }'

Independente de um registro ter existido ou não, 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 ao primeiro exemplo, dependendo da correspondência e do consentimento.

Tratamento de erros

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

Código HTTP	Error String	Descrição
400	INVALID_ARGUMENT	O user_identifier ou loyalty_tier está 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 especificada do Merchant Center.
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 para 404 NOT_FOUND:

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