Shopify 指令碼 API 參考

此頁面列印時間為 Sep 09, 2024。如須最新版本，請至 https://help.shopify.com/zh-TW/manual/checkout-settings/script-editor/shopify-scripts。

指令碼是以 Ruby API 編寫而成，具備優異的控制性和彈性。

指令碼有幾種不同類型。在 Script Editor App 中建立指令碼時，系統會根據您選擇開始建立的指令碼範本，為指令碼指派一個類型：

商品項目指令碼

商品項目指令碼會影響購物車中的商品項目，且可變更價格和提供折扣。當購物車內容有所變更，這類指令碼就會執行。

提供訂閱折扣的商品項目指令碼僅會套用於該訂閱的第一筆付款。該指令碼不會為後續的付款提供折扣。

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

運送指令碼

運送指令碼會與運送作業互動，且可變更運送方式和提供運費費率折扣。當結帳流程進入運送選項頁面時，系統就會執行這類指令碼。

提供運費折扣的運送指令碼僅會套用至該訂閱的第一筆付款。該指令碼不會為後續的付款提供折扣。

部分方法只能用於運送指令碼。

付款指令碼

付款指令碼會與付款作業互動，且可重新命名、隱藏和重新排序付款閘道。請注意，付款指令碼不會與進入結帳畫面之前顯示的付款閘道 (例如 Apple Pay) 互動。當結帳流程進入付款頁面時，這類指令碼就會執行。

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

此頁面上

通用方法

下列方法適用於任何類型的指令碼：

輸入

輸入指令碼的方式
方法 傳回類型 說明
.cart 購物車 傳回可變動的 cart 物件。
.locale 字串 返回客戶的語言設定。例如：en (英文)、fr (法文) 或 pt-BR (葡萄牙文-巴西)。

購物車

購物車物件僅適用於線上商店。某些未完成的結帳作業可存取購物車物件。但是，若結帳關閉後有客戶造訪未完成的結帳作業，系統會將客戶引導至預先填入的結帳作業，而購物車物件將不再存在。這是因為未完成結帳作業電子郵件已繞過店面。

使用購物車物件的指令碼方法
方法 傳回類型 說明
.customer 客戶 傳回購物車的擁有者 (若有)。
.shipping_address 運送地址 傳回運送購物車擁有者的運送地址 (若有)。
.discount_code 不定 傳回內容：

若折扣已套用至購物車，則會顯示 discount_code。這不一定代表購物車的價格改變。例如，若折扣套用至滿 $50 美元的購物車，且指令碼減少低於 $50 美元的購物車金額，則 discount_code 仍會顯示，但購物車金額不會改變。

請參閱 discount_code 的範例。
.line_items List<LineItem> 傳回購物車中包含該商品項目的清單。
.presentment_currency List<String> 傳回顧客的當地 (呈現) 幣別 (格式為 ISO 4217)。例如 USD。
.subtotal_price Money 傳回已套用商品項目折扣但尚未套用折扣碼的購物車小計金額。
.total_weight grams 傳回購物車中所有商品項目的總重量。

CartDiscount::FixedAmount

指令碼的方式使用 Cartdiscount 物件
方法 傳回類型 說明
.code String 傳回用來套用折扣的折扣碼。
.amount Money 傳回折扣的金額。
.reject({ message: String }) nil 拒絕套用至購物車的折扣碼，需要一個 message 物件。
.rejected? 布林值 傳回折扣碼是否遭拒。

CartDiscount::Percentage

指令碼的方式使用 Cartdiscount 物件
方法 傳回類型 說明
.code String 傳回用來套用折扣的折扣碼。
.percentage 小數點 傳回折扣的百分比金額。
.reject({ message: String }) nil 拒絕套用至購物車的折扣碼，需要一個 message 物件。
.rejected? 布林值 傳回折扣碼是否遭拒。

CartDiscount::Shipping

指令碼的方式使用 Cartdiscount 物件
方法 傳回類型 說明
.code String 傳回用來套用折扣的折扣碼。
.reject({ message: String }) nil 拒絕套用至購物車的折扣碼，需要一個 message 物件。
.rejected? 布林值 傳回折扣碼是否遭拒。

客戶

指令碼的方式使用顧客對象
方法 傳回類型 說明
.id Integer 傳回客戶的 ID 編號。
.email String 傳回客戶的電子郵件地址。
.tags List<Tag> 傳回代表針對某客戶所設定任何標籤的字串清單。
.orders_count Integer 傳回某客戶送出的訂單總數。
.total_spent Money 傳回客戶對所有訂單消費的總金額。
.accepts_marketing? 布林值 傳回客戶是否接受行銷。

LineItem

<td 公克數
指令碼的方式使用明細項目物件
方法 傳回類型 說明
.grams 傳回商品項目的總重量。
.line_price Money 商品項目的價格。
.discounted? 布林值 傳回商品項目價格是否因指令碼或手動套用折扣而經過折扣。使用折扣代碼不會影響退貨價值。
.properties hash 傳回為此商品項目指定的屬性。
.variant 變體 傳回此商品項目代表的指定產品子類。
.quantity Integer 傳回此商品項目的數量。
.selling_plan_id Integer 回傳商品項目的銷售方案 ID。若此商店販售訂閱產品且想要運用指令碼偵測產品子類是否以訂閱制方式售出，則可採用此方法。

清單

