Rujukan API Skrip Shopify

Skrip ditulis menggunakan API Ruby yang memberikan anda tahap kawalan dan fleksibiliti yang tinggi.

Terdapat pelbagai jenis skrip. Sesuatu skrip diperuntukkan jenisnya apabila anda mencipta skrip tersebut dalam aplikasi Script Editor, berdasarkan templat skrip yang anda pilih untuk bermula:

Skrip item baris

Skrip item baris mempengaruhi item baris di dalam troli dan boleh mengubah harga serta memberikan diskaun. Skrip ini dijalankan apabila perubahan dibuat pada troli.

Skrip item baris yang memberikan diskaun kepada langganan terpakai pada pembayaran pertama langganan sahaja. Pembayaran seterusnya tidak didiskaunkan oleh skrip.

Sesetengah kaedah hanya boleh digunakan dalam skrip item baris.

Skrip pengiriman

Skrip pengiriman berinteraksi dengan pengiriman, serta boleh mengubah kaedah pengiriman dan memberikan diskaun untuk kadar pengiriman. Skrip ini dijalankan apabila pembayaran sampai ke halaman pilihan pengiriman.

Skrip pengiriman yang memberikan diskaun untuk kadar pengiriman langganan terpakai pada pembayaran pertama langganan sahaja. Pembayaran seterusnya tidak didiskaunkan 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 boleh menamakan semula, menyembunyikan serta menyusun semula gerbang pembayaran. Ambil perhatian bahawa skrip pembayaran tidak berinteraksi dengan gerbang pembayaran yang ditunjukkan sebelum skrin pembayaran, seperti Apple Pay. Skrip ini dijalankan apabila pembayaran sampai ke halaman pembayaran.

Sesetengah kaedah hanya boleh digunakan dalam skrip pembayaran.

Pada halaman ini

Kaedah am

Kaedah berikut boleh digunakan dalam mana-mana jenis skrip:

Input

Kaedah input skrip
Kaedah	Jenis pulangan	Penerangan
.cart	Troli	Mengembalikan objek troli boleh ubah.
.locale	rentetan	Mengembalikan penempatan pelanggan. Sebagai contoh, `en`, `fr` atau `pt-BR`.

Troli

Objek troli hanya tersedia pada kedai dalam talian. Beberapa pembayaran yang ditinggalkan mempunyai akses kepada objek troli. Walau bagaimanapun, jika pembayaran telah ditutup dan kemudian pelanggan melawat pembayaran yang ditinggalkan itu, ini akan menghantar mereka ke pembayaran yang dipraisi dan objek troli tidak wujud lagi. Hal ini berlaku kerana laman kedai telah dipintas oleh e-mel pembayaran yang ditinggalkan.

Kaedah Jenis pulangan Penerangan

.customer Pelanggan Mengembalikan pemilik troli (jika ada).

.shipping_address ShippingAddress Mengembalikan alamat penghantaran pemilik troli (jika ada).

.discount_code

berbeza-beza

Kaedah skrip menggunakan objek Troli
Kaedah	Jenis pulangan	Penerangan
.customer	Pelanggan	Mengembalikan pemilik troli (jika ada).
.shipping_address	ShippingAddress	Mengembalikan alamat penghantaran pemilik troli (jika ada).
.discount_code	berbeza-beza	Mengembalikan: `nil` jika troli tiada kod diskaun `CartDiscount::FixedAmount` jika troli mempunyai jumlah diskaun tetap `CartDiscount::Percentage` jika troli mempunyai diskaun peratusan `CartDiscount::Shipping` jika troli mempunyai diskaun pengiriman Mengembalikan satu kod diskaun (lihat Had) `discount_code` akan wujud jika diskaun telah digunakan pada troli. Ini tidak semestinya bermaksud harga troli tersebut berubah. Sebagai contoh, jika diskaun terpakai pada troli yang bernilai lebih $50 dan skrip mengurangkan harga troli di bawah $50, `discount_code` masih ada tetapi harga troli 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><LineItem></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><String></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>

