Shopify 指令碼 API 參考

指令碼是使用 Ruby API 撰寫，可提供高度的控制與彈性。

方案需求

自 2026 年 6 月 30 日起，Shopify 指令碼已棄用。任何仍在您商店發佈的指令碼皆已停用且無法再運作。若要重新建立這些自訂，請轉移至 Shopify Functions。瞭解從 Shopify 指令碼轉移至 Shopify Functions 的詳情。

指令碼有不同的類型。您在 Script Editor app 建立指令碼時，系統會根據您選擇的指令碼範本指派類型：

商品項目指令碼

商品項目指令碼會影響購物車中的商品項目，能變更價格並發放折扣。當購物車發生變更時，系統會執行這些指令碼。

對訂閱提供折扣的商品項目指令碼只會適用於該訂閱的首次付款。後續付款不會套用該指令碼的折扣。

部分方法僅能用於商品項目指令碼。

運送指令碼

運送指令碼會與運送互動，能變更運送方式並對運費費率發放折扣。當結帳流程進到運送選項頁面時，系統會執行這些指令碼。

對訂閱的運送費率提供折扣的運送指令碼只會適用於該訂閱的首次付款。後續付款不會套用該指令碼的折扣。

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

付款指令碼

付款指令碼會與付款互動，能重新命名、隱藏與重新排序付款閘道。請注意，付款指令碼不會與結帳畫面前顯示的付款閘道互動，例如 Apple Pay。當結帳流程進到付款頁面時，系統會執行這些指令碼。

部分方法僅能用於付款指令碼。

通用方法

以下方法可用於任何類型的指令碼：

輸入

指令碼輸入方法

方法	傳回型別	說明
.cart	購物車	傳回可變動的購物車物件。
.locale	字串	傳回顧客的語言代碼。例如，en、fr 或 pt-BR。

購物車

購物車物件僅適用於網路商店。有些未完成結帳作業可以存取購物車物件。不過，如果結帳已關閉，而顧客再次造訪該未完成結帳作業，系統會將其導向已預先填寫的結帳頁面，購物車物件就不再存在。這是因為未完成結帳作業電子郵件會略過線上店面。

使用購物車物件的指令碼方法

方法	傳回型別	說明
.customer	顧客	傳回購物車擁有者 (若有)。
.shipping_address	運送地址	傳回購物車擁有者的運送地址 (若有)。
.discount_code	視情況而定	傳回： 若購物車沒有折扣代碼，則為 nil 若購物車有固定金額折扣，則為 CartDiscount::FixedAmount 若購物車有百分比折扣，則為 CartDiscount::Percentage 若購物車有運送折扣，則為 CartDiscount::Shipping 傳回單一折扣代碼 (請參閱 Limitations) 當購物車已套用折扣時，discount_code 會存在。這不一定表示購物車的價格會變動。例如，若折扣僅適用於高於 $50 的購物車，而某個腳本將購物車價格降至 $50 以下，discount_code 仍會存在，但購物車的價格不會改變。 <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

使用 CartDiscount::FixedAmount 物件的腳本方法

方法	傳回型別	說明
.code	字串	傳回用來套用折扣的折扣代碼。
.amount	Money	傳回折扣的金額。
.reject({ message: String })	nil	拒絕套用至購物車的折扣代碼。必須提供 message。
.rejected?	布林值	傳回折扣代碼是否遭拒。

CartDiscount::Percentage

使用 CartDiscount::Percentage 物件的腳本方法

方法	傳回型別	說明
.code	字串	傳回用來套用折扣的折扣代碼。
.percentage	小數	傳回折扣的百分比。
.reject({ message: String })	nil	拒絕套用至購物車的折扣代碼。必須提供 message。
.rejected?	布林值	傳回折扣代碼是否遭拒。

CartDiscount::Shipping

使用 CartDiscount::Shipping 物件的指令碼方法

方法	傳回型別	說明
.code	字串	傳回用來套用折扣的折扣代碼。
.reject({ message: String })	nil	拒絕套用至購物車的折扣代碼。必須提供 message。
.rejected?	布林值	傳回折扣代碼是否遭拒。

Customer

使用 Customer 物件的指令碼方法

方法	傳回型別	說明
.id	整數	傳回顧客的 ID 編號。
.email	字串	傳回顧客的電子郵件地址。
.tags	List<Tag>	傳回代表此顧客所有標籤的字串清單。
.orders_count	整數	傳回顧客已建立的訂單總數。
.total_spent	Money	傳回該顧客在所有訂單上的總花費金額。
.accepts_marketing?	布林值	傳回該顧客是否同意接收行銷資訊。

LineItem

使用 LineItem 物件的指令碼方法

