Omówienie programów lojalnościowych

Prezentuj korzyści z zakupów w Twoim sklepie w Google za pomocą programów lojalnościowych. Możesz przesłać wiele korzyści, takich jak bezpłatna dostawa, punkty do wykorzystania przez klientów oraz specjalne ceny dla uczestników programu. Korzyści z udziału w programie lojalnościowym mogą się wyświetlać w bezpłatnych informacjach, reklamach produktowych i reklamach lokalnego asortymentu produktów na platformach Google, takich jak wyszukiwarka Google, karta Zakupy czy Portfel Google.

Dzięki interfejsowi Merchant API sprzedawcy i zewnętrzni dostawcy programów lojalnościowych działający w imieniu sprzedawców mogą programowo konfigurować i utrzymywać programy lojalnościowe za pomocą LoyaltyProgramService. Ta usługa umożliwia tworzenie, pobieranie, wyświetlanie, aktualizowanie i usuwanie programów lojalnościowych.

Ważne: usługa jest dostępna tylko dla wybranych sprzedawców. Skontaktuj się z zespołem pomocy, aby wyrazić zainteresowanie udziałem, przesyłając prośbę o umieszczenie na liście dozwolonych w formularzu pomocy interfejsu Shopping API w sekcji Na czym polega problem lub czego dotyczy pytanie? > Allowlist request > Other.

Więcej informacji o wymaganiach biznesowych i wytycznych dotyczących zasad znajdziesz w artykule Informacje o programie lojalnościowym sprzedawcy w Centrum pomocy Merchant Center.

Kluczowe pojęcia

Podczas pracy z programami lojalnościowymi pamiętaj o tych kwestiach i ograniczeniach:

• Identyfikator na poziomie konta: interfejs Merchant API identyfikuje programy lojalnościowe według identyfikatora konta Merchant Center, do którego należą.
• Limit jednego programu: interfejs Merchant API obsługuje tylko jeden program lojalnościowy na konto sprzedawcy.
• Bezpośrednia własność konta: programy lojalnościowe muszą być skonfigurowane bezpośrednio na docelowym koncie sprzedawcy (accounts/{ACCOUNT_ID}). Usługa nie obsługuje zarządzania programami lojalnościowymi na poziomie konta zaawansowanego w przypadku subkont. Zewnętrzni dostawcy programów lojalnościowych, którzy mają autoryzowany dostęp do konta sprzedawcy, mogą zarządzać programem w imieniu sprzedawcy.
• Sprawdzanie pod kątem zgodności z zasadami: po utworzeniu lub zaktualizowaniu programu lojalnościowego jest on sprawdzany. Pole review_result.review_status wskazuje, czy program jest UNDER_REVIEW, APPROVED czy REJECTED.
• Obsługiwane regiony: programy lojalnościowe sprzedawców są dostępne w obsługiwanych krajach, w tym w Australii, Brazylii, Francji, Hiszpanii, Holandii, Indiach, Kanadzie, Korei Południowej, Meksyku, Niemczech, Stanach Zjednoczonych, Wielkiej Brytanii i we Włoszech.
• Wymagania dotyczące poziomów: poziomy mogą być bezpłatne, wymagać opłaty członkowskiej, progu wydatków lub karty kredytowej marki sprzedawcy. Poziomy oparte na zawodzie (np. student, żołnierz itp.) nie są obsługiwane.
• Bonusy i korzyści: programy obsługują bezpłatną dostawę, punkty do wykorzystania i ceny dla uczestników programu. W reklamach ceny dla uczestników programu wymagają rabatu w wysokości co najmniej 5% lub 5 jednostek waluty poniżej ceny standardowej lub promocyjnej.

Wymagania wstępne

Zanim zaczniesz zarządzać programami lojalnościowymi za pomocą interfejsu Merchant API, upewnij się, że spełniasz te wymagania:

• Musisz mieć aktywne konto Merchant Center (lub autoryzowany dostęp do konta sprzedawcy, jeśli jesteś zewnętrznym dostawcą programu lojalnościowego).
• Włącz dodatek Program lojalnościowy na swoim koncie. Dodatek możesz włączyć, korzystając z jednej z tych opcji:
  • Interfejs Merchant Center: postępuj zgodnie z instrukcjami podanymi w artykule Konfigurowanie programu lojalnościowego w Centrum pomocy Merchant Center.
  • Podrzędny interfejs API programów: włącz program automatycznie zgodnie z opisem w artykule Włączanie programów w podrzędnym interfejsie API programów.

Oto przykładowe żądanie włączenia dodatku do programu lojalnościowego za pomocą podrzędnego interfejsu API programów:

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

Metody

Programami lojalnościowymi możesz zarządzać na te sposoby:

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

