חשוב: אנחנו נוציא משימוש את Content API for Shopping ב-18 באוגוסט 2026.

אם אתם צריכים עוד זמן כדי לעבור ל-Merchant API, אתם יכולים להגיש בקשה להארכת הגישה ל-Content API for Shopping.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

סקירה כללית של מועדוני לקוחות

מציגים את ההטבות של החנות ב-Google באמצעות מועדוני לקוחות. אתם יכולים להגדיר שם סוגים שונים של הטבות לחברי מועדון, כמו משלוח חינם, צבירת נקודות למימוש בקנייה ומחירים מיוחדים. ההטבות של מועדון הלקוחות יכולות להופיע בכרטיסי מוצר חינמיים, במודעות שופינג ובמודעות מלאי של חנויות מקומיות בפלטפורמות השונות של Google, כולל חיפוש Google, כרטיסיית שופינג ו-Google Wallet.

באמצעות 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 (או גישה מורשית לחשבון של המוכר אם אתם ספק מועדון לקוחות של צד שלישי).
מפעילים את התוסף של מועדון הלקוחות Loyalty בחשבון. אפשר להפעיל את התוסף באחת מהדרכים הבאות:
- ממשק המשתמש של Merchant Center: פועלים לפי ההוראות במאמר הגדרת מועדון לקוחות במרכז העזרה של Merchant Center.
- ‫Programs sub-API: מפעילים את התוכנית באופן פרוגרמטי כמו שמתואר במאמר הפעלת תוכניות ב-Programs sub-API.

זוהי בקשה לדוגמה להפעלת התוסף של מועדון הלקוחות באמצעות Programs sub-API:

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

Methods

אפשר לנהל את מועדוני הלקוחות בשיטות הבאות:

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, תוכלו לעיין במדריך לשירות התאמת לקוחות למועדון.
כדי להפעיל או להשבית תוכניות שופינג בחשבון, אפשר לעיין במדריך ל-API המשני של תוכניות.
פרטים על הגדרת העסק, מדיניות עריכה ודיווח זמינים במאמר מידע על מועדון לקוחות של מוכר במרכז העזרה של Merchant Center.
כדי לעיין בשיטות API ובהגדרות של משאבים, אפשר להיעזר במאמרי העזרה של ה-API בנושא Merchant API.

Manage customer loyalty data

סקירה כללית של מועדוני לקוחות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מושגים מרכזיים

דרישות מוקדמות

HTTP

cURL

Methods

יצירת מועדון לקוחות

HTTP

אחזור של מועדון לקוחות

HTTP

רשימת מועדוני לקוחות

HTTP

עדכון מועדון לקוחות

עדכון חלקי באמצעות מסכת עדכון

HTTP

החלפה מלאה ללא מסכת עדכון

HTTP

מחיקת מועדון לקוחות

HTTP

השלבים הבאים

סקירה כללית של מועדוני לקוחות