Mengembalikan:

nil jika troli tiada kod diskaun
CartDiscount::FixedAmount jika troli mempunyai jumlah diskaun tetap
CartDiscount::Percentage jika troli mempunyai diskaun peratusan
CartDiscount::Shipping jika troli mempunyai diskaun pengiriman
Mengembalikan satu kod diskaun (lihat Had)

discount_code akan wujud jika diskaun telah digunakan pada troli. Ini tidak semestinya bermaksud harga troli tersebut berubah. Sebagai contoh, jika diskaun terpakai pada troli yang bernilai lebih $50 dan skrip mengurangkan harga troli di bawah $50, discount_code masih ada tetapi harga troli 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

Kaedah skrip menggunakan objek CartDiscount::FixedAmount
Kaedah	Jenis pulangan	Penerangan
.code	Rentetan	Mengembalikan kod diskaun yang digunakan untuk mengenakan diskaun.
.amount	Wang	Mengembalikan jumlah wang bagi diskaun tersebut.
.reject({ message: String })	nil	Menolak kod diskaun yang dikenakan pada troli. `message` diwajibkan.
.rejected?	Boolean	Mengembalikan sama ada kod diskaun tersebut telah ditolak.

CartDiscount::Percentage

Kaedah skrip menggunakan objek CartDiscount::Percentage
Kaedah	Jenis pulangan	Penerangan
.code	Rentetan	Mengembalikan kod diskaun yang digunakan untuk mengenakan diskaun.
.percentage	Perpuluhan	Mengembalikan jumlah peratusan bagi diskaun tersebut.
.reject({ message: String })	nil	Menolak kod diskaun yang dikenakan pada troli. `message` diwajibkan.
.rejected?	Boolean	Mengembalikan sama ada kod diskaun tersebut telah ditolak.

CartDiscount::Shipping

Kaedah skrip menggunakan objek CartDiscount::Shipping
Kaedah	Jenis pulangan	Penerangan
.code	Rentetan	Mengembalikan kod diskaun yang digunakan untuk mengenakan diskaun.
.reject({ message: String })	nil	Menolak kod diskaun yang dikenakan pada troli. `message` diwajibkan.
.rejected?	Boolean	Mengembalikan sama ada kod diskaun tersebut telah ditolak.

Pelanggan

Kaedah skrip menggunakan objek Pelanggan
Kaedah	Jenis pulangan	Penerangan
.id	Integer	Mengembalikan nombor ID pelanggan.
.email	Rentetan	Mengembalikan alamat e-mel pelanggan.
.tags	Senarai<Tag>	Mengembalikan senarai rentetan yang mewakili sebarang tag yang ditetapkan untuk pelanggan.
.orders_count	Integer	Mengembalikan jumlah pesanan yang telah dibuat oleh pelanggan.
.total_spent	Wang	Mengembalikan jumlah keseluruhan yang telah dibelanjakan pelanggan pada semua pesanan.
.accepts_marketing?	Boolean	Mengembalikan sama ada pelanggan menerima pemasaran.

LineItem

Kaedah skrip menggunakan objek LineItem
Kaedah	Jenis pulangan	Penerangan
.grams	grams	Mengembalikan jumlah berat item baris.
.line_price	Wang	Harga item baris.
.discounted?	Boolean	Mengembalikan sama ada harga item baris telah dikenakan diskaun oleh skrip atau diskaun yang digunakan secara manual. Penggunaan kod diskaun tidak mempengaruhi nilai pulangan.
.properties	hash	Mengembalikan sifat yang ditentukan untuk item baris ini.
.variant	Variant	Mengembalikan varian produk khusus yang diwakili oleh item baris.
.quantity	Integer	Mengembalikan kuantiti item baris ini.
.selling_plan_id	Integer	Mengembalikan ID pelan jualan untuk item baris. Kaedah ini berguna apabila kedai menjual langganan dan anda mahukan skrip untuk mengesan waktu varian produk dijual sebagai langganan.