方法	傳回型別	說明
.grams	grams	傳回該商品項目的總重量。
.line_price	Money	此商品項目的價格。
.discounted?	布林值	傳回該商品項目的價格是否已被指令碼或手動套用的折扣調降。使用折扣代碼不會影響傳回值。
.properties	雜湊	傳回為此商品項目指定的屬性。
.variant	Variant	傳回此商品項目所代表的特定產品子類選項。
.quantity	整數	傳回此商品項目的數量。
.selling_plan_id	整數	傳回此商品項目的銷售方案 ID。當商店販售訂閱商品，且您希望指令碼偵測商品子類選項是否為 sold as a subscription 時，此方法相當實用。

List

使用 List 物件的指令碼方法

方法	傳回型別	說明
.new	List	建立一個新物件用來代表清單。
.[]	元素或 nil	傳回指定索引處的元素。
.&	List	傳回一個新清單，其中包含兩個清單的共同元素，且不含重複元素。
.delete_if	List	使用選用的程式碼區塊刪除元素。請參閱 Ruby's delete_if method 的說明文件。
.empty?	布林值	若清單沒有任何元素，則傳回 true。
.first	元素或 nil	傳回第一個元素，若清單為空則傳回 nil。
.index(*args, &block)	整數或 nil	傳回清單第一個元素的索引。若以區塊取代引數，則傳回第一個讓該區塊為 true 的元素之索引。
.rindex(*args, &block)	整數或 nil	傳回清單最後一個元素的索引。若以區塊取代引數，則傳回第一個讓該區塊為 true 的元素之索引。
.last	元素或 nil	傳回最後一個元素，若清單為空則傳回 nil。
.length	整數	傳回清單中的元素數目。
.size	整數	為 length 的別名。
.each(*args, &block)	List	對清單中的每個元素各呼叫一次區塊，並將該元素作為參數傳入區塊。

ShippingAddress

使用 ShippingAddress 物件的指令碼方法

方法	傳回型別	說明
.name	字串	傳回運送地址對應的姓名。
.address1	字串	傳回運送地址的街道地址欄位。
.address2	字串	傳回運送地址街道地址的選填附加欄位。
.phone	字串	傳回運送地址的電話號碼。
.city	字串	傳回運送地址的城市。
.zip	字串	傳回運送地址的郵遞區號。
.province	字串	傳回運送地址的省/州。
.province_code	字串	傳回運送地址省/州的縮寫值。
.country_code	字串	傳回運送地址國家/地區的縮寫值。

Money

使用 Money 物件的指令碼方法

方法	傳回型別	說明
.derived_from_presentment(customer_cents:X)	Money	將金額 (單位為分) 從顧客的本地顯示幣別轉換為您的商店幣別。此方法接受 customer_cents 參數，該參數以分為單位輸入數字。例如，Money.derived_from_presentment(customer_cents: 500)。
.new	Money	建立一個新物件來表示價格。
.zero	Money	建立一個價格為 0 的新物件。
+	Money	將兩個 Money 物件相加。
-	Money	從一個 Money 物件中減去另一個。
*	Money	將 Money 物件乘以數字。

Money 範例

Money.new(cents: 1000)

建立一個 Money 物件，代表 1,000 分，或 $10。

Money.new(cents: 100) * 50

建立一個 Money 物件，代表 $1，然後將該金額乘以 50。傳回一個代表 $50 的 Money 物件。

子類

使用子類物件的腳本方法

方法	傳回型別	說明
.id	整數	傳回該子類的 ID 編號。
.price	Money	傳回該子類的單價。
.product	Product	傳回該子類所屬的商品。
.skus	List<String>	傳回該子類的存貨單位 (SKU)，通常用於追蹤庫存。
.title	字串	傳回該子類的標題。

商品

使用商品物件的腳本方法

方法	傳回型別	說明
.id	整數	傳回該商品的 ID 編號。
.gift_card?	布林值	傳回此商品是否為禮品卡。
.tags	List<Tag>	傳回此商品的標籤字串清單。
.product_type	字串	商品可指定的一種分類，常用於篩選與搜尋。
.vendor	字串	傳回此商品的廠商。

Kernel

Kernel 是一個 Ruby 模組，包含於每個類別。因此，其方法可供每個物件使用。這些方法的作用類似其他語言中的全域函式。

使用 Kernel 物件的腳本方法

方法	傳回型別	說明
.exit	無	在不產生錯誤的情況下結束目前腳本的執行。若在指派任何內容給 Output.cart 之前執行，腳本不會產生任何效果。這是結束腳本的實用方式，例如當顧客不符合執行腳本的條件時。

Kernel 範例

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

商品項目方法

以下方法僅可用於商品項目腳本：

購物車

在商品項目腳本中使用購物車物件的方法

方法	傳回型別	說明
.subtotal_price_was	Money	傳回購物車在套用任何折扣前的小計金額。
.subtotal_price_changed?	布林值	傳回小計金額是否已變更。