Tworzenie programu lojalnościowego

Aby utworzyć nowy program lojalnościowy dla konta, użyj metody loyaltyPrograms.create. Podaj szczegóły, takie jak opisy programów, adres URL rejestracji i poziomy programu z unikalnymi korzyściami i wymaganiami.

Wymagany parametr program_label ustawia unikalny identyfikator programu lojalnościowego. Na przykład podanie etykiety my-rewards powoduje, że zasób name ma wartość accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Oto przykładowa treść wiadomości:

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

Zastąp {ACCOUNT_ID} unikalnym identyfikatorem swojego konta Merchant Center.

Oto przykładowa odpowiedź na udane żądanie:

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

Pobieranie programu lojalnościowego

Aby pobrać szczegóły konkretnego własnego programu lojalnościowego, użyj metody loyaltyPrograms.get.

Uwaga: nawet jeśli dodatek do programu lojalnościowego nie został włączony, ten punkt końcowy nadal odpowiada pasującym programem lojalnościowym bez zwracania błędu.

Oto przykładowa treść wiadomości:

HTTP

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

Zastąp {ACCOUNT_ID} identyfikatorem konta, a {PROGRAM_LABEL} unikalną etykietą programu lojalnościowego (np. my-rewards).

Oto przykładowa odpowiedź na udane żądanie:

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

Wyświetlanie listy programów lojalnościowych

Aby wyświetlić listę wszystkich programów lojalnościowych powiązanych z Twoim kontem, użyj metody loyaltyPrograms.list.

Uwaga: ta metoda wyświetla tylko programy lojalnościowe należące bezpośrednio do określonego konta, a nie programy powiązane z subkontami. Nawet jeśli dodatek programu lojalnościowego jest wyłączony, ten punkt końcowy odpowiada istniejącymi programami bez zwracania błędu.

Oto przykładowa treść wiadomości:

HTTP

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

Oto przykładowa odpowiedź na udane żądanie:

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

Aktualizowanie programu lojalnościowego

Aby zaktualizować istniejący program lojalnościowy, użyj metody loyaltyPrograms.update. Wykonaj częściową aktualizację za pomocą update_mask lub pełną, pomijając maskę.

Ważne: podczas aktualizowania programu lojalnościowego nie można aktualizować pól powtarzanych (takich jak programDescriptions i tiers) w miejscu. Każde pole powtarzane uwzględnione w aktualizacji zastępuje całą istniejącą listę. Aby uniknąć niezamierzonej utraty danych, przed aktualizacją pól powtarzanych wyślij najpierw żądanie get, aby pobrać bieżące wartości.

Częściowa aktualizacja z maską aktualizacji

update_mask pozwala określić pola, które mają zostać zaktualizowane. Modyfikowane są tylko pola wymienione w masce, a pola niewymienione pozostają niezmienione. Każde pole pominięte w masce aktualizacji jest ignorowane, nawet jeśli zostało podane w treści żądania.

Poniższe przykładowe żądanie aktualizuje tylko parametry programDescriptions i 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"
}

W tym przykładzie usługa ignoruje signupUrl, ponieważ nie jest on uwzględniony w update_mask. Pole programDescriptions całkowicie zastępuje wszystkie wcześniej skonfigurowane opisy.

Oto przykładowa odpowiedź na udane żądanie:

{
  "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
  }
}

Pełne zastąpienie bez maski aktualizacji

Jeśli pominiesz parametr update_mask, żądanie spowoduje całkowite zastąpienie konfiguracji programu lojalnościowego.

Oto przykładowa treść wiadomości:

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

Oto przykładowa odpowiedź na udane żądanie:

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

Usuwanie programu lojalnościowego

Aby usunąć program lojalnościowy z konta, użyj metody loyaltyPrograms.delete.

Oto przykładowa treść wiadomości:

HTTP

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

Jeśli operacja się uda, treść odpowiedzi będzie pusta.

Dalsze kroki

• Aby powiązać poszczególnych kupujących z poziomami programu lojalnościowego na potrzeby bezpłatnej personalizacji w wyszukiwarce Google, zapoznaj się z przewodnikiem po usłudze kierowania na listę klientów w programie lojalnościowym.
• Aby dowiedzieć się, jak włączyć lub wyłączyć programy zakupowe na koncie, zapoznaj się z przewodnikiem po podrzędnym interfejsie API programów.
• Szczegółowe informacje o konfiguracji firmy, zasadach redakcyjnych i raportowaniu znajdziesz w artykule Informacje o programie lojalnościowym sprzedawcy w Centrum pomocy Merchant Center.
• Aby dowiedzieć się więcej o metodach interfejsu API i definicjach zasobów, zapoznaj się z dokumentacją Merchant API.