Omówienie programów lojalnościowych

Prezentuj korzyści z udziału w programie lojalnościowym w Google. 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ę pojawiać w bezpłatnych informacjach, reklamach produktowych i reklamach lokalnego asortymentu produktów w usługach Google, takich jak wyszukiwarka Google, karta Zakupy czy Portfel Google.

Za pomocą Merchant API sprzedawcy i zewnętrzni dostawcy programów lojalnościowych działający w imieniu sprzedawców mogą konfigurować programy lojalnościowe i zarządzać nimi w sposób zautomatyzowany 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. Aby wyrazić zainteresowanie udziałem, skontaktuj się z zespołem pomocy i prześlij prośbę o umieszczenie na liście dozwolonych w formularzu pomocy dotyczącej interfejsu Shopping API w sekcji Jaki jest problem lub pytanie? > Prośba o dodanie do listy dozwolonych > Inne.

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.

Kluczowych pojęć

Podczas korzystania z programów lojalnościowych pamiętaj o tych kwestiach i ograniczeniach:

• Identyfikator na poziomie konta: interfejs Merchant API identyfikuje programy lojalnościowe za pomocą identyfikatora konta Merchant Center, do którego należą.
• Ograniczenie dotyczące jednego programu: interfejs Merchant API obsługuje tylko 1 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 usług lojalnościowych z autoryzowanym dostępem do konta sprzedawcy mogą zarządzać programem w jego imieniu.
• Sprawdzanie redakcyjne: 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: dołączenie do poziomów może być bezpłatne, wymagać opłaty za członkostwo, osiągnięcia progu wydatków lub posiadania karty kredytowej marki sprzedawcy. Poziomy oparte na zawodzie (np. student lub żołnierz) nie są obsługiwane.
• Korzyści: programy obsługują bezpłatną dostawę, punkty do wykorzystania i ceny dla uczestników. W reklamach ceny dla uczestników programu wymagają zniżki wynoszącej 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, sprawdź, czy spełniasz te wymagania:

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

Oto przykładowe żądanie włączenia dodatku do programu lojalnościowego za pomocą interfejsu API podrzędnego 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

Metody

Zarządzaj programami lojalnościowymi, korzystając z tych metod:

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

Tworzenie programu lojalnościowego

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

Wymagany element program_label ustawia unikalny identyfikator programu lojalnościowego. Na przykład podanie etykiety my-rewards spowoduje utworzenie zasobuname o wartości accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Przykładowe żądanie:

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 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 programu lojalnościowego, którego jesteś właścicielem, użyj metody loyaltyPrograms.get.

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

Przykładowe żądanie:

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, których jesteś właścicielem i które są powiązane z Twoim kontem, użyj metody loyaltyPrograms.list.

Uwaga: ta metoda wyświetla tylko programy lojalnościowe, których właścicielem jest bezpośrednio określone konto, 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.

Przykładowe żądanie:

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ą zamianę, pomijając maskę.

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

.

Częściowa aktualizacja z maską aktualizacji

update_mask umożliwia określenie dokładnych pól do zaktualizowania. Zmodyfikowane zostaną tylko pola wymienione w masce, a pola niewymienione pozostaną bez zmian. Wszystkie pola pominięte w masce aktualizacji są ignorowane, nawet jeśli zostały 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 parametr signupUrl, ponieważ nie jest on uwzględniony w parametrze 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łna wymiana bez maski aktualizacji

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

Przykładowe żądanie:

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.

Przykładowe żądanie:

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 w celu organicznej personalizacji w wyszukiwarce Google, zapoznaj się z przewodnikiem po usłudze kierowania na listę klientów w programie lojalnościowym.
• Aby włączyć lub wyłączyć programy zakupowe na koncie, zapoznaj się z przewodnikiem po interfejsie API podrzędnym Programs.
• 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 poznać metody interfejsu API i definicje zasobów, zapoznaj się z dokumentacją Merchant API.