Referensi API Skrip Shopify

Skrip ditulis dengan API Ruby yang memberi Anda banyak kontrol dan fleksibilitas.

Persyaratan paket

Skrip Shopify dan aplikasi Script Editor hanya tersedia untuk toko pada paket Shopify Plus. Aplikasi Script Editor tidak lagi tersedia untuk diunduh dari Shopify App Store.

Pada 30 Juni 2026, Skrip Shopify akan dihapus dan tidak akan berfungsi lagi. Jika Anda ingin dukungan berkelanjutan untuk kasus penggunaan Skrip Shopify yang ada, Anda harus beralih ke pengganti Shopify Functions yang kompatibel untuk skrip pembayaran, pengiriman, atau item pesanan yang ada. Pelajari selengkapnya tentang beralih dari Skrip Shopify ke Shopify Functions.

Ada berbagai jenis skrip. Sebuah skrip diberi jenis saat Anda membuatnya di aplikasi Script Editor, berdasarkan templat skrip yang Anda pilih untuk memulai:

Skrip item pesanan

Skrip item pesanan memengaruhi item pesanan di keranjang dan dapat mengubah harga serta memberikan diskon. Skrip ini dijalankan saat ada perubahan yang dibuat pada keranjang.

Skrip item pesanan yang memberikan diskon pada langganan hanya berlaku untuk pembayaran pertama langganan tersebut. Pembayaran berikutnya tidak didiskon oleh skrip.

Beberapa metode hanya dapat digunakan dalam skrip item pesanan.

Skrip pengiriman

Skrip pengiriman berinteraksi dengan pengiriman, dan dapat mengubah metode pengiriman serta memberikan diskon pada tarif pengiriman. Skrip ini dijalankan saat checkout mencapai halaman opsi pengiriman.

Skrip pengiriman yang memberikan diskon pada tarif pengiriman langganan hanya berlaku untuk pembayaran pertama langganan tersebut. Pembayaran berikutnya tidak didiskon oleh skrip.

<p>Some methods <a href="#shipping-methods">can only be used in shipping scripts</a>.</p>

Skrip pembayaran

Skrip pembayaran berinteraksi dengan pembayaran, dan dapat mengganti nama, menyembunyikan, dan menyusun ulang gerbang pembayaran. Perhatikan bahwa skrip pembayaran tidak berinteraksi dengan gerbang pembayaran yang ditampilkan sebelum layar checkout, seperti Apple Pay. Skrip ini dijalankan saat checkout mencapai halaman pembayaran.

Beberapa metode hanya dapat digunakan dalam skrip pembayaran.

Metode umum

Metode berikut dapat digunakan dalam semua jenis skrip:

Input

Metode input skrip

Metode	Jenis hasil	Deskripsi
.cart	Keranjang	Mengembalikan objek keranjang yang dapat diubah.
.locale	string	Mengembalikan lokal pelanggan. Misalnya, en, fr, atau pt-BR.

Keranjang

Objek keranjang hanya tersedia di toko online. Beberapa checkout yang ditinggalkan memiliki akses ke objek keranjang. Namun, jika checkout telah ditutup lalu pelanggan mengunjungi checkout yang ditinggalkan, pelanggan akan diarahkan ke checkout yang sudah terisi dan objek keranjang tidak ada lagi. Hal ini karena etalase toko online telah dilewati oleh email pengingat checkout.

Metode skrip menggunakan objek Keranjang