List

Kaedah skrip menggunakan objek List
Kaedah	Jenis pulangan	Penerangan
.new	List	Mencipta objek baharu untuk mewakili senarai.
.[]	Elemen atau nil	Mengembalikan elemen pada indeks yang ditentukan.
.&	List	Mengembalikan senarai baharu yang mengandungi elemen umum kepada kedua-dua senarai tanpa pendua.
.delete_if	List	Padamkan elemen menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `delete_if` Ruby.
.empty?	Boolean	Mengembalikan `true` jika senarai tidak mengandungi elemen.
.first	Elemen atau nil	Mengembalikan elemen pertama atau `nil` jika senarai kosong.
.index(*args, &block)	int atau nil	Mengembalikan indeks bagi elemen pertama dalam senarai. Jika blok diberikan bagi menggantikan hujah, ia mengembalikan indeks bagi elemen pertama yang mana blok tersebut adalah true.
.rindex(*args, &block)	int atau nil	Mengembalikan indeks elemen terakhir senarai. Jika blok diberikan bagi menggantikan hujah, ia mengembalikan indeks bagi elemen pertama yang mana blok tersebut adalah true.
.last	Elemen atau nil	Mengembalikan elemen terakhir atau `nil` jika senarai kosong.
.length	int	Mengembalikan bilangan elemen dalam senarai.
.size	int	Alias untuk length.
.each(*args, &block)	List	Memanggil blok sekali untuk setiap elemen dalam senarai dan menyerahkan elemen sebagai parameter kepada blok.

ShippingAddress

Kaedah skrip menggunakan objek ShippingAddress
Kaedah	Jenis pulangan	Penerangan
.name	rentetan	Mengembalikan nama orang yang dikaitkan dengan alamat penghantaran.
.address1	rentetan	Mengembalikan bahagian alamat jalan bagi alamat penghantaran.
.address2	rentetan	Mengembalikan medan tambahan pilihan pada bahagian alamat jalan bagi alamat penghantaran.
.phone	rentetan	Mengembalikan nombor telefon alamat penghantaran.
.city	rentetan	Mengembalikan bandar alamat penghantaran.
.zip	rentetan	Mengembalikan kod ZIP alamat penghantaran.
.province	rentetan	Mengembalikan wilayah/negeri alamat penghantaran.
.province_code	rentetan	Mengembalikan nilai singkatan bagi wilayah/negeri alamat penghantaran.
.country_code	rentetan	Mengembalikan nilai singkatan bagi negara alamat penghantaran.

Money

Kaedah skrip menggunakan objek Money
Kaedah	Jenis pulangan	Penerangan
.derived_from_presentment(customer_cents:X)	Wang	Menukar amaun (dalam sen) daripada mata wang tempatan pelanggan (mata wang yang dipaparkan) kepada mata wang kedai anda. Kaedah ini menerima parameter `customer_cents` yang menerima nombor dalam sen. Contohnya, `Money.derived_from_presentment(customer_cents: 500)`.
.new	Wang	Mencipta objek baharu untuk mewakili harga.
.zero	Wang	Mencipta objek baharu dengan harga sifar.
+	Wang	Menambahkan dua objek `Money`.
-	Wang	Menolak satu objek `Money` daripada yang lain.
*	Wang	Mendarabkan objek `Money` dengan nombor.

Contoh Money

Money.new(cents: 1000)

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

Money.new(cents: 100) * 50

Mencipta objek Money yang mewakili $1, kemudian mendarabkan jumlah tersebut dengan 50. Mengembalikan objek Money yang mewakili $50.

Varian

Kaedah skrip menggunakan objek Varian
Kaedah	Jenis pulangan	Penerangan
.id	Integer	Mengembalikan nombor ID varian.
.price	Wang	Mengembalikan harga seunit varian.
.product	Produk	Mengembalikan produk yang dikaitkan dengan varian.
.skus	Senarai<Rentetan>	Mengembalikan unit penyimpanan stok (SKU) varian, yang sering digunakan untuk menjejak inventori.
.title	Rentetan	Mengembalikan tajuk varian.

