Shopify指令碼API參考

此頁面列印時間為2023年4月10日。如須最新版本，請至https://help.shopify.com/zh-TW/manual/checkout-settings/script-editor/shopify-scripts。

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

指令碼有幾種不同類型。在脚本编辑器应用中建立指令碼時,系統會根據您選擇開始建立的指令碼範本,為指令碼指派一個類型:

商品項目指令碼

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

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

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

運送指令碼

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

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

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

付款指令碼

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

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

通用方法

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

輸入

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

購物車

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

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

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

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

CartDiscount: FixedAmount

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

CartDiscount:百分比

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

CartDiscount:航运

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

客戶

指令碼的方式使用顧客對象
方法 傳回類型 說明
.id 整数 傳回客戶的id編號。
.email 字符串 傳回客戶的電子郵件地址。
.tags 列表<标记> 傳回代表針對某客戶所設定任何標籤的字串清單。
.orders_count 整数 傳回某客戶送出的訂單總數。
.total_spent 钱 傳回客戶對所有訂單消費的總金額。
.accepts_ob欧宝娱乐app下载地址marketing吗? 布林值 傳回客戶是否接受行銷。

LineItem

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

清單

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

傳回位於指定索引的元素。
强生的 清單

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

若清單中無任何元素則傳回真正的。
中国当代 元素或nil

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

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

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

傳回最後一個元素，若清單空白則傳回零。
长处 int

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

長度的別名。
each (* args,室) 清單

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

運送地址

指令碼的方式使用ShippingAddress物件
方法 傳回類型 說明
. name 字串 傳回與運送地址相關聯的人員名字。
.address1 字串 傳回運送地址中的街道地址部分。
.address2 字串 傳回運送地址中街道地址部分的其他選填欄位。
.phone 字串 傳回運送地址的電話。
.city 字串 傳回運送地址中的城市。
. zip 字串 傳回運送地址的郵遞區號。
.province 字串 傳回運送地址中的省/州別。
.province_code 字串 傳回運送地址中省/州別的縮寫值。
.country_code 字串 傳回運送地址中國家/地區的縮寫值。

钱

指令碼的方式使用钱物件
方法 傳回類型 說明
.derived_from_presentment (customer_cents:X） 钱 將金額從客戶的當地 (出示) 貨幣轉換為您商店的貨幣 (單位為美分)。此方式接受customer_cents參數，該參數接受以美分為單位的數字。例如，Money.derived_from_presentment (customer_cents: 500)。
格式 钱 建立新物件以代表價格。
.zero 钱

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

金钱範例

钱．新（分:1000）

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

钱．新（分:One hundred.）＊50

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

變體

指令碼的方式使用變體物件
方法 傳回類型 說明
.id 整数 傳回變數的id編號。
.price 钱 傳回子類的單價。
. product 產品 傳回與子類相關聯的商品。
.skus 列表<字符串> 傳回子類的存貨單位(sku)，通常用於追蹤庫存。
.title 字符串 傳回子類的標題。

產品

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

内核

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

指令碼的方式使用核心物件
方法 傳回類型 說明
.exit 無 結束執行目前指令碼且無錯誤。若在為Output.cart指派任何項目之前執行此方法，則指令碼會無效。在客戶無資格執行指令碼等情況下，這是結束指令碼的實用方法。

内核範例

客户＝输入．车．客户如果客户& &客户．电子邮件．end_with吗?（“@mycompany.com”）#员工没有资格获得这次晋升。退出结束

商品項目方法

以下方法適用於商品項目方指令碼：

購物車

使用商品項目指令碼中的購物車物件的指令碼方法
方法 傳回類型 說明
.subtotal_price_was 钱 傳回套用任何折扣前的購物車小計金額。
.subtotal_price_changed吗? 布林值 傳回小計金額是否變更。

LineItem

指令碼的方式使用商品項目指令碼中的明細項目物件
方法 傳回類型 說明
.change_line_price (钱New_price，{消息:字符串}) 钱 將商品項目價格變更為指定的金額。需要一個消息物件。new_price必須低於目前價格。
.original_line_price 钱 傳回套用指令碼和折扣前的商品項目原始價格。
.line_price_was 钱 傳回由目前的指令碼套用變更之前的商品項目價格。
.line_price_changed吗? 布林值 傳回商品項目價格是否變更。
.change_properties (哈希New_properties，{消息:字符串}) 哈希 為商品項目設定新屬性。原始屬性雜湊會儲存在properties_was中，而傳送至此方法的屬性雜湊會成為商品項目的新屬性。
.properties_was 哈希 傳回套用任何變更前的商品項目原始屬性雜湊。
.properties_changed吗? 布林值 傳回商品項目屬性是否變更。
.split ({:整数}) LineItem 將一個商品項目分割為兩個商品項目。取指定從原始商品項目移除以建立新商品項目的數量。

.split例子

此範例指令碼會將稱為original_line_item的商品項目分割為兩個商品項目。新的商品項目數量為 1 (由带:1指定)。指定碼接著會將折扣價格套用於新商品項目，並包括「第三頂帽子 5 美元」的訊息。

如果original_line_item．数量＞＝3.new_line_item＝original_line_item．分裂（花:1）new_line_item．change_line_price（钱．新（分:500)，信息:“第三顶帽子5美元”）车．line_items<<new_line_item结束

變體

指令碼的方式使用商品項目指令碼中的子類物件
方法 傳回類型 說明
.compare_at_price 钱 傳回子類選項的售價。若子類選項沒有售價，則傳回零。

運送方式

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

輸入

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

ShippingRateList

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

ShippingRate

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

付款方式

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

輸入

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

PaymentGatewayList

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

PaymentGateway

方法 傳回類型 說明
. name 字符串 傳回付款閘道的名稱。
.enabled_card_brands 列表<字符串>

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

範例

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

customer = Input.cart.customerInput.cart.line_items。Eachdo |line_item| product = line_item.variant。line_item.change_line_price(line_item. change_line_price)line_price -钱。新（分:900), message: customer.total_spent)end Output.cart= Input.cart

深入瞭解

深入瞭解：

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

免費試用