Metode	Jenis hasil	Deskripsi
.customer	Pelanggan	Mengembalikan pemilik keranjang (jika ada).
.shipping_address	Alamat pengiriman	Mengembalikan alamat pengiriman pemilik keranjang (jika ada).
.discount_code	bervariasi	Mengembalikan: nil jika keranjang tidak memiliki kode diskon CartDiscount::FixedAmount jika keranjang memiliki diskon dengan jumlah tetap CartDiscount::Percentage jika keranjang memiliki diskon persentase CartDiscount::Shipping jika keranjang memiliki diskon pengiriman Mengembalikan satu kode diskon (lihat Batasan) discount_code ada jika diskon telah diterapkan pada keranjang. Ini tidak berarti bahwa harga keranjang berubah. Misalnya, jika diskon berlaku untuk keranjang di atas $50, dan skrip mengurangi harga keranjang di bawah $50, discount_code akan tetap ada, tetapi harga keranjang tidak berubah. <p><a href="/manual/checkout-settings/script-editor/examples/vat-script">See an example of <code>discount_code</code></a>.</p> </td> </tr> <tr> <td scope="row">.line_items</td> <td><a href="#list">List</a>&lt;LineItem&gt;</td> <td>Returns a list containing the line items in the cart.</td> </tr> <tr> <td scope="row">.presentment_currency</td> <td><a href="#list">List</a>&lt;String&gt;</td> <td>Returns the customer's local (presentment) currency (in <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217</a> format). For example, USD. </td> </tr> <tr> <td scope="row">.subtotal_price</td> <td><a href="#money">Money</a></td> <td>Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.</td> </tr> <tr> <td scope="row">.total_weight</td> <td><a href="https://shopify.dev/api/liquid/objects/line_item#line_item-grams">grams</a></td> <td>Returns the total weight of all the line items in the cart.</td> </tr>

CartDiscount::FixedAmount

Metode skrip menggunakan objek CartDiscount::FixedAmount

Metode	Jenis hasil	Deskripsi
.code	String	Mengembalikan kode diskon yang digunakan untuk menerapkan diskon.
.amount	Uang	Mengembalikan jumlah diskon dalam bentuk uang.
.reject({ message: String })	nil	Menolak kode diskon yang diterapkan ke keranjang. Diperlukan message.
.rejected?	Boolean	Mengembalikan apakah kode diskon ditolak.

CartDiscount::Percentage

Metode skrip menggunakan objek CartDiscount::Percentage

Metode	Jenis hasil	Deskripsi
.code	String	Mengembalikan kode diskon yang digunakan untuk menerapkan diskon.
.percentage	Desimal	Mengembalikan jumlah persentase diskon.
.reject({ message: String })	nil	Menolak kode diskon yang diterapkan ke keranjang. Diperlukan message.
.rejected?	Boolean	Mengembalikan apakah kode diskon ditolak.

CartDiscount::Shipping

Metode skrip menggunakan objek CartDiscount::Shipping

Metode	Jenis hasil	Deskripsi
.code	String	Mengembalikan kode diskon yang digunakan untuk menerapkan diskon.
.reject({ message: String })	nil	Menolak kode diskon yang diterapkan ke keranjang. Diperlukan message.
.rejected?	Boolean	Mengembalikan apakah kode diskon ditolak.

Pelanggan

Metode skrip menggunakan objek Pelanggan

Metode	Jenis hasil	Deskripsi
.id	Integer	Mengembalikan nomor ID pelanggan.
.email	String	Mengembalikan alamat email pelanggan.
.tags	Daftar<Tag>	Mengembalikan daftar string yang mewakili tag apa pun yang diatur untuk pelanggan.
.orders_count	Integer	Mengembalikan jumlah total pesanan yang telah dibuat oleh pelanggan.
.total_spent	Uang	Mengembalikan jumlah total yang telah dibelanjakan pelanggan untuk semua pesanan.
.accepts_marketing?	Boolean	Mengembalikan apakah pelanggan menerima pemasaran.

Item Pesanan

Metode skrip menggunakan objek Item Pesanan

Metode	Jenis hasil	Deskripsi
.grams	gram	Mengembalikan berat total item pesanan.
.line_price	Uang	Harga item pesanan.
.discounted?	Boolean	Mengembalikan apakah harga item pesanan telah didiskon oleh skrip atau diskon yang diterapkan secara manual. Penggunaan kode diskon tidak memengaruhi nilai yang dikembalikan.
.properties	hash	Mengembalikan properti yang ditentukan untuk item pesanan ini.
.variant	Varian	Mengembalikan varian produk spesifik yang diwakili oleh item pesanan.
.quantity	Integer	Mengembalikan kuantitas item pesanan ini.
.selling_plan_id	Integer	Mengembalikan ID rencana penjualan untuk item pesanan. Metode ini berguna saat toko menjual langganan dan Anda ingin skrip mendeteksi saat varian produk dijual sebagai langganan.

Daftar

