Omówienie interfejsu API promocji sprzedawcy

Korzystaj z promocji, aby prezentować oferty specjalne produktów, które sprzedajesz w Google. Promocje wyświetlają się w różnych usługach Google, takich jak wyszukiwarka Google, Zakupy Google i Chrome. Aby można było zatwierdzić promocje, muszą one spełniać określone kryteria. Więcej informacji znajdziesz w kryteriach promocji.

Gdy dodasz promocję do produktów, kupujący zobaczą link do oferty specjalnej. Na przykład „15% zniżki” lub „Bezpłatna dostawa”. Linki do ofert mogą zwiększać atrakcyjność Twoich produktów i zachęcać klientów do zakupu. Wszystkie promocje są uwzględniane w momencie płatności lub w punkcie sprzedaży.

Więcej informacji znajdziesz w artykule Podstawy promocji.

Zanim będziemy mogli wyświetlać Twoje promocje, musisz podać konkretne informacje na temat swojej firmy i produktów. Musisz mieć:

Dodatkowo musisz zarejestrować swoje konto sprzedawcy w programie Promocje. Jeśli nie masz pewności, czy jesteś już zarejestrowany, sprawdź Merchant Center.

Jeśli nie jesteś zarejestrowany, wypełnij formularz prośby. Zespół ds. promocji poinformuje Cię, kiedy będzie można rozpocząć wdrażanie.

Więcej informacji znajdziesz w artykule Kryteria i zasady uczestnictwa.

Tworzenie źródła danych

Aby utworzyć źródło danych o promocjach, możesz użyć metody accounts.dataSources.create. Jeśli dostępne jest istniejące źródło danych o promocjach, użyj metody accounts.dataSources.list, aby pobrać wszystkie źródła danych. Następnie możesz użyć pola name w źródle danych o promocjach, aby tworzyć promocje.

Następujące żądanie pokazuje, jak utworzyć źródło danych na potrzeby dodawania promocji:

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

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

Zastąp następujące elementy:

  • {ACCOUNT_ID}: unikalny identyfikator Twojego konta, który jest widoczny w interfejsie Merchant Center.
  • {DISPLAY_NAME}: wyświetlana nazwa źródła danych.
  • {CONTENT_LANGUAGE}: dwuliterowy kod języka ISO 639-1 produktów w źródle danych.
  • {TARGET_COUNTRY}: kod regionu CLDR kraju docelowego, w którym mają być widoczne promocje.

Po wykonaniu żądania zobaczysz odpowiedź zawierającą szczegóły nowo utworzonego źródła danych o promocjach:

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

Zorganizuj promocję

Aby utworzyć lub zaktualizować promocję, możesz użyć metody accounts.promotions.insert. Metoda accounts.promotions.insert przyjmuje jako dane wejściowe zasób promotions i nazwę źródła danych. W przypadku powodzenia zwraca nową lub zaktualizowaną promocję.

Aby utworzyć promocję, musisz podać nazwę źródła danych. W prośbie musisz też podać wartości w tych polach:

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

Google sprawdza i zatwierdza Twoje promocje, zanim zostaną rozpowszechnione. Więcej informacji znajdziesz w procesie zatwierdzania promocji.

Zalecamy zapoznanie się z zasadami dotyczącymi promocji, aby mieć pewność, że tworzone przez Ciebie promocje dodają wartości i są zgodne z zasadami dotyczącymi reklam produktowych.

Ten przykład pokazuje, jak utworzyć promocję online:

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}"
}

Informacje o zasadach dotyczących ustawiania identyfikatora promocji znajdziesz w artykule Minimalne wymagania dotyczące atrybutu identyfikator promocji.

Prawidłowe wartości dla obowiązkowego pola offerType to NO_CODE i GENERIC_CODE. Jeśli nie podasz jednej z tych wartości, żądanie interfejsu API zakończy się niepowodzeniem i otrzymasz odpowiedź HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Podobny komunikat o błędzie jest zwracany, jeśli nie podasz żadnych pól obowiązkowych.

Jeśli nie podasz wartości pola attributes.genericRedemptionCode, żądanie zakończy się niepowodzeniem i uzyskasz odpowiedź HTTP 400 [genericRedemptionCode] No redemption code provided.

Wartości pól promotion.attributes.promotionDisplayTimePeriod.startTime i promotion.attributes.promotionDisplayTimePeriod.endTime muszą mieć format yyyy-mm-ddThh:mm:ssZ. Pamiętaj, aby zastąpić wartości w tych polach datami z przyszłości.

Więcej informacji znajdziesz w specyfikacji danych o promocjach.

Sprawdzone metody tworzenia promocji znajdziesz w artykule Sprawdzone metody dotyczące promocji.

Listę atrybutów związanych z promocjami znajdziesz w artykule Dodawanie atrybutów danych strukturalnych.

Po pomyślnym przetworzeniu żądania utworzenia promocji może minąć kilka minut, zanim będzie można ją pobrać za pomocą interfejsu API lub wyświetlić w Merchant Center.

Poniżej znajdziesz kilka przykładowych promocji, które możesz wykorzystać na początek.

promocja lokalna dotycząca wszystkich produktów i sklepów,

Poniższy przykładowy request pokazuje, jak utworzyć promocję lokalną, która będzie obowiązywać w przypadku wszystkich produktów na Twoim koncie Merchant Center oraz wszystkich sklepów dodanych do połączonego konta Profilu Firmy.

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}"
}

