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 comerciais 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 do 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 de terceiros 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 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, México, Países Baixos e Reino Unido.
  • 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:

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

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.

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.

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.

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

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.

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

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 qualquer descrição configurada 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.

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

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.

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

Anterior
Overview
Avançar
Manage customer loyalty data