تم إيقاف الإصدار التجريبي v1 من Merchant API نهائيًا في 28 فبراير 2026. للاطّلاع على خطوات الانتقال إلى أحدث إصدار ثابت، يُرجى قراءة مقالة نقل البيانات من الإصدار التجريبي 1 إلى الإصدار 1.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

نظرة عامة على واجهة برمجة التطبيقات الفرعية للعروض الترويجية

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على أساسيات العروض الترويجية.

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

يجب أن تقدّم إلى Google معلومات محدّدة عن مؤسستك ومنتجاتك قبل عرض عروضك الترويجية. يجب أن يتوفّر لديك ما يلي:

خلاصة منتجات نشطة في Google Merchant Center.
خلاصة عروض ترويجية نشطة في Google Merchant Center.
حساب على إعلانات Google لحملات Shopping.

بالإضافة إلى ذلك، يجب تسجيل حسابك على Merchant Center في برنامج العروض الترويجية. إذا لم تكن متأكدًا مما إذا كنت مسجّلاً حاليًا، يُرجى التحقّق من Merchant Center.

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

لمزيد من المعلومات، يُرجى الاطّلاع على معايير وسياسات المشاركة.

إنشاء مصدر بيانات

يمكنك استخدام الـ accounts.dataSources.create طريقة لإنشاء مصدر بيانات للعروض الترويجية. إذا كان مصدر بيانات حالي للعروض الترويجية متاحًا، استخدِم الـ accounts.dataSources.list طريقة لاسترداد جميع مصادر البيانات. بعد ذلك، يمكنك استخدام حقل name في مصدر بيانات العروض الترويجية لـ إنشاء عروض ترويجية.

يوضّح الطلب التالي كيفية إنشاء مصدر بيانات لإضافة عروض ترويجية:

POST https://merchantapi.googleapis.com/datasources/v1/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"
}

إنشاء إعلانات ترويجية

يمكنك استخدام الـ 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 عروضك الترويجية ويوافق عليها قبل نشرها. لمزيد من المعلومات، يُرجى الاطّلاع على عملية الموافقة على العروض الترويجية.

ننصحك بالاطّلاع على سياسات العروض الترويجية للتأكّد من أنّ العروض الترويجية التي تنشئها تضيف قيمة وتلتزم بسياسات "إعلانات Shopping".

يوضّح الطلب التالي كيفية إنشاء عرض ترويجي على الإنترنت:

HTTP

POST https://merchantapi.googleapis.com/promotions/v1/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}"
}

cURL

  curl --request POST \
'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"dataSource":"{DATASOURCE_ID}","promotion":{"name":"accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}y","promotionId":"abc","contentLanguage":"en","targetCountry":"US","redemptionChannel":["ONLINE"]}}' \
--compressed

للحصول على معلومات حول القواعد السارية على ضبط رقم تعريف العرض الترويجي، يُرجى الاطّلاع على الحد الأدنى من المتطلبات لسمة "رقم تعريف العرض الترويجي".

القيمتان الصالحتان لحقل offerType الإلزامي هما NO_CODE وGENERIC_CODE. إذا لم تقدّم إحدى هاتَين القيمتَين، سيفشل طلب بيانات من واجهة برمجة التطبيقات مع ظهور الردّ [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type على HTTP 400. تظهر رسالة خطأ مماثلة إذا لم تقدّم أيًا من الحقول الإلزامية.

إذا لم تقدّم قيمة للحقل attributes.genericRedemptionCode، سيفشل الطلب مع ظهور الردّ [genericRedemptionCode] No redemption code provided على HTTP 400.

يجب أن تكون قيمتا الحقلَين promotion.attributes.promotionDisplayTimePeriod.startTime وpromotion.attributes.promotionDisplayTimePeriod.endTime بالتنسيق yyyy-mm-ddThh:mm:ssZ. تأكَّد من استبدال قيمتَي هذَين الحقلَين بتاريخَين في المستقبل.

لمزيد من المعلومات، يُرجى الاطّلاع على مواصفات بيانات العروض الترويجية.

للاطّلاع على أفضل الممارسات المتعلّقة بإنشاء عرض ترويجي، يُرجى الاطّلاع على أفضل الممارسات المتعلّقة بالعروض الترويجية.

للاطّلاع على قائمة بالسمات ذات الصلة بالعروض الترويجية، يُرجى الاطّلاع على إضافة سمات البيانات المنظّمة.

بعد تشغيل طلب إنشاء العرض الترويجي بنجاح، قد يستغرق استرداد العرض الترويجي باستخدام واجهة برمجة التطبيقات أو ظهوره في Merchant Center بضع دقائق.

في ما يلي نموذج يمكنك استخدامه لإدراج عروض ترويجية متعددة بشكل غير متزامن:

جافا

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1.Attributes;
import com.google.shopping.merchant.promotions.v1.CouponValueType;
import com.google.shopping.merchant.promotions.v1.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1.OfferType;
import com.google.shopping.merchant.promotions.v1.ProductApplicability;
import com.google.shopping.merchant.promotions.v1.Promotion;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder().setPoolSize(30).build();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}InsertPromotionsAsyncSample.java