Produk

Kaedah skrip menggunakan objek Produk
Kaedah	Jenis pulangan	Penerangan
.id	Integer	Mengembalikan nombor ID produk.
.gift_card?	Boolean	Mengembalikan sama ada produk ialah kad hadiah.
.tags	Senarai<Tag>	Mengembalikan senarai rentetan yang mewakili tag yang ditetapkan untuk produk ini.
.product_type	Rentetan	Pengkategorian yang boleh ditagkan pada produk, biasanya digunakan untuk menapis dan mencari.
.vendor	Rentetan	Mengembalikan vendor bagi produk ini.

Kernel

Kernel ialah modul Ruby yang disertakan dalam setiap kelas. Akibatnya, kaedahnya tersedia untuk setiap objek. Kaedah ini bertindak dengan cara yang sama seperti fungsi global bertindak dalam bahasa lain.

Kaedah skrip menggunakan objek Kernel
Kaedah	Jenis pulangan	Penerangan
.exit	tiada	Menamatkan pelaksanaan skrip semasa tanpa ralat. Jika ini dijalankan sebelum apa-apa diperuntukkan kepada `Output.cart`, skrip tiada kesan. Ini ialah cara yang berguna untuk keluar dari skrip, contohnya, jika pelanggan tidak layak 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

Kaedah item baris

Kaedah yang berikut hanya boleh digunakan dalam skrip item baris:

Troli

Kaedah skrip menggunakan objek Troli dalam skrip item baris
Kaedah	Jenis pulangan	Penerangan
.subtotal_price_was	Wang	Mengembalikan harga subjumlah troli sebelum sebarang diskaun digunakan.
.subtotal_price_changed?	Boolean	Mengembalikan sama ada harga subjumlah telah berubah.

LineItem

Kaedah skrip menggunakan objek LineItem dalam skrip item baris
Kaedah	Jenis pulangan	Penerangan
.change_line_price(Money new_price, { message: String })	Wang	Tukar harga item baris kepada jumlah yang ditentukan. `message` diperlukan. `new_price` mestilah lebih rendah daripada harga semasa.
.original_line_price	Wang	Mengembalikan harga asal item baris sebelum skrip dan diskaun digunakan.
.line_price_was	Wang	Mengembalikan harga item baris sebelum perubahan digunakan oleh skrip semasa.
.line_price_changed?	Boolean	Mengembalikan sama ada harga item baris telah berubah.
.change_properties(hash new_properties, { message: String })	hash	Menetapkan sifat baharu untuk item baris. Hash sifat asal disimpan dalam `properties_was` dan hash sifat yang diserahkan kepada kaedah tersebut menjadi sifat baharu untuk item baris tersebut.
.properties_was	hash	Mengembalikan hash sifat asal item baris sebelum sebarang perubahan digunakan.
.properties_changed?	Boolean	Mengembalikan sama ada sifat untuk item baris telah diubah.
.split({ take: Integer })	LineItem	Memisahkan item baris kepada dua item baris. `take` menentukan kuantiti yang perlu dikeluarkan daripada item baris asal untuk mencipta item baris baharu.

Contoh .split

Skrip contoh ini memisahkan item baris yang dipanggil original_line_item kepada dua item baris. Item baris baharu itu mempunyai kuantiti 1 (ditentukan oleh take: 1). Skrip kemudian menggunakan harga diskaun pada item baris baharu dengan mesej "Topi ketiga untuk 5 dolar".

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

Kaedah skrip menggunakan objek Varian dalam skrip item baris
Kaedah	Jenis pulangan	Penerangan
.compare_at_price	Wang	Mengembalikan harga bandingkan varian. Mengembalikan `nil` jika varian tidak mempunyai harga bandingkan.

Kaedah pengiriman

Kaedah yang berikut boleh digunakan dalam skrip pengiriman:

