Ringkasan program loyalitas

Tampilkan manfaat toko Anda di Google menggunakan program loyalitas. Anda dapat mengirimkan berbagai manfaat, seperti pengiriman gratis, poin yang dapat ditukarkan, dan harga khusus anggota. Manfaat program loyalitas Anda dapat muncul di listingan gratis, iklan Shopping, dan iklan inventaris lokal di seluruh platform Google, termasuk Google Penelusuran, tab Shopping, dan Google Wallet.

Dengan Merchant API, penjual dan penyedia program loyalitas pihak ketiga yang bertindak atas nama penjual dapat mengonfigurasi dan mengelola program loyalitas secara terprogram menggunakan LoyaltyProgramService. Layanan ini memungkinkan Anda membuat, mengambil, mencantumkan, memperbarui, dan menghapus program loyalitas.

Penting: Layanan ini hanya tersedia untuk penjual tertentu. Hubungi tim dukungan untuk menyatakan minat berpartisipasi dengan mengirimkan permintaan untuk dimasukkan ke daftar yang diizinkan di Formulir Dukungan Shopping API di bagian Apa masalah/pertanyaannya? > Permintaan daftar yang diizinkan > Lainnya.

Untuk mengetahui informasi selengkapnya tentang persyaratan bisnis dan pedoman kebijakan, lihat artikel Tentang program loyalitas penjual di Pusat Bantuan Merchant Center.

Konsep utama

Perhatikan konsep dan batasan berikut saat menggunakan program loyalitas:

• ID tingkat akun: Merchant API mengidentifikasi program loyalitas berdasarkan ID akun Merchant Center pemilik.
• Batas program tunggal: Merchant API hanya mendukung satu program loyalitas per akun penjual.
• Kepemilikan akun langsung: Program loyalitas harus dikonfigurasi langsung di akun penjual target (accounts/{ACCOUNT_ID}). Layanan ini tidak mendukung pengelolaan program loyalitas di tingkat akun tingkat lanjut untuk sub-akun. Penyedia program loyalitas pihak ketiga dengan akses resmi ke akun penjual dapat mengelola program atas nama penjual.
• Peninjauan editorial: Setelah membuat atau memperbarui program loyalitas, program tersebut akan ditinjau. Kolom review_result.review_status menunjukkan apakah program UNDER_REVIEW, APPROVED, atau REJECTED.
• Wilayah yang didukung: Program loyalitas penjual tersedia di negara-negara yang didukung, termasuk Australia, Brasil, Kanada, Prancis, Jerman, India, Italia, Meksiko, Belanda, Korea Selatan, Spanyol, Inggris Raya, dan Amerika Serikat.
• Persyaratan tingkat: Tingkat dapat tidak memerlukan biaya untuk bergabung, memerlukan biaya keanggotaan, memerlukan nilai minimum pembelanjaan, atau memerlukan kartu kredit bermerek penjual. Tingkatan berbasis pekerjaan (seperti tingkatan pelajar atau militer) tidak didukung.
• Keuntungan dan manfaat: Program mendukung pengiriman gratis, poin yang dapat ditukarkan, dan harga khusus anggota. Dalam iklan, harga khusus anggota memerlukan diskon minimal 5% atau 5 unit mata uang di bawah harga reguler atau harga promo.

Prasyarat

Sebelum mengelola program loyalitas dengan Merchant API, pastikan Anda memenuhi persyaratan berikut:

• Anda harus memiliki akun Merchant Center yang aktif (atau akses yang sah ke akun penjual jika Anda adalah penyedia program loyalitas pihak ketiga).
• Aktifkan add-on program Loyalitas untuk akun Anda. Anda dapat mengaktifkan add-on menggunakan salah satu opsi berikut:
  • UI Merchant Center: Ikuti petunjuk di Menyiapkan program loyalitas di Bantuan Merchant Center.
  • Sub-API program: Aktifkan program secara terprogram seperti yang dijelaskan dalam Mengaktifkan program di sub-API Program.

Berikut adalah contoh permintaan untuk mengaktifkan add-on Program loyalitas menggunakan sub-API Program:

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

Metode

Kelola program loyalitas menggunakan metode berikut:

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

Membuat program loyalitas

