דף זה תורגם על ידי Cloud Translation API.

סקירה כללית של Merchant promotion API

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

כשאתם מוסיפים מבצע למוצרים, הקונים רואים קישור למבצע מיוחד. לדוגמה, '15% הנחה' או 'משלוח חינם'. קישורים למבצעים יכולים להגביר את האטרקטיביות של המוצרים שלכם ולעודד קונים לבצע רכישה. המימוש של מבצעים תמיד יתבצע בתהליך התשלום באתר או בנקודת המכירה.

מידע נוסף זמין במאמר יסודות של קידום מכירות.

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

כדי שקידומי המכירות שלכם יוצגו, עליכם לספק ל-Google מידע ספציפי על העסק ועל המוצרים שלכם. נדרש לכם:

פיד מוצרים פעיל ב-Google Merchant Center.
פיד קידומי מכירות פעיל ב-Google Merchant Center.
חשבון Google Ads לקמפיינים של שופינג.

בנוסף, עליכם להירשם לתוכנית המבצעים בחשבון המוכר. אם אתם לא בטוחים אם כבר נרשמתם, תוכלו לבדוק ב-Merchant Center.

אם אתם לא רשומים, עליכם למלא את טופס הבקשה. הצוות של קידום המכירות יודיע לכם כאשר תוכלו להתחיל בהטמעה.

מידע נוסף זמין במאמר קריטריונים ומדיניות להשתתפות.

יצירת מקור נתונים

אפשר להשתמש ב-method‏ accounts.dataSources.create כדי ליצור מקור לנתוני מבצעים. אם יש מקור נתונים קיים של מבצעים, משתמשים בשיטה accounts.dataSources.list כדי לאחזר את כל מקורות הנתונים. לאחר מכן תוכלו להשתמש בשדה name של מקור הנתונים של המבצע כדי ליצור מבצעים.

הבקשה הבאה מראה איך יוצרים מקור נתונים להוספת מבצעים:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

מחליפים את מה שכתוב בשדות הבאים:

{ACCOUNT_ID}: המזהה הייחודי של החשבון כפי שהוא מופיע בממשק המשתמש של Merchant Center.
{DISPLAY_NAME}: השם המוצג של מקור הנתונים.
{CONTENT_LANGUAGE}: קוד השפה בן שתי האותיות של המוצרים במקור הנתונים, לפי התקן ISO 639-1.
{TARGET_COUNTRY}: קוד האזור במאגר CLDR של מדינת היעד שבה רוצים שהמבצעים יהיו גלויים.

אחרי שהבקשה מופעלת בהצלחה, מופיעה התגובה הבאה שמכילה פרטים על מקור הנתונים החדש של המבצעים:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

קידומי מכירות

אפשר להשתמש ב-method‏ accounts.promotions.insert כדי ליצור או לעדכן מבצע. השיטה accounts.promotions.insert מקבלת כקלט משאב promotions ושם של מקור נתונים. אם הפעולה בוצעה בהצלחה, הפונקציה מחזירה את קידום המכירות החדש או המעודכן.

כדי ליצור מבצע, צריך לציין את השם של מקור הנתונים. בבקשה צריך לציין גם ערכים לשדות הבאים:

contentLanguage
redemptionChannel
promotionId
targetCountry
attributes.offerType
attributes.genericRedemptionCode
attributes.couponValueType
attributes.productApplicability
attributes.promotionEffectiveTimePeriod.endTime
attributes.promotionEffectiveTimePeriod.startTime
attributes.longTitle

Google בודקת ומאשרת את המבצעים לפני שהיא מפרסמת אותם. למידע נוסף, ראו תהליך האישור של המבצעים.

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

הבקשה הבאה ממחישה איך יוצרים קידום מכירות אונליין:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

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