Pole productApplicability jest wymagane. Określa, czy promocja dotyczy wszystkich czy tylko określonych produktów. Obsługiwane wartości to ALL_PRODUCTSSPECIFIC_PRODUCTS. Więcej informacji znajdziesz w artykule Wybieranie produktów do promocji.

Pole couponValueType jest wymagane. Wskazuje typ promocji, którą prowadzisz. Listę obsługiwanych wartości znajdziesz w sekcji Typ wartości kuponu. W zależności od wybranego typu wartości kuponu niektóre atrybuty są wymagane.

Pole minimumPurchaseQuantity umożliwia ustawienie wartości minimalnej wielkości zakupu, która jest wymagana do skorzystania z oferty promocyjnej. Więcej informacji znajdziesz w artykule Minimalna wielkość zakupu dla promocji.

Podobnie możesz użyć pola minimumPurchaseAmount, aby ustawić minimalną kwotę zakupu wymaganą do skorzystania z promocji. Więcej informacji znajdziesz w artykule Minimalna kwota zakupu.

Więcej informacji o wartościach, które musisz podać, aby utworzyć promocję lokalną, znajdziesz w artykule Specyfikacja źródeł danych w przypadku promocji produktów dostępnych lokalnie.

promocja online dotycząca wybranych produktów z kodem do zrealizowania;

Poniższy przykładowy formularz pokazuje, jak utworzyć promocję online, która dotyczy wybranych produktów z kodem realizacji.

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"
}

Wyświetl promocje

Aby wyświetlić promocję, użyj właściwości accounts.promotions.get. To GET jest tylko do odczytu. Wymaga to podania merchantId i identyfikatora promocji. Metoda GET zwraca odpowiedni zasób promocji.

Na przykład:

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

Zastąp następujące elementy:

  • {ACCOUNT_ID}: unikalny identyfikator konta Merchant Center.
  • {PROMOTION_ID}: unikalny identyfikator promocji, którą chcesz pobrać. Format: {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Uwaga: utworzenie nowej promocji i możliwość jej pobrania za pomocą interfejsu API zajmuje kilka minut.

Wyświetlanie promocji lokalnej

Poniższe przykładowe zapytanie pobiera promocję lokalną o identyfikatorze 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

Po pomyślnym przesłaniu żądania wyświetli się taka odpowiedź:

{
 "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"
}

W tym przykładzie pole moneyOffAmount zawiera rabat oferowany w ramach promocji. Więcej informacji znajdziesz w sekcji Kwota rabatu w promocji.

W tym przykładzie pole promotionUrl zawiera link do witryny sklepu, w której klienci mogą znaleźć więcej informacji o promocji. Promowanie reklam lokalnego asortymentu produktów powoduje błąd, jeśli nie uwzględnisz pola promotionUrl.

Wyświetlanie promocji online

Poniższe przykładowe żądanie pobiera promocję internetową o identyfikatorze 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}"
}

Pole itemIdInclusion w tym przykładzie zawiera produkty kwalifikujące się do promocji. Więcej informacji znajdziesz w artykule Identyfikator produktu na potrzeby promocji.

Wyświetlanie listy promocji

Aby wyświetlić wszystkie utworzone promocje, możesz użyć metody promotions.list.

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

Odpowiedź zawiera listę wszystkich promocji na Twoim koncie. W przypadku każdej promocji możesz zobaczyć takie szczegóły jak promotionId, redemptionChannel, dataSource, promotionStatus i inne.

Wyświetlanie stanu promocji

Aby sprawdzić stan promocji, sprawdź atrybut promotionStatus zwracany przez metodę promotions.get lub promotions.list.

Pole promotionStatus może mieć jedną z tych wartości:

  • IN_REVIEW: promocja jest nadal sprawdzana.
  • REJECTED: promocja została odrzucona.
  • LIVE: promocja została zatwierdzona i jest aktywna.
  • STOPPED: promocja została zatrzymana przez konto.
  • EXPIRED: promocja nie jest już aktywna.
  • PENDING: promocja nie została zatrzymana, wszystkie opinie zostały zatwierdzone, ale data rozpoczęcia jest w przyszłości.
  • STATE_UNSPECIFIED: nieznany stan promocji.

Aby dowiedzieć się więcej o procesie zatwierdzania utworzonej przez Ciebie promocji, przeczytaj artykuł Proces zatwierdzania promocji.

Przykładowy stan promocji

Poniższe przykłady pokazują różnicę między żądaniami, które się powiodły, a tymi, które się nie powiodły.

Brak mapowania produktów

Treść odpowiedzi poniżej pokazuje promocję online, która została odrzucona z powodu braku mapowania produktów.

  "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"
        ]
      }
    ]
  }

Aby dowiedzieć się, jak rozwiązać problemy z odrzuconymi promocjami i uniknąć odrzucenia w przyszłości, przeczytaj artykuł Rozwiązywanie problemów z odrzuconymi promocjami.

Jeśli utworzona przez Ciebie promocja nie zostanie zatwierdzona, otrzymasz e-maila z podaniem powodu odrzucenia i instrukcjami dotyczącymi rozwiązania problemów.

Promocja w trakcie oceny

Poniższy tekst odpowiedzi pokazuje promocję, która jest nadal oceniana.

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

Zatwierdzona i aktywne promocja

Treść odpowiedzi poniżej pokazuje promocję widoczną dla kupujących.

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

Więcej informacji znajdziesz w najczęstszych pytaniach dotyczących stanu promocji.

Więcej informacji