Merchant API v1beta, 28 Şubat 2026'da kullanımdan kaldırıldı ve kapatıldı. En yeni kararlı sürüme geçiş adımları için v1beta'dan v1'e taşıma başlıklı makaleyi inceleyin.

Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Bağlılık Müşteri Eşleştirme Hizmetine Genel Bakış

Bu kılavuzda, Merchant API'de Loyalty Customer Match Service'in nasıl kullanılacağı açıklanmaktadır. Bu hizmet, satıcıların Google Arama'da organik kişiselleştirme için kullanıcı tanımlayıcıları ve katman bilgileri gibi müşteri bağlılığı verilerini etkin bir Google Ads hesabı gerektirmeden yönetmelerini sağlar.

Genel Bakış

Bağlılık verilerini yüklemek için Bağlılık Müşteri Eşleştirme Hizmeti'ni kullanın. Bu veriler daha sonra Google Arama'da üyelere özel fiyatlandırma gösterme gibi organik bağlılık kişiselleştirme özellikleri sağlamak için kullanılır. Müşterilerinizi bağlılık programı düzeyleriyle ilişkilendirmek için ManageLoyaltyCustomerMatch özel yöntemini kullanırsınız. Bu sayede, kullanıcı kimliklerine göre bağlılık durumlarını ekleyebilir, güncelleyebilir veya kaldırabilirsiniz.

Temel kavramlar

Birleştirilmiş arayüz: Müşteri bağlılığı katmanı ayrıntılarını eklemek, güncellemek veya kaldırmak için kullanılan benzersiz bir uç nokta.
Gizlilik öncelikli tasarım: API, kullanıcı gizliliğini korumak ve yetkisiz hesap incelemelerini önlemek için GET veya LIST işlemlerini desteklemez. Bu sayede verilerin, alınmadan veya denetlenmeden yönetilmesi sağlanır.
Esnek tanımlama: Kullanıcıları e-posta adresi, açık adres veya telefon numarası gibi en az bir geçerli tanımlayıcı kullanarak eşleştirin.
İzne dayalı işleme: Hizmet, müşteri verilerini yalnızca son kullanıcı Google'a gerekli izni verdiğinde saklar ve kullanır. Hizmet, hesap varlığı yoklamasını veya izin durumunu korumak ve önlemek için eşleşme yapılmazsa ya da izin verilmezse sessiz bir başarı döndürür.

Ön koşullar

Bağlılık programı Müşteri Eşleştirme Hizmeti'ni kullanmak için aşağıdaki koşulları karşılamanız gerekir:

Hesap kurulumu: Etkin bir Merchant Center hesabınız olduğundan emin olun. Loyalty Customer Match Service'i kullanmak için Google Ads hesabı oluşturmanız gerekmez.
Bağlılık programı yapılandırması: Merchant Center hesabınızda bağlılık programını etkinleştirin ve bağlılık katmanlarını tanımladığınızdan emin olun.
Katman sırası farkındalığı: Bağlılık katmanlarınızın Merchant Center kullanıcı arayüzünde tanımlandığı sıranın farkında olun. API, enum eşlemesi için bu sırayı kullanır.

Yöntem: `ManageLoyaltyCustomerMatch`

ManageLoyaltyCustomerMatch yöntemi, müşteri bağlılığı ilişkilendirmelerini yönetmek için merkezi arayüz olarak kullanılır. Sağlanan girişe göre hizmet, müşterinin bağlılık programı katmanı durumunu ekleme, güncelleme veya kaldırma konusunda otomatik olarak karar verir. İşlem idempotent'tir: Tekrarlanan aynı istekler, tek bir istekle aynı etkiye sahiptir.

Aşağıdaki istekte, API aracılığıyla müşteri bağlılığı ilişkilendirmelerinin nasıl yönetileceği gösterilmektedir:

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

Bu istekte aşağıdaki zorunlu yol parametreleri tanımlanır:

api_version: v1 gibi API sürümü.
account_id: Merchant Center hesabı kimliği.

İstek metnine bir loyaltyCustomer nesnesi ekleyin.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer alanları

userIdentifier: Müşteriyi eşleştirmek için kullanılan tanımlayıcılar grubu. userIdentifier içinde en az bir alan sağlanmalı ve geçerli olmalıdır.
loyaltyTier: Müşteriyle ilişkilendirilecek bağlılık kademesi. Merchant Center kurulumundaki katman sırasıyla eşleşir. Ayrıntılar için loyaltyTier eşlemeyi anlama başlıklı makaleyi inceleyin. Mevcut bir ilişkilendirmeyi kaldırmak için NON_MEMBER değerini kullanın.
pointBalance: Müşterinin mevcut puan bakiyesi.

userIdentifier alanları

Aşağıdaki alanlardan en az biri sağlanmalıdır:

emailAddress: Müşterinin e-posta adresi.
address: Müşterinin fiziksel adresi. PostalCode gereklidir.
phoneNumber: Müşterinin telefon numarası. E.164 biçimi önerilir.

`loyaltyTier` eşlemeyi anlama

