Shopify 指令碼 API 參考

指令碼是以 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? Boolean 傳回折扣碼是否遭拒。

CartDiscount::Percentage

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

CartDiscount::Shipping

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

客戶

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

LineItem

< td公克數
指令碼的方式使用明細項目物件
方法 傳回類型 說明
.grams 傳回商品項目的總重量。
.line_price Money 商品項目的價格。
.discounted? Boolean 傳回折扣是否變更了商品項目的價格。
.properties hash 傳回為此商品項目指定的屬性。
.variant 變體 傳回此商品項目代表的指定商品子類選項。
.quantity Integer 傳回此商品項目的數量。

清單

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

傳回位於指定索引的元素。

.& 清單

傳回包含兩個清單間共同元素的新清單,不含重複項目。

.empty? Boolean

若清單中無任何元素則傳回 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? Boolean 傳回商品是否為禮品卡。
.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? Boolean 傳回小計金額是否變更。

LineItem

指令碼的方式使用商品項目指令碼中的明細項目物件
方法 傳回類型 說明
.change_line_price(Money new_price, { message: String }) Money 將商品項目價格變更為指定的金額。需要一個 message 物件。new_price 必須低於目前價格。
.original_line_price Money 傳回套用指令碼和折扣前的商品項目原始價格。
.line_price_was Money 傳回由目前的指令碼套用變更之前的商品項目價格。
.line_price_changed? Boolean 傳回商品項目價格是否變更。
.change_properties(hash new_properties, { message: String }) hash 為商品項目設定新屬性。原始屬性雜湊會儲存在 properties_was 中,而傳送至此方法的屬性雜湊會成為商品項目的新屬性。
.properties_was hash 傳回套用任何變更前的商品項目原始屬性雜湊。
.properties_changed? Boolean 傳回商品項目屬性是否變更。
.split({ take: Integer }) LineItem 將一個商品項目分割為兩個商品項目。take 指定從原始商品項目移除以建立新商品項目的數量。

.split example

此範例指令碼會將稱為 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 String 傳回運費說明的標記。
.name String 傳回運費的名稱。
.price Money 傳回運費的金額。
.source String 傳回與運費相關聯的來源 (貨運業者)。
.change_name(String new_name, { message: String }) String 變更運費的名稱 (上限 255 個字元)。需要一個 message 物件。
.apply_discount(Money discount, { message: String }) Money 套用指定固定金額的折扣。折扣後的金額不能低於 0。需要一個 message 物件。
.phone_required? Boolean 若需要電話號碼才能取得運費,則傳回 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 銷售商品了嗎?

免費試用