في ما يلي بعض العروض الترويجية النموذجية التي يمكنك استخدامها للبدء.

عرض ترويجي محلي ينطبق على كل المنتجات وكل المتاجر

يوضّح طلب النموذج التالي كيفية إنشاء عرض ترويجي محلي ينطبق على جميع المنتجات في حسابك على Merchant Center وجميع المتاجر المُضافة في حسابك على الملف التجاري المرتبط.

POST https://merchantapi.googleapis.com/promotions/v1/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/v1/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 ورقم تعريف العرض الترويجي. تعرض طريقة GET مورد العروض الترويجية المقابل.

على سبيل المثال:

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer {ACCESS_TOKEN}' \
   --header 'Accept: application/json' \
   --compressed

غيِّر القيم في السلسلة على الشكل التالي:

{ACCOUNT_ID}: المعرّف الفريد لحسابك على Merchant Center
{PROMOTION_ID}: المعرّف الفريد للعرض الترويجي الذي تريد استرداده التنسيق هو {CHANNEL}~{CONTENT_LANGUAGE}~ {TARGET_COUNTRY}~{PROMOTION_ID}.

يُرجى العِلم أنّ استرداد عرض ترويجي تم إنشاؤه حديثًا باستخدام واجهة برمجة التطبيقات يستغرق بضع دقائق.

الاطّلاع على عرض ترويجي محلي

يسترد طلب النموذج التالي عرضًا ترويجيًا محليًا معرّف العرض الترويجي الخاص به هو in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1/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/v1/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 المستخدَم في هذا النموذج المنتجات المؤهَّلة للاستفادة من العرض الترويجي. لمزيد من المعلومات، يُرجى الاطّلاع على رقم تعريف المنتج للعرض الترويجي.

سرد العروض الترويجية

يمكنك استخدام الـ promotions.list طريقة للاطّلاع على جميع العروض الترويجية التي تم إنشاؤها.

في ما يلي نموذج للطلب:

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer {ACCESS_TOKEN}' \
   --header 'Accept: application/json' \
   --compressed

يحتوي الردّ على قائمة بجميع العروض الترويجية في حسابك. لكل عرض ترويجي، يمكنك الاطّلاع على تفاصيل مثل 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 Center. لمزيد من المعلومات، يُرجى الاطّلاع على تعديل عرض ترويجي أو تغيير حالته.

لإنهاء عرض ترويجي حالي، يمكنك استخدام الـ accounts.promotions.insert طريقة لتعديل الحقل attributes.promotionEffectiveTimePeriod.endTime إلى وقت في الماضي.

مزيد من المعلومات

لمزيد من التفاصيل، يُرجى الاطّلاع على مركز مساعدة العروض الترويجية.
لتحديد وحلّ المشاكل الشائعة، يُرجى الاطّلاع على تحديد وحلّ المشاكل المتعلّقة بواجهة برمجة التطبيقات الفرعية للعروض الترويجية.
للتعرّف على كيفية نقل البيانات من Content API for Shopping، يُرجى الاطّلاع على نقل إدارة العروض الترويجية.

Troubleshoot issues

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

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

إنشاء مصدر بيانات

إنشاء إعلانات ترويجية

HTTP

cURL

جافا

عرض ترويجي محلي ينطبق على كل المنتجات وكل المتاجر

عرض ترويجي على الإنترنت ينطبق على منتجات محدّدة باستخدام رمز تحصيل القيمة

الاطّلاع على العروض الترويجية

HTTP

cURL

الاطّلاع على عرض ترويجي محلي

الاطّلاع على عرض ترويجي على الإنترنت

سرد العروض الترويجية

HTTP

cURL

الاطّلاع على حالة عرض ترويجي

نموذج لحالة العرض الترويجي

حذف عمليات الترويج

مزيد من المعلومات

نظرة عامة على واجهة برمجة التطبيقات الفرعية للعروض الترويجية