Untuk membuat program loyalitas baru untuk akun, gunakan metode loyaltyPrograms.create. Tentukan detail seperti deskripsi program, URL pendaftaran, dan tingkat program dengan manfaat dan persyaratan uniknya.

program_label yang diperlukan menetapkan ID unik untuk program loyalitas. Misalnya, memberikan label my-rewards akan menghasilkan resource name accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

Berikut contoh permintaannya:

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

Ganti {ACCOUNT_ID} dengan ID unik akun Merchant Center Anda.

Berikut adalah contoh respons permintaan yang berhasil:

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

Mengambil program loyalitas

Untuk mengambil detail program loyalitas milik sendiri tertentu, gunakan metode loyaltyPrograms.get.

Catatan: Meskipun add-on Program loyalitas belum diaktifkan, endpoint ini tetap merespons dengan program loyalitas yang cocok tanpa menampilkan error.

Berikut contoh permintaannya:

HTTP

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

Ganti {ACCOUNT_ID} dengan ID akun Anda dan {PROGRAM_LABEL} dengan label unik program loyalitas (misalnya, my-rewards).

Berikut adalah contoh respons permintaan yang berhasil:

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

Mencantumkan program loyalitas

Untuk mencantumkan semua program loyalitas milik sendiri yang terkait dengan akun Anda, gunakan metode loyaltyPrograms.list.

Catatan: Metode ini hanya mencantumkan program loyalitas yang dimiliki langsung oleh akun yang ditentukan, bukan program yang terkait dengan sub-akun. Meskipun add-on program Loyalitas dinonaktifkan, endpoint ini merespons dengan program yang ada tanpa menampilkan error.

Berikut contoh permintaannya:

HTTP

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

Berikut adalah contoh respons permintaan yang berhasil:

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

Memperbarui program loyalitas

Untuk memperbarui program loyalitas yang ada, gunakan metode loyaltyPrograms.update. Lakukan update sebagian menggunakan update_mask, atau lakukan penggantian penuh dengan menghilangkan mask.

Penting: Saat memperbarui program loyalitas, kolom berulang (seperti programDescriptions dan tiers) tidak dapat diperbarui di tempat. Setiap kolom berulang yang disertakan dalam pembaruan akan menggantikan seluruh daftar yang ada. Untuk menghindari kehilangan data yang tidak disengaja, kirim permintaan get terlebih dahulu untuk mengambil nilai saat ini sebelum memperbarui kolom berulang.

Pembaruan parsial dengan mask pembaruan

update_mask memungkinkan Anda menentukan kolom yang tepat untuk diperbarui. Hanya kolom yang tercantum dalam mask yang diubah, sedangkan kolom yang tidak tercantum tetap tidak berubah. Kolom apa pun yang dihilangkan dari mask update akan diabaikan, meskipun diberikan di isi permintaan.

Contoh permintaan berikut hanya memperbarui programDescriptions dan 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"
}

Dalam contoh ini, layanan mengabaikan signupUrl karena tidak disertakan dalam update_mask. Kolom programDescriptions sepenuhnya menggantikan deskripsi yang dikonfigurasi sebelumnya.

Berikut adalah contoh respons dari permintaan yang berhasil:

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

Penggantian penuh tanpa mask pembaruan

Jika Anda menghilangkan parameter update_mask, permintaan akan melakukan penggantian konfigurasi program loyalitas secara menyeluruh.

Berikut contoh permintaannya:

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

Berikut adalah contoh respons dari permintaan yang berhasil:

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

Menghapus program loyalitas

Untuk menghapus program loyalitas dari akun Anda, gunakan metode loyaltyPrograms.delete.

Berikut contoh permintaannya:

HTTP

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

Jika berhasil, isi respons akan kosong.

Langkah berikutnya

• Untuk mengaitkan masing-masing pembeli dengan tingkat program loyalitas Anda untuk personalisasi organik di Google Penelusuran, lihat panduan Layanan Customer Match Loyalitas.
• Untuk mengaktifkan atau menonaktifkan program Shopping untuk akun Anda, lihat panduan sub-API Program.
• Untuk mengetahui detail penyiapan bisnis, kebijakan editorial, dan pelaporan, lihat Tentang program loyalitas penjual di Bantuan Merchant Center.
• Untuk mempelajari metode API dan definisi resource, lihat Referensi Merchant API.