Gunakan promosi untuk menampilkan penawaran spesial untuk produk yang Anda jual di Google. Promosi ditampilkan di berbagai properti Google, termasuk Google Penelusuran, Shopping, dan Chrome. Promosi harus memenuhi kriteria tertentu agar disetujui. Untuk mengetahui informasi selengkapnya, lihat Kriteria promosi.
Saat Anda menambahkan promosi ke produk, pembeli akan melihat link penawaran spesial. Misalnya, "Diskon 15%" atau "Pengiriman gratis". Link penawaran dapat meningkatkan daya tarik produk Anda dan mendorong pembeli untuk melakukan pembelian. Semua promosi diterapkan saat checkout atau di tempat penjualan.
Untuk informasi selengkapnya, lihat Dasar-dasar promosi.
Prasyarat
Google memerlukan informasi spesifik tentang bisnis dan produk Anda sebelum menampilkan promosi. Anda harus memiliki hal berikut:
- Feed produk aktif di Google Merchant Center.
- Feed promosi aktif di Google Merchant Center.
- Akun Google Ads untuk kampanye Shopping.
Selain itu, Anda harus mendaftarkan akun penjual ke program Promosi. Jika Anda tidak yakin apakah sudah terdaftar, periksa Merchant Center.
Jika Anda belum terdaftar, isi formulir permintaan. Tim promosi akan memberi tahu Anda saat Anda siap untuk memulai penerapan.
Untuk informasi selengkapnya, lihat Kriteria dan kebijakan partisipasi.
Membuat sumber data
Anda dapat menggunakan metode accounts.dataSources.create untuk membuat sumber data promosi. Jika sumber data promosi yang ada
tersedia, gunakan
metode
accounts.dataSources.list
untuk mengambil semua sumber data. Kemudian, Anda dapat menggunakan kolom name
sumber data promosi untuk membuat promosi.
Permintaan berikut menunjukkan cara membuat sumber data untuk menambahkan promosi:
POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources
{
"displayName": "{DISPLAY_NAME}",
"promotionDataSource": {
"contentLanguage": "{CONTENT_LANGUAGE}",
"targetCountry": "{TARGET_COUNTRY}"
}
}
Ganti kode berikut:
- {ACCOUNT_ID}: ID unik akun Anda seperti yang muncul di UI Merchant Center.
- {DISPLAY_NAME}: Nama tampilan sumber data.
- {CONTENT_LANGUAGE}: Kode bahasa ISO 639-1 dua huruf dari produk di sumber data.
- {TARGET_COUNTRY}: Kode wilayah CLDR negara target tempat Anda ingin promosi terlihat.
Setelah permintaan berhasil berjalan, Anda akan melihat respons berikut yang berisi detail tentang sumber data promosi yang baru dibuat:
{
"name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
"dataSourceId": "{DATASOURCE_ID}",
"displayName": "{DISPLAY_NAME}",
"promotionDataSource": {
"targetCountry": "{TARGET_COUNTRY}",
"contentLanguage": "{CONTENT_LANGUAGE}"
},
"input": "API"
}
Buat promosi
Anda dapat menggunakan metode
accounts.promotions.insert
untuk membuat atau memperbarui promosi. Metode accounts.promotions.insert
mengambil resource
promotions
dan nama sumber data sebagai input. Metode ini menampilkan promosi baru atau yang diperbarui, jika berhasil.
Membuat promosi memerlukan nama sumber data. Anda juga harus memberikan nilai untuk kolom berikut dalam permintaan:
contentLanguage
redemptionChannel
promotionId
targetCountry
attributes.offerType
attributes.genericRedemptionCode
attributes.couponValueType
attributes.productApplicability
attributes.promotionEffectiveTimePeriod.endTime
attributes.promotionEffectiveTimePeriod.startTime
attributes.longTitle
Google akan meninjau dan menyetujui promosi Anda sebelum mendistribusikannya. Untuk mengetahui informasi selengkapnya, lihat Proses persetujuan promosi.
Sebaiknya baca kebijakan promosi untuk memastikan promosi yang Anda buat memberikan nilai tambah dan mematuhi kebijakan iklan Shopping.
Permintaan berikut menunjukkan cara membuat promosi 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}"
}
Untuk mengetahui informasi tentang aturan yang berlaku untuk menetapkan ID promosi, lihat Persyaratan minimum untuk atribut ID promosi.
Nilai yang valid untuk kolom offerType
wajib adalah NO_CODE
dan
GENERIC_CODE
. Jika Anda tidak memberikan salah satu nilai ini, permintaan API akan gagal dengan respons HTTP 400 [offer_type] validation/missing_required: Invalid or
missing required attribute: offer_type
. Pesan error serupa akan ditampilkan jika
Anda tidak memberikan kolom wajib.
Jika Anda tidak memberikan nilai untuk kolom attributes.genericRedemptionCode
,
permintaan akan gagal dengan respons HTTP 400 [genericRedemptionCode] No
redemption code provided
.
Nilai untuk kolom promotion.attributes.promotionDisplayTimePeriod.startTime
dan promotion.attributes.promotionDisplayTimePeriod.endTime
harus dalam
format yyyy-mm-ddThh:mm:ssZ
. Pastikan untuk mengganti nilai untuk kolom
ini dengan tanggal di masa mendatang.
Untuk mengetahui informasi selengkapnya, lihat Spesifikasi data promosi.
Untuk praktik terbaik tentang cara membuat promosi, lihat Praktik terbaik promosi.
Untuk mengetahui daftar atribut terkait promosi, lihat Menambahkan atribut data terstruktur.
Setelah permintaan pembuatan promosi berhasil dijalankan, perlu waktu beberapa menit agar promosi dapat diambil menggunakan API atau muncul di Merchant Center.
Berikut adalah contoh yang dapat Anda gunakan untuk menyisipkan beberapa promosi secara asinkron:
Java
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.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1beta.Attributes;
import com.google.shopping.merchant.promotions.v1beta.CouponValueType;
import com.google.shopping.merchant.promotions.v1beta.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1beta.OfferType;
import com.google.shopping.merchant.promotions.v1beta.ProductApplicability;
import com.google.shopping.merchant.promotions.v1beta.Promotion;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1beta.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();
PromotionsServiceSettings merchantPromotionsServiceSettings =
PromotionsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.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>");
}
}
Berikut adalah beberapa contoh promosi yang dapat Anda gunakan untuk memulai.
Promosi lokal yang berlaku untuk semua produk dan semua toko
Contoh permintaan berikut menunjukkan cara membuat promosi lokal yang berlaku untuk semua produk di akun Merchant Center dan semua toko yang ditambahkan di akun Profil Bisnis tertaut.
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}"
}
Kolom productApplicability
wajib diisi. Atribut ini menandakan penerapan promosi untuk semua produk atau hanya produk tertentu. Nilai yang didukung
adalah ALL_PRODUCTS
dan SPECIFIC_PRODUCTS
. Untuk mengetahui informasi selengkapnya, lihat Memilih
produk untuk promosi Anda.
Kolom couponValueType
wajib diisi. Kode ini menandakan jenis promosi yang
Anda jalankan. Untuk mengetahui daftar nilai dukungan, lihat Jenis nilai kupon. Bergantung pada jenis
nilai kupon yang Anda pilih, beberapa atribut
diperlukan.
Kolom minimumPurchaseQuantity
memungkinkan Anda menetapkan nilai untuk jumlah pembelian minimum yang diperlukan untuk menukarkan penawaran promosi. Untuk mengetahui informasi
selengkapnya, lihat Jumlah pembelian minimum untuk
promosi.
Demikian pula, Anda dapat menggunakan kolom minimumPurchaseAmount
untuk menetapkan jumlah pembelian minimum yang diperlukan untuk menukarkan promosi. Untuk informasi selengkapnya,
lihat Jumlah pembelian minimum.
Untuk informasi selengkapnya tentang nilai yang perlu Anda berikan untuk membuat promosi lokal, lihat Spesifikasi sumber data untuk promosi lokal.
Promosi online yang berlaku untuk produk tertentu dengan kode penukaran
Contoh permintaan berikut menunjukkan cara membuat promosi online yang berlaku untuk produk yang dipilih dengan kode penukaran.
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"
}
Lihat promosi
Untuk melihat promosi, gunakan
accounts.promotions.get
.
Permintaan GET
ini bersifat hanya baca. Tindakan ini memerlukan merchantId
dan ID promosi. Metode GET
menampilkan resource promosi yang sesuai.
Contoh:
GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}
Ganti kode berikut:
- {ACCOUNT_ID}: ID unik akun Merchant Center Anda.
- {PROMOTION_ID}: ID unik promosi yang ingin Anda ambil. Formatnya adalah {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.
Perhatikan bahwa perlu waktu beberapa menit agar promosi yang baru dibuat dapat diambil menggunakan API.
Melihat promosi lokal
Contoh permintaan berikut mengambil promosi lokal yang ID promosinya adalah
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
Setelah permintaan berhasil, Anda akan melihat respons berikut:
{
"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"
}
Kolom moneyOffAmount
dalam contoh ini memberikan diskon yang ditawarkan
dalam promosi. Untuk mengetahui informasi selengkapnya, lihat Jumlah diskon moneter promosi.
Kolom promotionUrl
dalam contoh ini memberikan link ke situs toko
tempat pembeli dapat menemukan informasi selengkapnya tentang promosi. Promosi iklan inventaris lokal
akan menampilkan error jika Anda tidak menyertakan kolom promotionUrl
.
Melihat promosi online
Contoh permintaan berikut mengambil promosi online yang ID promosinya adalah
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}"
}
Kolom itemIdInclusion
yang digunakan dalam contoh ini menyebutkan produk yang
memenuhi syarat untuk promosi. Untuk mengetahui informasi selengkapnya, lihat ID produk untuk
promosi.
Mencantumkan promosi
Anda dapat menggunakan metode
promotions.list
untuk melihat semua promosi yang dibuat.
GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions
Respons berisi daftar semua promosi di akun Anda. Untuk setiap
promosi, Anda dapat melihat detail seperti promotionId
, redemptionChannel
,
dataSource
, promotionStatus
, dan lainnya.
Melihat status promosi
Untuk melihat status promosi, lihat atribut promotionStatus
yang ditampilkan oleh metode
promotions.get
atau
promotions.list
.
Kolom promotionStatus
dapat memiliki nilai berikut:
IN_REVIEW
: Promosi masih dalam peninjauan.REJECTED
: Promosi tidak disetujui.LIVE
: Promosi disetujui dan aktif.STOPPED
: Promosi dihentikan oleh akun.EXPIRED
: Promosi tidak lagi aktif.PENDING
: Promosi tidak dihentikan, dan semua peninjauan disetujui, tetapi tanggal aktifnya adalah pada masa mendatang.STATE_UNSPECIFIED
: Status promosi tidak diketahui.
Untuk memahami proses persetujuan promosi yang Anda buat, lihat Proses persetujuan promosi.
Contoh status promosi
Contoh berikut menunjukkan perbedaan antara permintaan yang berhasil dan gagal.
Pemetaan produk tidak ada
Isi respons berikut menunjukkan promosi online yang tidak disetujui karena pemetaan produk tidak ada.
"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"
]
}
]
}
Untuk memecahkan masalah promosi yang tidak disetujui dan mempelajari cara menghindari penolakan di masa mendatang, lihat Memperbaiki masalah terkait promosi yang tidak disetujui.
Jika promosi yang Anda buat tidak disetujui, Anda akan menerima email yang menyebutkan alasan penolakan dan petunjuk untuk memperbaiki masalah.
Promosi sedang dievaluasi
Isi respons berikut menampilkan promosi yang masih dievaluasi.
"promotionStatus": {
"destinationStatuses": [
{
"reportingContext": "FREE_LISTINGS",
"status": "PENDING"
},
{
"destination": "SHOPPING_ADS",
"status": "PENDING"
}
],
"itemLevelIssues": []
}
Promosi yang disetujui dan sedang berlangsung
Isi respons berikut menampilkan promosi yang terlihat oleh pembeli.
"promotionStatus": {
"destinationStatuses": [
{
"reportingContext": "FREE_LISTINGS",
"status": "LIVE"
},
{
"destination": "SHOPPING_ADS",
"status": "LIVE"
} ],
"itemLevelIssues": []
}
Untuk informasi selengkapnya, lihat FAQ status promosi.
Pelajari lebih lanjut
- Untuk mengetahui detail selengkapnya, lihat Pusat Bantuan Promosi.
- Untuk memecahkan masalah umum, lihat Memecahkan masalah terkait Merchant Promotions API.
- Untuk mempelajari cara bermigrasi dari Content API for Shopping, lihat Memigrasikan pengelolaan promosi.