Bermigrasi dari v1beta ke v1

Panduan ini membantu Anda bermigrasi dari Merchant API v1beta ke v1, versi pertama untuk Ketersediaan Umum. Versi v1 memperkenalkan beberapa update dan beberapa perubahan yang mungkin memerlukan update kode. Perubahan ini dirancang untuk menyederhanakan API dan meningkatkan pengelolaan akun Merchant Center Anda.

Perbedaan utama

Berikut adalah perubahan paling penting yang perlu diperhatikan saat bermigrasi dari v1beta ke v1:

• Pendaftaran satu kali setidaknya satu developer API untuk menggunakan Merchant API: Anda harus memanggil metode registerGcp (hanya sekali untuk setiap project Google Cloud yang digunakan untuk autentikasi) guna memberikan detail kontak Anda, yang memungkinkan Anda menggunakan API dan menerima info terbaru serta pengumuman terkait Merchant API. Anda tidak akan dapat menggunakan API v1 atau v1alpha hingga langkah ini selesai. Untuk mengetahui petunjuknya, lihat Mendaftar sebagai developer
• Product.attributes diganti namanya menjadi: Kolom Product.attributes telah diganti namanya menjadi Product.productAttributes.
• Penghapusan informasi pajak tingkat produk: Kolom taxes dan taxCategory telah dihapus dari objek Product.productAttributes. Baca artikel Bantuan Google Merchant Center tentang pajak untuk mengetahui info selengkapnya
• Perubahan pada kolom GTIN: Kolom gtin dalam objek Product.productAttributes telah diganti namanya menjadi gtins agar lebih mencerminkan bahwa kolom tersebut dapat menyimpan beberapa nilai. Kolom gtin dalam objek OrderTrackingSignals.lineItemDetails kini menjadi array dan juga telah diganti namanya menjadi gtins.
• Penghapusan kolom saluran: Kolom channel telah dihapus dari produk, input produk, dan sumber data. Kolom boolean baru, legacyLocal, telah diperkenalkan untuk menetapkan dengan jelas produk yang dijual secara eksklusif di toko fisik. Catatan: Kolom legacyLocal adalah kolom tambahan untuk membantu migrasi dan pada akhirnya akan dihentikan setelah metode pemasaran Online dan Lokal dapat sepenuhnya ditargetkan dengan satu sumber produk. Lihat tabel di bagian berikut untuk mengetahui informasi selengkapnya.
• Kolom baru untuk atribut inventaris regional dan lokal:
  • Semua kolom RegionalInventory kecuali name, account, dan region kini disatukan dalam objek baru bernama regionalInventoryAttributes . Misalnya, atribut RegionalInventory.price kini berada di bagian RegionalInventory.regionalInventoryAttributes.price.
  • Semua kolom LocalInventory kecuali name, account, dan storeCode kini disatukan dalam objek baru bernama localInventoryAttributes . Misalnya, atribut LocalInventory.price kini berada di bagian LocalInventory.localInventoryAttributes.price.
• Penghapusan customAttributes dari inventaris regional dan lokal: Kolom customAttributes telah dihapus dari resource RegionalInventory dan LocalInventory.
• Pembuatan akun yang lebih baik: Kolom users yang duplikat telah dihapus dari CreateAndConfigureAccountRequest. Gunakan kolom user tunggal untuk mengaitkan pengguna awal dengan akun baru.
• Jenis atribut tertentu diubah dari string menjadi enum: Beberapa kolom dalam resource Product dan Inventory dengan daftar singkat nilai yang ditentukan diubah dari jenis string menjadi jenis enum untuk validasi data yang lebih baik (misalnya, kolom Product.ProductAttributes.condition kini berjenis enum).
• Penghapusan metode pembaruan kebijakan pengembalian barang secara online: Metode onlineReturnPolicy.update dihapus di v1. Buat kebijakan pengembalian barang secara online menggunakan metode onlineReturnPolicy.create.

Cara melakukan migrasi

Versi v1beta Merchant API dijadwalkan untuk dihentikan pada 28 Februari 2026. Untuk mengetahui informasi selengkapnya tentang jadwal penghentian penggunaan, lihat Panduan penerapan versi Merchant API.

• Langkah pertama dalam melakukan migrasi adalah melakukan pendaftaran developer satu kali (Lihat Mendaftar sebagai developer). Anda harus memanggil metode registerGcp untuk setiap project Google Cloud yang Anda gunakan untuk autentikasi sebelum metode v1 dapat berfungsi.

• Terlepas dari cara Anda memanggil API (dengan REST, gRPC, atau menggunakan library klien), Anda dapat melakukan migrasi secara bertahap. Artinya, Anda dapat memperbarui dan memigrasikan kode satu API dalam satu waktu (misalnya, memindahkan API Products ke v1 sambil mempertahankan API Accounts di v1beta) tanpa harus memperbarui seluruh integrasi sekaligus.

Perubahan kolom mendetail

Tabel ini memberikan perbandingan mendetail tentang kolom yang telah berubah antara versi v1beta dan v1.

v1beta	v1	Deskripsi
Product.gtin	Product.gtins	Kolom untuk GTIN telah diganti namanya.
Product.taxes	Dihapus	Kolom taxes telah dihapus
Product.taxCategory	Dihapus	Kolom taxCategory telah dihapus
Product.channel	Dihapus	Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
Product.attributes	Product.productAttributes	Kolom attributes telah diganti namanya menjadi productAttributes.
availability, condition, gender, includedDestinations, dan excludedDestinations di kolom Product ditampilkan sebagai strings (atau array dari strings)	Kolom ini sekarang enums (atau array dari enums)	Kolom dengan daftar singkat nilai yang ditentukan diubah dari jenis string menjadi enum.
price, salePrice, salePriceEffectiveDate, dan availability di RegionalInventory	Dipindahkan ke RegionalInventory.regionalInventoryAttributes	Kolom ini telah dipindahkan ke regionalInventoryAttributes.
Kolom RegionalInventory.availability adalah string	RegionalInventory.regionalInventoryAttributes.availability sekarang menjadi enums	Jenis ketersediaan diubah dari string menjadi enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla, dan instoreProductLocation dalam LocalInventory	Dipindahkan ke LocalInventory.localInventoryAttributes	Kolom ini telah dipindahkan ke localInventoryAttributes.
Kolom LocalInventory.availability adalah string	LocalInventory.localInventoryAttributes.availability sekarang menjadi enums	Jenis ketersediaan diubah dari string menjadi enum.
LocalInventory.customAttributes	Dihapus	Atribut kustom tidak lagi didukung untuk inventaris lokal.
RegionalInventory.customAttributes	Dihapus	Atribut kustom tidak lagi didukung untuk inventaris regional.
ProductInput.channel	Dihapus	Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
DataSource.channel	Dihapus	Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
Tidak tersedia	ProductInput.legacyLocal	Kolom boolean baru untuk menunjukkan bahwa produk hanya dapat menargetkan metode pemasaran lokal. ID resource produk akan memiliki awalan "local~".
Tidak tersedia	Product.legacyLocal	Kolom boolean baru untuk menunjukkan bahwa produk hanya dijual di toko lokal dan tidak tersedia untuk pembelian online.
Tidak tersedia	DataSource.legacyLocal	Kolom boolean baru untuk menunjukkan bahwa sumber data berisi produk yang dijual hanya di toko lokal.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Kolom gtin telah diganti namanya menjadi gtins dan sekarang berupa array string (bukan string).
CreateAndConfigureAccountRequest.users	Dihapus	Kolom users telah dihapus. Gunakan kolom user untuk menambahkan administrator awal ke akun.