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

عرض مزايا متجرك على 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 (أو إذن بالوصول إلى حساب التاجر إذا كنت مقدّم خدمات ولاء تابعًا لجهة خارجية).
  • فعِّل إضافة برنامج الولاء لحسابك. يمكنك تفعيل الإضافة باستخدام أحد الخيارَين التاليَين:

في ما يلي نموذج طلب لتفعيل إضافة "برنامج الولاء" باستخدام واجهة برمجة التطبيقات الفرعية الخاصة بـ "البرامج":

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}

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

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

التالي
Manage customer loyalty data