A API Merchant v1beta foi descontinuada e desativada em 28 de fevereiro de 2026. Para saber como fazer a transição para a versão estável mais recente, consulte Migrar da v1beta para a v1.

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 lealdade na API Merchant. Esse serviço permite que os 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 o upload de dados de fidelidade, que são usados para oferecer recursos de personalização de fidelidade orgânica na Pesquisa Google, como a exibição de preços específicos para membros. Use o ManageLoyaltyCustomerMatch método personalizado para associar seus clientes a níveis de programa de fidelidade, permitindo que você insira, atualize ou remova o status de fidelidade deles 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 a análise não autorizada da conta, 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: combine 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.
Processamento baseado 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 análise 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. 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 verifique se você definiu os níveis de fidelidade.
Conhecimento da ordem de níveis: esteja ciente da 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 deve inserir, atualizar ou remover o status de nível de fidelidade de um cliente. 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. Mapeia para a ordem do nível na configuração do Merchant Center. Para mais detalhes, consulte Noções básicas sobre o mapeamentoloyaltyTier. Use NON_MEMBER para remover uma associação.
pointBalance: o saldo de pontos atual do cliente.

Campos userIdentifier

Pelo menos um dos seguintes campos precisa ser fornecido:

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

Noções básicas sobre o mapeamento de `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 de ouro") ou 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 ao terceiro ao sétimo níveis 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: "Gold Member", rótulo do nível: "gold"
Nome do nível: "Platinum Elite", rótulo do nível: "platinum"

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

Para atribuir um cliente ao "Silver Status", use loyaltyTier: TIER1.
Para atribuir um cliente ao "Gold Member", 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)

Noções básicas sobre o corpo da resposta ManageLoyaltyCustomerMatch

O método ManageLoyaltyCustomerMatch retorna um ManageLoyaltyCustomerMatchResponse objeto:

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

Considerações importantes sobre possíveis 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ê corresponde a um usuário do Google com o userIdentifier fornecido
- você define o loyaltyTier na solicitação para 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 os dados foram processados e armazenados:

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

Exclusão bem-sucedida: para remover qualquer associação de fidelidade existente para o cliente com esse 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 retornará um status HTTP 200 OK com um objeto JSON vazio: {}. Isso acontece para tentativas de upsert e remoção.

Exemplos

TIER1 corresponde ao primeiro nível definido do comerciante, o chamado "Basic", e TIER2 ao segundo - "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 consentido, 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 consentiu, 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 ao 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 identificador 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 de 404 NOT_FOUND :

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