LineItem

在商品項目腳本中使用商品項目物件的方法

方法	傳回型別	說明
.change_line_price(Money new_price, { message: String })	Money	將商品項目的價格變更為指定金額。必須提供 message。new_price 必須低於目前價格。
.original_line_price	Money	傳回套用腳本與折扣前，商品項目的原始價格。
.line_price_was	Money	傳回目前腳本套用變更前的商品項目價格。
.line_price_changed?	布林值	傳回商品項目的價格是否已變更。
.change_properties(hash new_properties, { message: String })	雜湊	為商品項目設定新的屬性。原始屬性雜湊會儲存在 properties_was 中，而傳入此方法的屬性雜湊會成為商品項目的新屬性。
.properties_was	雜湊	傳回套用任何變更前，商品項目的原始屬性雜湊。
.properties_changed?	布林值	傳回商品項目的屬性是否已變更。
.split({ take: Integer })	LineItem	將一個商品項目拆分為兩個商品項目。take 指定要從原始商品項目移除的數量，以建立新的商品項目。

.split 範例

此範例腳本會將名為 original_line_item 的商品項目拆分為兩個商品項目。新的商品項目數量為 1 (由 take: 1 指定)。接著腳本會對新的商品項目套用折扣價格，並顯示訊息「第三頂帽子 $5」。

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

子類

在商品項目腳本中使用子類物件的方法

方法	傳回型別	說明
.compare_at_price	Money	傳回該子類的原價。若該子類沒有原價，則傳回 nil。

運送方式

以下方法可用於運送腳本：

輸入

在運送腳本中使用 Input 物件的方法

方法	傳回型別	說明
.shipping_rates	ShippingRateList	傳回所有運費費率的清單。

ShippingRateList

在運送指令碼中可使用的 ShippingRateList 物件方法

方法	傳回型別	說明
.delete_if	ShippingRateList	使用選用的程式碼區塊刪除運費費率。請參閱 Ruby's delete_if method 的說明文件。
.sort!	ShippingRateList	使用比較運算子或選用的程式碼區塊來排序運費費率。請參閱 Ruby's sort! method 的說明文件。
.sort_by!	ShippingRateList	使用選用的程式碼區塊來排序運費費率。請參閱 Ruby's sort_by! method 的說明文件。

ShippingRate

在運送指令碼中可使用的 ShippingRate 物件方法

方法	傳回型別	說明
.code	字串	傳回運費費率的代碼。
.markup	Money	如適用，傳回此運費費率的加成。
.name	字串	傳回運費費率的名稱。可使用 change_name 方法加以修改。
.price	Money	傳回運費費率的金額。
.source	字串	如適用，傳回與該運費費率相關聯的來源 (貨運業者)。無法修改。
.change_name(String new_name)	字串	變更運費費率的名稱 (最多 255 個字元)。無法變更、刪除或隱藏來源。
.apply_discount(Money discount, { message: String })	Money	套用指定的固定金額折扣。金額不可低於 0。必須提供訊息。
.phone_required?	布林值	如果需要電話號碼才能取得運費費率，則傳回 true；若不需要，則傳回 false。

付款方法

以下方法可用於付款指令碼：

輸入

在付款指令碼中可使用的 Input 物件方法

方法	傳回型別	說明
.payment_gateways	PaymentGatewaysList	傳回商店中所有付款閘道的清單。

PaymentGatewayList

在付款指令碼中可使用的 PaymentGatewayList 物件方法

方法	傳回型別	說明
.delete_if	PaymentGatewayList	使用選用的程式碼區塊刪除付款閘道。請參閱 Ruby's delete_if method 的說明文件。
.sort!	PaymentGatewayList	使用比較運算子或選用的程式碼區塊來排序付款閘道。請參閱 Ruby's sort! method 的說明文件。
.sort_by!	PaymentGatewayList	使用選用的程式碼區塊來排序付款閘道。請參閱 Ruby's sort_by! method 的說明文件。

PaymentGateway

方法	傳回型別	說明
.name	字串	傳回付款閘道的名稱。
.enabled_card_brands	List<String>	若該付款閘道支援信用卡，則傳回商店可接受的信用卡種類清單。若不支援信用卡，則傳回空的清單。
.change_name(String new_name)	字串	變更付款閘道的名稱。具有標誌的付款閘道無法重新命名。

範例

在以下商品項目指令碼範例中，當顧客訂購的商品不是禮品卡時，該商品的價格會減少 9 美元。另外，還會顯示該顧客在您商店所有造訪的累計消費金額：

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

瞭解詳情

進一步瞭解：

• The basics of Ruby
• Creating scripts
• Testing and debugging your scripts
• Updating your Liquid templates for scripts
• Shopify Scripts