Input

Kaedah skrip menggunakan objek Input dalam skrip pengiriman
Kaedah	Jenis pulangan	Penerangan
.shipping_rates	ShippingRateList	Mengembalikan senarai semua kadar pengiriman.

ShippingRateList

Kaedah skrip menggunakan objek ShippingRateList dalam skrip pengiriman
Kaedah	Jenis pulangan	Penerangan
.delete_if	ShippingRateList	Padamkan kadar pengiriman menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `delete_if` Ruby.
.sort!	ShippingRateList	Susun kadar pengiriman menggunakan operator perbandingan atau menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `sort!` Ruby.
.sort_by!	ShippingRateList	Susun kadar pengiriman menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `sort_by!` Ruby.

ShippingRate

Kaedah skrip menggunakan objek ShippingRate dalam skrip pengiriman
Kaedah	Jenis pulangan	Penerangan
.code	Rentetan	Mengembalikan kod kadar pengiriman.
.markup	Wang	Mengembalikan markup untuk kadar pengiriman, jika berkenaan.
.name	Rentetan	Mengembalikan nama kadar pengiriman. Nama ini boleh diubah suai dengan menggunakan kaedah `change_name`.
.price	Wang	Mengembalikan harga kadar pengiriman.
.source	Rentetan	Mengembalikan sumber (pengangkut) yang dikaitkan dengan kadar pengiriman, jika relevan. Sumber ini tidak boleh diubah suai.
.change_name(String new_name)	Rentetan	Mengubah nama (maksimum 255 aksara) kadar pengiriman. Sumber ini tidak boleh ditukar, dipadamkan atau disembunyikan.
.apply_discount(Money discount, { message: String })	Wang	Mengenakan diskaun sebanyak amaun tetap yang ditentukan. Harga tidak boleh dikurangkan di bawah 0. Mesej diperlukan.
.phone_required?	Boolean	Mengembalikan `true` jika nombor telefon diperlukan untuk mendapatkan kadar pengiriman, atau `false` jika nombor telefon tidak diperlukan.

Kaedah pembayaran

Kaedah yang berikut boleh digunakan dalam skrip pembayaran:

Input

Kaedah skrip menggunakan objek Input dalam skrip pembayaran
Kaedah	Jenis pulangan	Penerangan
.payment_gateways	PaymentGatewaysList	Mengembalikan senarai semua gerbang pembayaran di kedai.

PaymentGatewayList

Kaedah skrip menggunakan objek PaymentGatewayList dalam skrip pembayaran
Kaedah	Jenis pulangan	Penerangan
.delete_if	PaymentGatewayList	Padamkan gerbang pembayaran menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `delete_if` Ruby.
.sort!	PaymentGatewayList	Isih gerbang pembayaran menggunakan operator perbandingan atau menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `sort!` Ruby.
.sort_by!	PaymentGatewayList	Isih gerbang pembayaran menggunakan blok kod pilihan. Lihat dokumentasi untuk kaedah `sort_by!` Ruby.

PaymentGateway

Kaedah	Jenis pulangan	Penerangan
.name	Rentetan	Mengembalikan nama gerbang pembayaran.
.enabled_card_brands	Senarai<Rentetan>	Jika gerbang pembayaran menyokong kad kredit, mengembalikan senarai jenis kad kredit yang diterima oleh kedai. Jika gerbang tidak menyokong kad kredit, mengembalikan senarai kosong.
.change_name(String new_name)	Rentetan	Mengubah nama gerbang pembayaran. Gerbang pembayaran dengan logo tidak boleh dinamakan semula.

Contoh

Dalam contoh skrip item baris berikut, apabila pelanggan memesan produk yang bukan kad hadiah, harga produk akan dikurangkan sebanyak $9. Selain itu, jumlah amaun yang dibelanjakan oleh pelanggan sepanjang semua lawatan ke kedai anda akan ditunjukkan:

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

Ketahui lebih lanjut

Ketahui lebih lanjut tentang: