Visão geral dos programas de fidelidade

Mostre os benefícios da sua loja no Google usando programas de fidelidade. Você pode adicionar vários benefícios, como frete grátis, pontos resgatáveis e preços exclusivos para membros. Os benefícios do seu programa de fidelidade podem aparecer em listagens sem custo financeiro, anúncios do Shopping e anúncios de inventário local em plataformas do Google, incluindo a Pesquisa Google, a guia "Shopping" e a Carteira do Google.

Com a API Merchant, os comerciantes e os provedores de fidelidade terceirizados que atuam em nome deles podem configurar e manter programas de fidelidade de forma programática usando o LoyaltyProgramService. Esse serviço permite criar, recuperar, listar, atualizar e excluir programas de fidelidade.

Para mais informações sobre os requisitos de negócios e as diretrizes da política, consulte Sobre o programa de fidelidade do comerciante na Central de Ajuda do Merchant Center.

Principais conceitos

Considere os seguintes conceitos e limitações ao trabalhar com programas de fidelidade:

  • Identificador no nível da conta: a API Merchant identifica os programas de fidelidade pelo ID da conta do Merchant Center proprietária.

  • Limite de um único programa: a API Merchant aceita apenas um programa de fidelidade por conta do comerciante.

  • Propriedade direta da conta: os programas de fidelidade precisam ser configurados diretamente na conta de comerciante de destino (accounts/{ACCOUNT_ID}). O serviço não permite gerenciar programas de fidelidade em um nível de conta avançado para subcontas. Os provedores de fidelidade terceirizados com acesso autorizado à conta de um comerciante podem gerenciar o programa em nome dele.

  • Revisão editorial: depois de criar ou atualizar um programa de fidelidade, ele passa por uma revisão. O campo review_result.review_status indica se o programa é UNDER_REVIEW, APPROVED ou REJECTED. Cada atualização bem-sucedida envia o programa de volta para a fila de revisão, mesmo que não mude nada importante. O Google oculta o programa dos compradores durante o processo de análise. A análise pode levar até 48 horas.

  • Regiões com disponibilidade: os programas de fidelidade do comerciante estão disponíveis em países com disponibilidade, incluindo Alemanha, Austrália, Brasil, Canadá, Coreia do Sul, Espanha, Estados Unidos, França, Índia, Itália, Japão, México, Países Baixos e Reino Unido.

  • Regiões ativas: o regionCodes de um programa de fidelidade precisa ser um subconjunto do activeRegionCodes de accounts/{ACCOUNT_ID}/programs/loyalty. Caso contrário, as solicitações de criação, atualização e exclusão vão falhar com um erro LOYALTY_PROGRAM_DISABLED. O Google ativa um país compatível quando o complemento do programa de fidelidade está ativado e a conta atende aos requisitos de qualificação nesse país. Por exemplo, a conta estará qualificada se o programa de listagens sem custo financeiro estiver ativado e uma fonte de dados de produtos principal segmentar o país para o destino FREE_LISTINGS. Para saber por que um país não está ativo, consulte Verificar regiões ativas.

  • Requisitos de nível: os níveis podem não ter custo para participar, exigir uma taxa de associação, um limite de gastos ou um cartão de crédito da marca do comerciante. Níveis com base na ocupação (como estudante ou militar) não são aceitos.

  • Vantagens e benefícios: os programas oferecem frete grátis, pontos resgatáveis e preços para membros. Nos anúncios, o preço para membros exige um desconto de pelo menos 5% ou 5 unidades monetárias abaixo do preço normal ou promocional.

Pré-requisitos

Antes de gerenciar programas de fidelidade com a API Merchant, verifique se você atende aos seguintes requisitos:

  • Você precisa ter uma conta ativa do Merchant Center (ou acesso autorizado à conta do comerciante se você for um provedor de fidelidade terceirizado).

  • Ative o complemento do programa de fidelidade na sua conta. É possível ativar o complemento usando uma das seguintes opções:

  • Os países em que você quer oferecer seu programa de fidelidade precisam estar ativos na sua conta. Para saber quais países estão ativos, consulte Verificar regiões ativas.

Veja um exemplo de solicitação para ativar o complemento do programa de fidelidade usando a sub-API Programs:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable

cURL

curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

Verificar regiões ativas

Depois de ativar o complemento do programa de fidelidade, chame o método accounts.programs.get para accounts/{ACCOUNT_ID}/programs/loyalty. A resposta mostra onde você pode usar programas de fidelidade e por que outros países aceitos estão inativos.

Veja um exemplo de solicitação:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