Metode skrip menggunakan objek Daftar

Metode	Jenis hasil	Deskripsi
.new	Daftar	Membuat objek baru untuk mewakili daftar.
.[]	Elemen atau nil	Mengembalikan elemen pada indeks yang ditentukan.
.&	Daftar	Mengembalikan daftar baru yang berisi elemen yang sama untuk kedua daftar, tanpa duplikat.
.delete_if	Daftar	Hapus elemen menggunakan blok kode opsional. Lihat dokumentasi untuk metode delete_if Ruby.
.empty?	Boolean	Mengembalikan true jika daftar tidak berisi elemen.
.first	Elemen atau nil	Mengembalikan elemen pertama atau nil jika daftar kosong.
.index(*args, &block)	int atau nil	Mengembalikan indeks elemen pertama dari daftar. Jika blok diberikan sebagai pengganti argumen, mengembalikan indeks elemen pertama yang bloknya bernilai benar.
.rindex(*args, &block)	int atau nil	Mengembalikan indeks elemen terakhir dari daftar. Jika blok diberikan sebagai pengganti argumen, mengembalikan indeks elemen pertama yang bloknya bernilai benar.
.last	Elemen atau nil	Mengembalikan elemen terakhir atau nil jika daftar kosong.
.length	int	Mengembalikan jumlah elemen dalam daftar.
.size	int	Alias untuk length.
.each(*args, &block)	Daftar	Memanggil blok satu kali untuk setiap elemen dalam daftar, meneruskan elemen sebagai parameter ke blok.

Alamat Pengiriman

Metode skrip menggunakan objek Alamat Pengiriman

Metode	Jenis hasil	Deskripsi
.name	string	Mengembalikan nama orang yang terkait dengan alamat pengiriman.
.address1	string	Mengembalikan bagian alamat jalan dari alamat pengiriman.
.address2	string	Mengembalikan kolom tambahan opsional dari bagian alamat jalan pada alamat pengiriman.
.phone	string	Mengembalikan nomor telepon dari alamat pengiriman.
.city	string	Mengembalikan kota dari alamat pengiriman.
.zip	string	Mengembalikan Kode Pos dari alamat pengiriman.
.province	string	Mengembalikan provinsi/negara bagian dari alamat pengiriman.
.province_code	string	Mengembalikan nilai singkatan dari provinsi/negara bagian pada alamat pengiriman.
.country_code	string	Mengembalikan nilai singkatan dari negara pada alamat pengiriman.

Uang

Metode skrip menggunakan objek Uang

Metode	Jenis hasil	Deskripsi
.derived_from_presentment(customer_cents:X)	Uang	Mengonversi jumlah (dalam sen) dari mata uang lokal pelanggan (mata uang yang ditampilkan) ke mata uang toko Anda. Metode ini menerima parameter customer_cents, yang menerima angka dalam sen. Misalnya, Money.derived_from_presentment(customer_cents: 500).
.new	Uang	Membuat objek baru untuk mewakili harga.
.zero	Uang	Membuat objek baru dengan harga nol.
+	Uang	Menambahkan dua objek Money.
-	Uang	Mengurangkan satu objek Money dari objek lainnya.
*	Uang	Mengalikan objek Money dengan angka.

Contoh Uang

Money.new(cents: 1000)

Membuat objek Money yang mewakili 1000 sen, atau $10.

Money.new(cents: 100) * 50

Membuat objek Money yang mewakili $1, lalu mengalikan jumlah tersebut dengan 50. Menghasilkan objek Money yang mewakili $50.

Varian

Metode skrip yang menggunakan objek Varian

Metode	Jenis hasil	Deskripsi
.id	Integer	Menghasilkan nomor ID varian.
.price	Uang	Menghasilkan harga satuan varian.
.product	Produk	Menghasilkan produk terkait dari varian.
.skus	List<String>	Menghasilkan unit penyimpanan stok (SKU) varian, yang sering digunakan untuk melacak inventaris.
.title	String	Menghasilkan judul varian.

Produk

Metode skrip yang menggunakan objek Produk

