Visão geral dos programas de fidelidade

Mostre os benefícios da sua loja no Google usando programas de fidelidade. Você pode enviar 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 nas plataformas do Google, incluindo a Pesquisa Google, a guia "Shopping" e a Carteira do Google.

Com a API Merchant, os comerciantes e provedores de fidelidade terceirizados que agem em nome dos comerciantes 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.

Importante: o serviço está disponível apenas para algumas lojas. Entre em contato com a equipe de suporte para manifestar interesse em participar enviando um pedido de inclusão na lista de permissões no Formulário de suporte da API Shopping em Qual é o problema/a dúvida? > Solicitação de lista de permissões > Outro.

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

Principais conceitos

Ao trabalhar com programas de fidelidade, tenha em mente os seguintes conceitos e limitações:

• 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 oferece suporte ao gerenciamento de programas de fidelidade em um nível avançado de conta 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.
• Regiões disponíveis:os programas de fidelidade dos comerciantes estão disponíveis nos países participantes, incluindo Austrália, Brasil, Canadá, França, Alemanha, Índia, Itália, México, Países Baixos, Coreia do Sul, Espanha, Reino Unido e Estados Unidos.
• 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.
• Benefícios:os programas oferecem frete grátis, pontos resgatáveis e preços para membros. Em anúncios, o preço para membros exige um desconto de pelo menos 5% ou 5 unidades da moeda 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 for um provedor de fidelidade terceirizado.
• Ative o complemento do programa Fidelidade na sua conta. É possível ativar o complemento usando uma das seguintes opções:
  • Interface do Merchant Center:siga as instruções em Configurar um programa de fidelidade na Ajuda do Merchant Center.
  • Sub-API Programs:ative o programa de forma programática, conforme descrito em Ativar programas na sub-API Programs.

Confira 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

Métodos

Gerencie programas de fidelidade usando os seguintes métodos:

• loyaltyPrograms.create
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.delete

Criar um programa de fidelidade

Para criar um 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 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.

Confira 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.

Confira 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 específico de propriedade própria, use o método loyaltyPrograms.get.

Observação: mesmo que o complemento do programa de fidelidade não esteja ativado, esse endpoint ainda responde com um programa de fidelidade correspondente sem retornar um erro.

Confira 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).

Confira 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.

Observação: esse método lista apenas os programas de fidelidade pertencentes diretamente à conta especificada, não os associados a subcontas. Mesmo que o complemento do programa de fidelidade esteja desativado, esse endpoint responde com os programas atuais sem retornar um erro.

Confira um exemplo de solicitação:

HTTP

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

Confira 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.

Importante: ao atualizar um programa de fidelidade, não é possível atualizar no lugar os campos repetidos, como programDescriptions e tiers. Qualquer campo repetido incluído em uma atualização substitui toda a lista atual. Para evitar a perda de dados não intencional, envie uma solicitação get primeiro para recuperar os valores atuais antes de atualizar os campos repetidos.

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

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

A solicitação de amostra 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.

Confira 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 faz uma substituição completa da configuração do programa de fidelidade.

Confira 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
      }
    }
  ]
}

Confira 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.

Confira 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

• Para associar compradores individuais aos níveis do seu programa de fidelidade para personalização orgânica na Pesquisa Google, consulte o guia do serviço de segmentação por lista de clientes de fidelidade.
• Para ativar ou desativar programas do Shopping na sua conta, consulte o guia da sub-API Programs.
• Para detalhes sobre a configuração da empresa, políticas editoriais e relatórios, consulte Sobre o programa de fidelidade do comerciante na Ajuda do Merchant Center.
• Para conferir métodos de API e definições de recursos, consulte a referência da API Merchant.