Substitua {ACCOUNT_ID} pelo identificador exclusivo da sua conta do Merchant Center.

Veja um exemplo de resposta para uma conta que ativou o complemento e está qualificada apenas nos Estados Unidos:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

Nessa resposta, observe os seguintes campos:

  • activeRegionCodes: os países que você pode usar no regionCodes do seu programa de fidelidade. No exemplo anterior, apenas US está ativo.
  • unmetRequirements: o motivo pelo qual outros países aceitos estão inativos. Para programas de fidelidade, esse é o requisito IS_ELIGIBLE_FOR_LOYALTY.
    • affectedRegionCodes: os países aceitos em que a conta não está qualificada.
    • documentationUri: um link para os requisitos de qualificação.

No exemplo anterior, ainda não é possível usar os países em affectedRegionCodes. Se o regionCodes do seu programa de fidelidade incluir um deles, as solicitações de criação, atualização e exclusão vão falhar com um erro LOYALTY_PROGRAM_DISABLED. Para ativar um país, faça o seguinte:

  1. Tornar a conta qualificada nesse país. Por exemplo, ative o programa de listagens sem custo financeiro e defina uma fonte de dados de produtos principal para segmentar o país do destino FREE_LISTINGS. Para saber como se qualificar, consulte os requisitos de qualificação.
  2. Chame accounts.programs.get novamente e verifique se o país está em activeRegionCodes.

affectedRegionCodes pode incluir países onde você não vende. Você não precisa fazer nada para esses países. Eles não afetam os países em activeRegionCodes.

Métodos

Gerencie programas de fidelidade usando os seguintes métodos:

Criar um programa de fidelidade

Para criar um novo programa de fidelidade para uma conta, use o método loyaltyPrograms.create. Especifique detalhes como descrições do programa, o URL de inscrição e os níveis do programa com os benefícios e requisitos exclusivos.

O program_label obrigatório define o identificador exclusivo do programa de fidelidade. Por exemplo, fornecer o rótulo my-rewards resulta em um recurso name de accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Veja um exemplo de solicitação:

HTTP

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}

Substitua {ACCOUNT_ID} pelo identificador exclusivo da sua conta do Merchant Center.

Veja um exemplo de resposta de uma solicitação bem-sucedida:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Recuperar um programa de fidelidade

Para recuperar os detalhes de um programa de fidelidade próprio específico, use o método loyaltyPrograms.get.

Veja um exemplo de solicitação:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Substitua {ACCOUNT_ID} pelo ID da sua conta e {PROGRAM_LABEL} pelo rótulo exclusivo do programa de fidelidade (por exemplo, my-rewards).

Veja um exemplo de resposta de uma solicitação bem-sucedida:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Listar programas de fidelidade

Para listar todos os programas de fidelidade próprios associados à sua conta, use o método loyaltyPrograms.list.

Veja um exemplo de solicitação:

HTTP

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

Veja um exemplo de resposta de uma solicitação bem-sucedida:

{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}

Atualizar um programa de fidelidade

Para atualizar um programa de fidelidade, use o método loyaltyPrograms.update. Faça uma atualização parcial usando um update_mask ou uma substituição completa omitindo a máscara. Cada atualização bem-sucedida aciona uma nova revisão editorial. Portanto, envie uma atualização somente quando um valor mudar.

Atualização parcial com máscara de atualização

Uma update_mask permite especificar os campos exatos a serem atualizados. Somente os campos listados na máscara são modificados, enquanto os campos não listados permanecem inalterados. Qualquer campo omitido da máscara de atualização é ignorado, mesmo que seja fornecido no corpo da solicitação.

O exemplo de solicitação a seguir atualiza apenas programDescriptions e advancedSettings:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}

Neste exemplo, o serviço ignora signupUrl porque ele não está incluído no update_mask. O campo programDescriptions substitui completamente as descrições configuradas anteriormente.

Veja um exemplo de resposta de uma solicitação bem-sucedida:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}

Substituição completa sem máscara de atualização

Quando você omite o parâmetro update_mask, a solicitação realiza uma substituição completa da configuração do programa de fidelidade.

Veja um exemplo de solicitação:

HTTP

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}

Veja um exemplo de resposta de uma solicitação bem-sucedida:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}

Excluir um programa de fidelidade

Para excluir um programa de fidelidade da sua conta, use o método loyaltyPrograms.delete.

Veja um exemplo de solicitação:

HTTP

DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

Se a solicitação for concluída, o corpo da resposta estará vazio.

Próximas etapas

Anterior
Overview
Avançar
Manage customer loyalty data