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

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

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

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

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

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

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

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

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

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

مصدر بيانات المنتج في Google Merchant Center
مصدر بيانات العروض الترويجية في Google Merchant Center
حساب على إعلانات Google لإنشاء حملات تسوّق

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

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

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

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

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

للإشارة إليها مباشرةً في طلبات البيانات المستقبلية من واجهة برمجة التطبيقات، ننصح بشدة بتخزين accounts.dataSources.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. إذا لم تقدّم إحدى هذه القيم، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات مع ظهور استجابة HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. تظهر رسالة خطأ مشابهة إذا لم يتم تقديم أي من الحقول الإلزامية.

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

يجب أن تكون قيم الحقلَين 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.ChannelPoolSettings;
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()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(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 إلى وقت في الماضي.

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

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

Troubleshoot issues

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

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

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

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

HTTP

cURL

جافا

عرض ترويجي محلي يسري على كل المنتجات وكل المتاجر

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

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

HTTP

cURL

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

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

عرض قائمة العروض الترويجية

HTTP

cURL

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

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

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

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

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