הערכים החוקיים לשדה offerType הם NO_CODE ו-GENERIC_CODE. אם לא מציינים אחד מהערכים האלה, בקשת ה-API תיכשל עם התשובה [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type של HTTP 400. הודעת שגיאה דומה תוחזר אם לא תספקו אף אחד מהשדות החובה.

אם לא מציינים ערך בשדה attributes.genericRedemptionCode, הבקשה תיכשל עם תגובת HTTP 400‏ [genericRedemptionCode] No redemption code provided.

הערכים בשדות promotion.attributes.promotionDisplayTimePeriod.startTime ו-promotion.attributes.promotionDisplayTimePeriod.endTime חייבים להיות בפורמט yyyy-mm-ddThh:mm:ssZ. חשוב להחליף את הערכים בשדות האלה בתאריכים עתידיים.

מידע נוסף זמין במאמר מפרט נתוני המבצעים.

שיטות מומלצות ליצירת מבצעים

רשימה של מאפיינים שקשורים לקידומי מכירות מפורטת במאמר הוספת מאפיינים של נתונים מובְנים.

אחרי שהבקשה ליצירת המבצע מופעלת בהצלחה, יכול להיות שיחלפו כמה דקות עד שאפשר יהיה לאחזר את המבצע באמצעות ה-API או עד שהוא יופיע ב-Merchant Center.

בהמשך מפורטות כמה דוגמאות למבצעים שתוכלו להשתמש בהם כדי להתחיל.

מבצע מקומי שחל על כל המוצרים ועל כל החנויות

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

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

השדה productApplicability הוא חובה. המאפיין הזה מציין אם המבצע תקף לכל המוצרים או רק למוצרים ספציפיים. הערכים הנתמכים הם ALL_PRODUCTS ו-SPECIFIC_PRODUCTS. מידע נוסף זמין במאמר בחירת המוצרים שייכללו במבצע.

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

השדה minimumPurchaseQuantity מאפשר להגדיר את הערך של כמות הרכישה המינימלית שנדרשת למימוש המבצע. מידע נוסף זמין במאמר כמות רכישה מינימלית למימוש המבצע.

באופן דומה, אפשר להשתמש בשדה minimumPurchaseAmount כדי להגדיר את סכום הרכישה המינימלי שנדרש למימוש המבצע. מידע נוסף זמין במאמר סכום רכישה מינימלי.

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

מבצע באינטרנט שחלה על מוצרים נבחרים עם קוד מימוש

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

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

צפייה בקידומי המכירות

כדי להציג קידום מכירות, משתמשים ב-accounts.promotions.get. הבקשה GET היא לקריאה בלבד. צריך לציין את merchantId ואת המזהה של קידום המכירות. ה-method ‏GET מחזיר את משאב הקידומי המכירות התואם.

לדוגמה:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

מחליפים את מה שכתוב בשדות הבאים:

{ACCOUNT_ID}: המזהה הייחודי של חשבון Merchant Center שלכם.
{PROMOTION_ID}: המזהה הייחודי של קידום המכירות שרוצים לאחזר. הפורמט הוא {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

לתשומת ליבכם: ייתכן שיחלפו כמה דקות עד שתוכלו לאחזר קידום מכירות חדש באמצעות ה-API.

הצגת קידום מכירות מקומי

הבקשה לדוגמה הבאה מאחזרת קידום מכירות מקומי שמזהה המבצע שלו הוא in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

לאחר שהבקשה תתבצע בהצלחה, תוצג התגובה הבאה:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

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

השדה promotionUrl בדוגמה הזו מספק את הקישור לאתר של החנות, שבו הקונים יכולים למצוא מידע נוסף על המבצע. אם לא תכללו את השדה promotionUrl, תופיע שגיאה במודעות המלאי של החנות המקומית.

הצגת מבצע אונליין

הבקשה לדוגמה הבאה מאחזרת קידום מכירות אונליין שמזהה הקידום שלו הוא online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

בשדה itemIdInclusion שמוצג בדוגמה הזו מפורטים המוצרים שעומדים בדרישות של המבצע. מידע נוסף זמין במאמר מזהה מוצר לקידום מכירות.

הצגת רשימת המבצעים

אפשר להשתמש ב-method‏ promotions.list כדי להציג את כל המבצעים שנוצרו.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

התשובה מכילה את רשימת כל המבצעים בחשבון. לכל קידום מכירות תוכלו לראות פרטים כמו promotionId,‏ redemptionChannel,‏ dataSource,‏ promotionStatus ועוד.

הצגת הסטטוס של מבצע

כדי לראות את הסטטוס של קידום מכירות, אפשר לעיין במאפיין promotionStatus שמוחזר על ידי השיטה promotions.get או השיטה promotions.list.

השדה promotionStatus יכול לקבל את הערכים הבאים:

IN_REVIEW: המבצע עדיין בבדיקה.
REJECTED: המבצע נדחה.
LIVE: המבצע אושר ופעיל.
STOPPED: המבצע הופסק על ידי החשבון.
EXPIRED: המבצע כבר לא פעיל.
PENDING: המבצע לא הופסק וכל הבדיקות אושרו, אבל תאריך הפעילות שלו הוא בעתיד.
STATE_UNSPECIFIED: מצב קידום מכירות לא ידוע.

במאמר תהליך האישור של מבצעים מוסבר איך מתבצע תהליך האישור של מבצעים שיצרתם.

דוגמה לסטטוס של מבצע

הדוגמאות הבאות מדגימות את ההבדל בין בקשות שהצליחו לבין בקשות שנכשלו.

חסר מיפוי מוצרים

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

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

במאמר פתרון בעיות במבצעים שנפסלו מוסבר איך לפתור בעיות במבצעים שנפסלו ואיך למנוע פסילות בעתיד.

אם קידום המכירות שיצרתם לא יאושר, תקבלו אימייל עם הסיבה לדחייה והוראות לפתרון הבעיות.

המבצע בבדיקה

גוף התשובה הבא מציג קידום מכירות שעדיין נמצא בבדיקה.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

מבצע שאושר ופעיל

גוף התשובה הבא מציג מבצע שגלוי לקונים.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

מידע נוסף זמין במאמר שאלות נפוצות בנושא סטטוס המבצע.

מידע נוסף

פרטים נוספים זמינים במרכז העזרה בנושא מבצעים.
במאמר פתרון בעיות שקשורות ל-Merchant Promotions API מוסבר איך לפתור בעיות נפוצות.
במאמר העברת ניהול קידומי המכירות מוסבר איך עוברים מ-Content API for Shopping.