Metode	Jenis hasil	Deskripsi
.id	Integer	Menghasilkan nomor ID produk.
.gift_card?	Boolean	Menghasilkan informasi apakah produk tersebut adalah kartu hadiah.
.tags	Daftar<Tag>	Menghasilkan daftar string yang mewakili tag yang diatur untuk produk ini.
.product_type	String	Kategorisasi yang dapat diberi tag pada produk, yang biasa digunakan untuk memfilter dan mencari.
.vendor	String	Menghasilkan vendor produk ini.

Kernel

Kernel adalah modul Ruby yang disertakan di setiap kelas. Hasilnya, metodenya tersedia untuk setiap objek. Metode ini bertindak dengan cara yang sama seperti fungsi global di bahasa lain.

Metode skrip yang menggunakan objek Kernel

Metode	Jenis hasil	Deskripsi
.exit	tidak ada	Mengakhiri eksekusi skrip saat ini tanpa kesalahan. Jika ini dijalankan sebelum apa pun ditetapkan ke Output.cart, skrip tidak akan berpengaruh. Ini adalah cara yang berguna untuk keluar dari skrip, misalnya, jika pelanggan tidak memenuhi syarat untuk menjalankan skrip.

Contoh Kernel

customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

Metode item pesanan

Metode berikut hanya dapat digunakan dalam skrip item pesanan:

Keranjang

Metode skrip yang menggunakan objek Keranjang dalam skrip item pesanan

Metode	Jenis hasil	Deskripsi
.subtotal_price_was	Uang	Menghasilkan harga subtotal keranjang sebelum diskon apa pun diterapkan.
.subtotal_price_changed?	Boolean	Menghasilkan informasi apakah harga subtotal telah berubah.

Item Pesanan

Metode skrip yang menggunakan objek LineItem dalam skrip item pesanan

Metode	Jenis hasil	Deskripsi
.change_line_price(Money new_price, { message: String })	Uang	Mengubah harga item pesanan menjadi jumlah yang ditentukan. message wajib diisi. new_price harus lebih rendah dari harga saat ini.
.original_line_price	Uang	Menghasilkan harga asli item pesanan sebelum skrip dan diskon diterapkan.
.line_price_was	Uang	Menghasilkan harga item pesanan sebelum perubahan diterapkan oleh skrip saat ini.
.line_price_changed?	Boolean	Menghasilkan informasi apakah harga item pesanan telah berubah.
.change_properties(hash new_properties, { message: String })	hash	Menetapkan properti baru untuk item pesanan. Hash properti asli disimpan di properties_was dan hash properti yang diteruskan ke metode menjadi properti baru untuk item pesanan.
.properties_was	hash	Menghasilkan hash properti asli item pesanan sebelum perubahan apa pun diterapkan.
.properties_changed?	Boolean	Menghasilkan informasi apakah properti untuk item pesanan telah diubah.
.split({ take: Integer })	LineItem	Membagi item pesanan menjadi dua item pesanan. take menentukan kuantitas yang akan dihapus dari item pesanan asli untuk membuat item pesanan baru.

Contoh .split

Contoh skrip ini membagi item pesanan bernama original_line_item menjadi dua item pesanan. Item pesanan baru memiliki kuantitas 1 (ditentukan oleh take: 1). Skrip kemudian menerapkan harga diskon ke item pesanan baru dengan pesan "Third hat for 5 dollars".

if original_line_item.quantity >= 3
  new_line_item = original_line_item.split(take: 1)
  new_line_item.change_line_price(Money.new(cents: 500), message: "Third hat for 5 dollars")
  cart.line_items << new_line_item
end

Varian

Metode skrip yang menggunakan objek Varian dalam skrip item pesanan

Metode	Jenis hasil	Deskripsi
.compare_at_price	Uang	Menghasilkan harga banding varian. Menghasilkan nil jika varian tidak memiliki harga banding.

Metode pengiriman

Metode berikut dapat digunakan dalam skrip pengiriman:

Input

Metode skrip yang menggunakan objek Input dalam skrip pengiriman

Metode	Jenis hasil	Deskripsi
.shipping_rates	ShippingRateList	Menampilkan daftar semua tarif pengiriman.

ShippingRateList

Metode skrip yang menggunakan objek ShippingRateList dalam skrip pengiriman

