ملاحظة مهمة: تم إيقاف Content API for Shopping نهائيًا في 18 أغسطس 2026.

اعتبارًا من 1 سبتمبر 2026، ستظهر أخطاء تدريجية في طلبات Content API for Shopping. يُرجى مراجعة دليل إيقاف Content API نهائيًا.

إذا كنت بحاجة إلى وقت إضافي للانتقال إلى Merchant API، يمكنك تقديم طلب للحصول على إذن وصول مطوّل إلى Content API for Shopping.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

اعرض مزايا متجرك على 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. يؤدي كل تعديل ناجح إلى إعادة البرنامج إلى قائمة انتظار المراجعة، حتى إذا لم يغيّر التعديل أي شيء رئيسي. تخفي Google البرنامج عن المتسوّقين أثناء عملية المراجعة. قد تستغرق المراجعة مدة تصل إلى 48 ساعة.
المناطق المتاحة: تتوفّر برامج الولاء الخاصة بالتجّار في البلدان المتاحة، بما في ذلك أستراليا وألمانيا وإسبانيا وإيطاليا والبرازيل والمكسيك والمملكة المتحدة والهند والولايات المتحدة واليابان وفرنسا وكندا وكوريا الجنوبية وهولندا.
المناطق النشطة: يجب أن تكون السمة regionCodes لبرنامج الولاء مجموعة فرعية من السمة activeRegionCodes لـ accounts/{ACCOUNT_ID}/programs/loyalty. وإلا، ستتعذّر طلبات الإنشاء والتعديل والحذف مع ظهور الخطأ LOYALTY_PROGRAM_DISABLED. تفعّل Google بلدًا متوافقًا عندما تكون إضافة برنامج الولاء مفعّلة ويستوفي الحساب متطلبات الأهلية في ذلك البلد. على سبيل المثال، يكون الحساب مؤهلاً إذا كان برنامج "البيانات المجانية" مفعّلاً وكان مصدر بيانات المنتجات الأساسي يستهدف البلد الخاص بوجهة FREE_LISTINGS. لمعرفة سبب عدم نشاط بلد معيّن، يُرجى الاطّلاع على التحقّق من المناطق النشطة.
متطلبات المستويات: يمكن أن تكون المستويات مجانية أو تتطلب دفع رسوم اشتراك أو بلوغ حدّ إنفاق معيّن أو استخدام بطاقة ائتمان تحمل العلامة التجارية للتاجر. لا يمكن للمستويات التي تستند إلى المهن (مثل الطلاب أو العسكريين) الاستفادة من المزايا.
المزايا والفوائد: تتيح البرامج خدمة الشحن المجاني والنقاط التي يمكن تحصيل قيمتها والأسعار المخصّصة للأعضاء. في إعلانات Google، يتطلّب السعر المخصّص للأعضاء خصمًا لا يقل عن ‎5% أو 5 وحدات عملة أقل من السعر العادي أو السعر المخفَّض.

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

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

يجب أن يكون لديك حساب نشط على Merchant Center (أو إذن وصول مصرَّح به إلى حساب التاجر إذا كنت مقدّم خدمة ولاء تابعًا لجهة خارجية).
فعِّل إضافة برنامج الولاء لحسابك. يمكنك تفعيل الإضافة باستخدام أي من الخيارات التالية:
- واجهة مستخدم Merchant Center: اتّبِع التعليمات الواردة في مقالة إعداد برنامج ولاء في مساعدة Merchant Center.
- واجهة برمجة التطبيقات الفرعية Programs sub-API: يمكنك تفعيل البرنامج آليًا كما هو موضّح في مقالة تفعيل البرامج في واجهة برمجة التطبيقات الفرعية Programs sub-API. تتطلّب طريقة accounts.programs.enable إذن وصول المشرف.
يجب أن تكون البلدان التي تريد تقديم برنامج الولاء فيها نشطة في حسابك. لمعرفة البلدان النشطة، يُرجى الاطّلاع على التحقّق من المناطق النشطة.

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

التحقّق من المناطق النشطة

بعد تفعيل إضافة "برنامج الولاء"، يمكنك استدعاء طريقة accounts.programs.get لـ accounts/{ACCOUNT_ID}/programs/loyalty. توضّح الاستجابة البلدان التي يمكنك فيها استخدام برامج الولاء وسبب عدم تفعيل البلدان الأخرى المتوافقة.

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

HTTP

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

cURL

curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed

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

في ما يلي نموذج ردّ لحساب فعّل الإضافة وهو مؤهَّل في الولايات المتحدة فقط:

{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}

في هذه الاستجابة، راجِع الحقول التالية:

‫activeRegionCodes: البلدان التي يمكنك استخدامها في regionCodes لبرنامج الولاء في النموذج السابق، يكون US فقط نشطًا.
‫unmetRequirements: سبب عدم نشاط البلدان الأخرى المتوافقة بالنسبة إلى برامج الولاء، هذا هو متطلب IS_ELIGIBLE_FOR_LOYALTY.
- ‫affectedRegionCodes: البلدان المتاحة التي لا يكون فيها الحساب مؤهلاً
- ‫documentationUri: رابط يؤدي إلى متطلبات الأهلية

في النموذج السابق، لا يمكنك استخدام البلدان في affectedRegionCodes بعد. إذا كان regionCodes الخاص ببرنامج الولاء يتضمّن أحد هذه الحقول، ستتعذّر طلبات الإنشاء والتعديل والحذف وسيظهر الخطأ LOYALTY_PROGRAM_DISABLED. لتفعيل بلد، اتّبِع الخطوات التالية:

اجعل الحساب مؤهَّلاً في ذلك البلد. على سبيل المثال، يمكنك تفعيل برنامج "البيانات المجانية" وضبط مصدر بيانات المنتج الأساسي من أجل استهداف البلد للوجهة FREE_LISTINGS. للاطّلاع على جميع طرق التأهّل، يُرجى مراجعة متطلبات الأهلية.
يُرجى الاتصال بالرقم ‎accounts.programs.get مرة أخرى والتأكّد من أنّ البلد هو activeRegionCodes.

يمكن أن يتضمّن affectedRegionCodes بلدانًا لا تبيع فيها منتجاتك. لست بحاجة إلى اتخاذ أي إجراء في هذه البلدان. ولا تؤثّر في البلدان المشمولة في activeRegionCodes.

الطُرق

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

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

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

لإنشاء برنامج ولاء جديد لحساب معيّن، استخدِم طريقة 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}

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

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

لربط المتسوّقين الفرديين بمستويات برنامج الولاء من أجل التخصيص المجاني على "بحث Google"، يُرجى الاطّلاع على دليل خدمة "مطابقة العملاء" في برنامج الولاء.
لتفعيل برامج التسوّق أو إيقافها في حسابك، يُرجى الاطّلاع على دليل واجهة Programs sub-API.
للاطّلاع على تفاصيل إعداد المؤسسة وسياسات الصياغة وإعداد التقارير، يُرجى مراجعة مقالة لمحة عن برنامج الولاء الخاص بالتجار في مركز مساعدة Merchant Center.
لاستكشاف طرق واجهة برمجة التطبيقات وتعريفات الموارد، يُرجى الاطّلاع على مرجع Merchant API.

Overview

Manage customer loyalty data

نظرة عامة على برامج الولاء تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

HTTP

cURL

التحقّق من المناطق النشطة

HTTP

cURL

الطُرق

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

HTTP

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

HTTP

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

HTTP

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

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

HTTP

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

HTTP

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

HTTP

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

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