指令碼的方式使用清單物件
方法 傳回類型 說明
.new 清單 建立新物件以代表清單。
.[] Element 或 nil

傳回位於指定索引的元素。
.& 清單

傳回包含兩個清單間共同元素的新清單，不含重複項目。
.delete_if 清單 使用選用的程式碼區塊刪除元素。請參閱 Ruby 的 delete_if 方法說明文件。
.empty? 布林值

若清單中無任何元素則傳回 true。
.first Element 或 nil

傳回第一個元素，若清單空白則傳回 nil。
.index(*args, &block) int 或 nil

傳回清單中第一個元素的索引。如果給定一個區塊而非引數，則傳回第一個區塊為 true 的元素之索引。
.rindex(*args, &block) int 或 nil

傳回清單中最後一個元素的索引。如果給定一個區塊而非引數，則傳回第一個區塊為 true 的元素之索引。
.last Element 或 nil

傳回最後一個元素，若清單空白則傳回 nil。
.length int

傳回清單中的元素數量。
.size int

長度的別名。
.each(*args, &block) 清單

為清單中每個元素呼叫一次某個區塊，將元素作為參數傳送至該區塊。

運送地址

指令碼的方式使用 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

建立價格為零的新物件。
+ Money 新增兩個 Money 物件。
- Money 兩個 Money 物件相減。
* Money 將某個 Money 物件乘以某數。

Money 範例

Money.new(cents: 1000)

建立一個代表 1000 美分 (10 美元) 的 Money 物件。

Money.new(cents: 100) * 50

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

子類

指令碼的方式使用變體物件
方法 傳回類型 說明
.id Integer 傳回變數的 ID 編號。
.price Money 傳回子類的單價。
.product 產品 傳回與子類相關聯的商品。
.skus List<String> 傳回子類的存貨單位 (SKU)，通常用於追蹤庫存。
.title String 傳回子類的標題。

產品

指令碼的方式使用產品物件
方法 傳回類型 說明
.id Integer 傳回商品的 ID 編號。
.gift_card? 布林值 傳回商品是否為禮品卡。
.tags List<Tag> 傳回代表針對此商品所設定標籤的字串清單。
.product_type String 可用來標記某商品的分類，常用於進行篩選和搜尋。
.vendor String 傳回此商品的廠商。

Kernel

Kernel 是一種 Ruby 模組，包含在每個類別中，因此其方法適用於所有物件。這類方法的作用與其他語言中的全域函數相同。

指令碼的方式使用核心物件
方法 傳回類型 說明
.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 }) hash 為商品項目設定新屬性。原始屬性雜湊會儲存在 properties_was 中，而傳送至此方法的屬性雜湊會成為商品項目的新屬性。
.properties_was hash 傳回套用任何變更前的商品項目原始屬性雜湊。
.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。

運送方式

以下方法適用於運送指令碼：

輸入

指令碼的方式使用您輸入的內容中的物件運送指令碼
方法 傳回類型 說明
.shipping_rates ShippingRateList 傳回所有運費的清單。

ShippingRateList

指令碼的方式使用 ShippingRateList 物件中運送指令碼
方法 傳回類型 說明
.delete_if ShippingRateList 使用選用的程式碼區塊刪除運費。請參閱 Ruby 的 delete_if 方法說明文件。
.sort! ShippingRateList 使用比較運算子或選用的程式碼區塊排序運費。請參閱 Ruby 的 sort! 方法說明文件。
.sort_by! ShippingRateList 使用選用的程式碼區塊排序運費。請參閱 Ruby 的 sort_by! 方法說明文件。

ShippingRate

指令碼的方式使用 ShippingRate 物件中運送指令碼
方法 傳回類型 說明
.code String 傳回運費的代碼。
.markup Money 傳回運費費率加成 (若適用)。
.name String 傳回運費的名稱。您可以用使用 change_name 方法進行修改。
.price Money 傳回運費的金額。
.source String 如有相關，傳回與運費相關聯的來源 (貨運業者)。無法修改。
.change_name(String new_name) String 變更運費的名稱 (上限 255 個字元)。無法變更、刪除或隱藏來源。
.apply_discount(Money discount, { message: String }) Money 套用指定固定金額的折扣。折扣後的金額不能低於 0。需要一個 message 物件。
.phone_required? 布林值 若需要電話號碼才能取得運費，則傳回 true；若不需要電話號碼則傳回 false。

付款方式

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

輸入

使用您輸入的內容物件，付款指令碼中的指令碼方法
方法 傳回類型 說明
.payment_gateways PaymentGatewaysList 傳回商店所有付款閘道的清單。

PaymentGatewayList

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

PaymentGateway

方法 傳回類型 說明
.name String 傳回付款閘道的名稱。
.enabled_card_brands List<String>

如果付款閘道支援信用卡，則傳回商店接受的信用卡類型清單。如果付款閘道不支援信用卡，則傳回空白的清單。
.change_name(String new_name) String 變更付款閘道的名稱。無法重新命名具有標誌的付款閘道。

範例

下列商品項目指令碼範例中，客戶訂購了一個非禮品卡的商品，然後指令碼將該商品的價格減去 9 美元。此外，也顯示該客戶過去在您商店消費累計的總金額。

customer = Input.cart.customerInput.cart.line_items.eachdo |line_item| product = line_item.variant.productnext 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

深入瞭解

深入瞭解：

準備好開始透過 Shopify 銷售商品了嗎？

免費試用