Metode	Jenis hasil	Deskripsi
.delete_if	ShippingRateList	Hapus tarif pengiriman menggunakan blok kode opsional. Lihat dokumentasi untuk metode delete_if Ruby.
.sort!	ShippingRateList	Urutkan tarif pengiriman menggunakan operator perbandingan atau menggunakan blok kode opsional. Lihat dokumentasi untuk metode sort! Ruby.
.sort_by!	ShippingRateList	Urutkan tarif pengiriman menggunakan blok kode opsional. Lihat dokumentasi untuk metode sort_by! Ruby.

ShippingRate

Metode skrip yang menggunakan objek ShippingRate dalam skrip pengiriman

Metode	Jenis hasil	Deskripsi
.code	String	Menampilkan kode tarif pengiriman.
.markup	Uang	Menampilkan penandaan untuk tarif pengiriman, jika berlaku.
.name	String	Menampilkan nama tarif pengiriman. Nama ini dapat diubah menggunakan metode change_name.
.price	Uang	Menampilkan harga tarif pengiriman.
.source	String	Menampilkan sumber (pengangkut) yang terkait dengan tarif pengiriman, jika relevan. Ini tidak dapat diubah.
.change_name(String new_name)	String	Mengubah nama (maksimum 255 karakter) tarif pengiriman. Sumber tidak dapat diubah, dihapus, atau disembunyikan.
.apply_discount(Money discount, { message: String })	Uang	Menerapkan diskon dengan jumlah tetap yang ditentukan. Harga tidak dapat dikurangi hingga di bawah 0. Pesan wajib diisi.
.phone_required?	Boolean	Menampilkan true jika nomor telepon diperlukan untuk mendapatkan tarif pengiriman, atau false jika nomor telepon tidak diperlukan.

Metode pembayaran

Metode berikut dapat digunakan dalam skrip pembayaran:

Input

Metode skrip yang menggunakan objek Input dalam skrip pembayaran

Metode	Jenis hasil	Deskripsi
.payment_gateways	PaymentGatewaysList	Menampilkan daftar semua gerbang pembayaran di toko.

PaymentGatewayList

Metode skrip yang menggunakan objek PaymentGatewayList dalam skrip pembayaran

Metode	Jenis hasil	Deskripsi
.delete_if	PaymentGatewayList	Hapus gerbang pembayaran menggunakan blok kode opsional. Lihat dokumentasi untuk metode delete_if Ruby.
.sort!	PaymentGatewayList	Urutkan gerbang pembayaran menggunakan operator perbandingan atau menggunakan blok kode opsional. Lihat dokumentasi untuk metode sort! Ruby.
.sort_by!	PaymentGatewayList	Urutkan gerbang pembayaran menggunakan blok kode opsional. Lihat dokumentasi untuk metode sort_by! Ruby.

PaymentGateway

Metode	Jenis hasil	Deskripsi
.name	String	Menampilkan nama gerbang pembayaran.
.enabled_card_brands	List<String>	Jika gerbang pembayaran mendukung kartu kredit, metode ini akan menampilkan daftar jenis kartu kredit yang diterima toko. Jika gerbang tidak mendukung kartu kredit, metode ini akan menampilkan daftar kosong.
.change_name(String new_name)	String	Mengubah nama gerbang pembayaran. Gerbang pembayaran dengan logo tidak dapat diganti namanya.

Contoh

Pada contoh skrip item pesanan berikut, saat pelanggan memesan produk yang bukan kartu hadiah, harga produk akan dikurangi sebesar $9. Selain itu, jumlah total yang telah dibelanjakan pelanggan selama semua kunjungan ke toko Anda juga ditampilkan:

customer = Input.cart.customer
Input.cart.line_items.each do |line_item|
  product = line_item.variant.product
  next if product.gift_card?
  line_item.change_line_price(line_item.line_price - Money.new(cents: 900), message: customer.total_spent)
end

Output.cart = Input.cart

Pelajari selengkapnya

Pelajari selengkapnya tentang:

• Dasar-dasar Ruby
• Membuat skrip
• Menguji dan melakukan debug pada skrip Anda
• Memperbarui templat Liquid Anda untuk skrip
• Skrip Shopify