API, özel adları kullanmaz. loyaltyTier enum değerleri (TIER1 ile TIER7 arası) semantik etiketlerdir. Merchant Center kullanıcı arayüzünüzde atadığınız özel adları (ör. "Altın Ödüller") veya özel etiketleri (ör. "gold_tier") kullanmazlar. Bunun yerine, Merchant Center'daki bağlılık programı ayarlarında katmanlarınızı tanımladığınız sırayla eşlenirler:

TIER1: Merchant Center bağlılık programı yapılandırmanızda listelenen ilk katmana karşılık gelir.
TIER2: Merchant Center bağlılık programı yapılandırmanızda listelenen ikinci katmana karşılık gelir.
TIER3 - TIER7: Merchant Center bağlılık programı yapılandırmanızda listelenen üçüncü ila yedinci katmanlara karşılık gelir.

Örnek:

Merchant Center bağlılık programınızda katmanlar şu sırayla tanımlanmışsa:

Katman adı: "Gümüş Statü", Katman etiketi: �"silver"
Katman adı: "Altın Üye", Katman etiketi: "gold"
Katman adı: "Platinum Elite", Katman etiketi: "platinum"

Ardından, accounts.loyaltyCustomers.manage API çağrıları bölümünde:

Bir müşteriyi "Gümüş Durumu"'na atamak için loyaltyTier: TIER1 kullanmanız gerekir.
Bir müşteriyi "Altın Üye" olarak atamak için loyaltyTier: TIER2 kullanmanız gerekir.
Bir müşteriyi "Platinum Elite"'e atamak için loyaltyTier: TIER3 kullanmanız gerekir.

LoyaltyTier enum değerleri

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (Müşterinin bağlılık ilişkisinin kaldırıldığını belirtmek için kullanılır)

ManageLoyaltyCustomerMatch yanıt gövdesini anlama

ManageLoyaltyCustomerMatch yöntemi bir ManageLoyaltyCustomerMatchResponse nesnesi döndürür:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Olası yanıtlarla ilgili önemli noktalar:

Başarılı upsert (veriler depolandı): Bir müşterinin bağlılık programı katmanı ilişkilendirmesini başarıyla depolamak veya güncellemek için aşağıdaki koşulları karşılayın:
- bir Google kullanıcısını sağlanan userIdentifier ile eşleştirirseniz
- İsteklerdeki loyaltyTier değerini NON_MEMBER dışında geçerli bir değere ayarladıysanız
- Eşleşen kullanıcının, bağlılık programı verilerinin kullanımına izin vermiş olması

Yanıt, isteğinizdeki loyaltyCustomer nesnesini içerir. Bu, verilerin başarıyla işlendiğini ve depolandığını gösterir:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

Başarılı silme: Müşterinin bu satıcıyla mevcut tüm bağlılık ilişkilerini başarıyla kaldırmak için aşağıdaki koşulların karşılanması gerekir:
- sağlanan ile userIdentifier bir Google kullanıcısını eşleştirirseniz
- İstekteki loyaltyTier değerini NON_MEMBER olarak ayarladıysanız

Yanıt boş bir JSON nesnesi olur:

{}

Eşleşme yok / izin yok (sessiz başarı): Sağlanan userIdentifier, bir Google Hesabı ile eşleşmiyorsa veya eşleşen kullanıcı, bağlılık programı verilerinin kullanımına izin vermediyse API, boş bir JSON nesnesiyle HTTP 200 OK durumunu döndürür: {}. Bu durum, hem ekleme/güncelleme hem de kaldırma denemelerinde görülür.

Örnekler

TIER1, satıcının tanımlanan ilk katmanına ("Temel") ve TIER2 ise ikinci katmanına ("Premium") karşılık gelir.

Bir müşteriyi TIER2'ye eklemek veya durumunu e-posta adresini kullanarak güncellemek için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Bir kullanıcı başarıyla eşleştirilip izin verdiğinde API aşağıdaki yanıtı döndürür:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Eşleşme olmadığında veya kullanıcı izin vermediğinde API aşağıdaki yanıtı döndürür:

{}

Bir müşterinin bağlılık programı üyeliğini telefon numarası kullanarak kaldırmak için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Kayıt olup olmadığına bakılmaksızın API aşağıdaki başarılı yanıtı döndürür:

{}

Birden fazla tanımlayıcı kullanarak müşteri eklemek veya güncellemek için aşağıdaki isteği gönderin:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

Eşleşmeye ve izne bağlı olarak yanıt, ilk örneğe benzer.

Hata işleme

API, standart HTTP kodlarını kullanır. Sık karşılaşılan hata dizeleri şunlardır:

HTTP kodu	Hata dizesi	Açıklama
400	INVALID_ARGUMENT	user_identifier veya loyalty_tier eksik ya da tanımlayıcı boş.
401	UNAUTHENTICATED	Geçersiz veya eksik kimlik bilgileri.
403	PERMISSION_DENIED	Kimliği doğrulanmış kullanıcının, belirtilen Merchant Center hesabına erişimi yok.
404	NOT_FOUND	Belirtilen bağlılık katmanı etiketi, yapılandırmanızda mevcut değil.
412	FAILED_PRECONDITION	Hesabınızda bağlılık programı yapılandırmadınız.
429	RESOURCE_EXHAUSTED	Kota sınırına ulaşıldı.