نظرة عامة على برامج الولاء

اعرض مزايا متجرك على Google باستخدام برامج الولاء. يمكنك تقديم مجموعة من المزايا، مثل الشحن المجاني والنقاط التي يمكن تحصيل قيمتها والأسعار الحصرية للأعضاء. يمكن أن تظهر مزايا برنامج الولاء في البيانات المجانية و"إعلانات Shopping" و"الإعلانات للمنتجات المتوفرة في المتجر" على مساحات العرض في Google، بما في ذلك "بحث Google" وعلامة التبويب "التسوّق" و"محفظة Google".

باستخدام Merchant API، يمكن للتجّار ومقدّمي برامج الولاء الخارجيين الذين يتصرّفون نيابةً عن التجّار إعداد برامج الولاء وصيانتها آليًا باستخدام LoyaltyProgramService. تتيح لك هذه الخدمة إنشاء برامج الولاء واستردادها وإدراجها وتعديلها وحذفها.

لمزيد من المعلومات حول المتطلبات التجارية وإرشادات السياسة، يُرجى الاطّلاع على المقالة لمحة عن برنامج الولاء الخاص بالتجّار في مركز مساعدة Merchant Center.

المفاهيم الرئيسية

يُرجى مراعاة المفاهيم والقيود التالية عند العمل مع برامج الولاء:

  • المعرّف على مستوى الحساب: تحدّد Merchant API برامج الولاء من خلال رقم تعريف حساب Merchant Center المالك.
  • الحدّ الأقصى لبرنامج واحد: تتيح Merchant API استخدام برنامج ولاء واحد فقط لكل حساب تاجر.
  • ملكية الحساب المباشرة: يجب ضبط برامج الولاء مباشرةً على حساب التاجر المستهدف (accounts/{ACCOUNT_ID}). لا تتيح الخدمة إدارة برامج الولاء على مستوى حساب متقدّم للحسابات الفرعية. يمكن لمقدّمي برامج الولاء الخارجيين الذين لديهم إذن وصول مصرَّح به إلى حساب التاجر إدارة البرنامج نيابةً عن التاجر.
  • المراجعة التحريرية: بعد إنشاء برنامج ولاء أو تعديله، يخضع البرنامج للمراجعة. يشير الحقل review_result.review_status إلى ما إذا كان البرنامج UNDER_REVIEW أو APPROVED أو REJECTED.
  • المناطق المعتمدة: تتوفّر برامج الولاء الخاصة بالتجّار في البلدان المعتمدة، بما في ذلك أستراليا وألمانيا وإسبانيا وإيطاليا والبرازيل والمكسيك والمملكة المتحدة والهند والولايات المتحدة وفرنسا وكندا وكوريا الجنوبية وهولندا.
  • متطلبات المستوى: يمكن أن تكون المستويات مجانية أو تتطلب دفع رسوم اشتراك أو إنفاق حد أدنى من المبلغ أو استخدام بطاقة ائتمان تحمل العلامة التجارية للتاجر. لا يمكن للمستويات التي تستند إلى المهن (مثل الطلاب والعسكريين) الاستفادة من المزايا.
  • المزايا والفوائد: تتيح البرامج خدمة الشحن المجاني والنقاط التي يمكن تحصيل قيمتها والأسعار المخصّصة للأعضاء. في الإعلانات، يتطلّب السعر المخصّص للأعضاء خصمًا لا يقل عن ‎5% أو 5 وحدات عملة أقل من السعر العادي أو السعر المخفَّض.

المتطلبات الأساسية

قبل إدارة برامج الولاء باستخدام Merchant API، تأكَّد من استيفاء المتطلبات التالية:

  • يجب أن يكون لديك حساب نشط على Merchant Center (أو إذن وصول مصرَّح به إلى حساب التاجر إذا كنت مقدّم خدمة ولاء خارجي).
  • فعِّل إضافة برنامج الولاء لحسابك. يمكنك تفعيل الإضافة باستخدام أحد الخيارَين التاليَين:

في ما يلي نموذج طلب لتفعيل إضافة برنامج الولاء باستخدام واجهة 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

الطُرق

يمكنك إدارة برامج الولاء باستخدام الطرق التالية:

إنشاء برنامج ولاء

لإنشاء برنامج ولاء جديد لحساب معيّن، استخدِم طريقة loyaltyPrograms.create. حدِّد تفاصيل مثل أوصاف البرنامج وعنوان URL للاشتراك ومستويات البرنامج مع مزاياها ومتطلباتها الفريدة.

تحدّد السمة المطلوبة program_label المعرّف الفريد لبرنامج الولاء. على سبيل المثال، يؤدي تقديم التصنيف my-rewards إلى الحصول على مورد name من accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards.

إليك نموذج طلب:

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

استبدِل {ACCOUNT_ID} بالمعرّف الفريد لحسابك على Merchant Center.

في ما يلي نموذج ردّ على طلب ناجح:

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

استرداد برنامج ولاء

لاسترداد تفاصيل برنامج ولاء معيّن تملكه، استخدِم طريقة loyaltyPrograms.get.

إليك نموذج طلب:

HTTP

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

استبدِل {ACCOUNT_ID} برقم تعريف حسابك و{PROGRAM_LABEL} بالتصنيف الفريد لبرنامج الولاء (مثلاً، my-rewards).

في ما يلي نموذج ردّ على طلب ناجح:

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

عرض برامج الولاء

لإدراج جميع برامج الولاء المملوكة ذاتيًا والمرتبطة بحسابك، استخدِم طريقة loyaltyPrograms.list.

إليك نموذج طلب:

HTTP

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

في ما يلي نموذج ردّ على طلب ناجح:

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

تعديل برنامج ولاء

لتعديل برنامج ولاء حالي، استخدِم طريقة loyaltyPrograms.update. يمكنك إجراء تعديل جزئي باستخدام update_mask أو إجراء استبدال كامل من خلال حذف القناع.

تعديل جزئي باستخدام قناع التعديل

يتيح لك update_mask تحديد الحقول التي تريد تعديلها بالضبط. يتم تعديل الحقول المدرَجة في القناع فقط، بينما تبقى الحقول غير المدرَجة بدون تغيير. ويتم تجاهل أي حقل تم حذفه من قناع التعديل، حتى إذا تم توفيره في نص الطلب.

يعدّل نموذج الطلب التالي programDescriptions و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"
}

في هذا المثال، تتجاهل الخدمة signupUrl لأنّه غير مضمّن في update_mask. يحلّ حقل programDescriptions محلّ أي أوصاف تم ضبطها سابقًا.

في ما يلي نموذج ردّ على طلب ناجح:

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

استبدال كامل بدون قناع تعديل

عند حذف المَعلمة update_mask، ينفّذ الطلب عملية استبدال كاملة لإعدادات برنامج الولاء.

إليك نموذج طلب:

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

في ما يلي نموذج ردّ على طلب ناجح:

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

حذف برنامج ولاء

لحذف برنامج ولاء من حسابك، استخدِم طريقة loyaltyPrograms.delete.

إليك نموذج طلب:

HTTP

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

إذا كانت الاستجابة ناجحة، سيكون نصها فارغًا.

الخطوات التالية

السابق
Overview
التالي
Manage customer loyalty data