Shopify 脚本 API 参考

脚本是使用 Ruby API 编写的，能实现高度的控制力和灵活性。

Shopify Plus

Shopify 脚本和 Script Editor 应用仅适用于 Shopify Plus 商家。Shopify App Store 中不再支持下载 Script Editor 应用。

2025 年 8 月 28 日，Shopify 脚本将被移除并不再受支持。请在此日期之前将现有脚本迁移到 Shopify Functions。

脚本分为不同类型。在 Script Editor 应用程序中创建脚本时，系统将根据您选择的脚本模板为脚本分配类型：

订单项目脚本

订单项目脚本会影响购物车中的订单项，可以更改价格和给予折扣。此类脚本会在购物车产生变化时运行。

提供订阅折扣的订单项目脚本仅适用第一笔订阅付款。该脚本不会为后续付款提供折扣。

部分方法仅能用于订单项目脚本。

发货脚本

发货脚本是与发货环节交互的，可以更改发货方式并对运费给予折扣。当客户在结账时进入发货选项页面时，会运行此类脚本。

提供订阅运费折扣的发货脚本仅适用第一笔订阅付款。该脚本不会为后续付款提供折扣。

部分方法仅能用于发货脚本。

付款脚本

付款脚本与付款环节交互，可以重命名、隐藏和重新排序付款网关。请注意，付款脚本不会与在结账屏幕之前显示的支付网关交互，例如 Apple Pay。结账到达付款页面时会运行这些脚本。

部分方法仅能用于付款脚本。

通用方法

以下方法适用于任何类型的脚本：

输入

脚本输入方法

方法	返回类型	描述
.cart	购物车	返回可变的 Cart 对象。
.locale	字符串	返回客户的区域设置。例如，en、fr 或 pt-BR。

购物车

Cart 对象仅适用于在线商店。某些弃单可以访问 Cart 对象。但是，如果客户在某一结账关闭后访问此弃单，它则会将客户导向至预先填写的结账处，并且 Cart 对象不再存在。这是因为弃单营销邮件绕过了店面。

使用 Cart 对象的脚本方法

方法	返回类型	描述
.customer	客户	返回购物车的所有者（如果有）。
.shipping_address	发货地址	返回购物车所有者的收货地址（如果有）。
.discount_code	不定	返回： 如果购物车没有折扣码，则返回 0 如果购物车中存在固定折扣金额，则返回 CartDiscount::FixedAmount 如果购物车中有百分比折扣，则返回 CartDiscount::Percentage CartDiscount::Shipping 如果购物车有运费折扣 返回一个折扣码（请参阅 限制） 如果已将折扣应用于购物车，则存在 discount_code。这并不一定意味着购物车的价格发生了更改。例如，如果将折扣应用于价格高于 50 美元的购物车，并且脚本将购物车价格减少至 50 美元以下，则 discount_code 仍然存在，但购物车的价格未发生更改。 查看 discount_code 的示例。
.line_items	List<LineItem>	返回包含购物车中订单项目的列表。
.presentment_currency	List<String>	返回客户的当地（显示）币种（采用 ISO 4217 格式）。例如 USD。
.subtotal_price	金钱	返回应用订单项目折扣之后、应用折扣码之前的购物车小计价格。
.total_weight	grams	返回购物车中所有订单项的总重量。

CartDiscount::FixedAmount

使用 CartDiscount::FixedAmount 对象的脚本方法

方法	返回类型	描述
.code	字符串	返回用于应用折扣的折扣码。
.amount	金钱	退还折扣金额。
.reject({ message: String })	零	拒绝应用于购物车的折扣码。需要一条消息。
.rejected?	布尔	返回折扣码是否被拒绝。

CartDiscount::Percentage

使用 CartDiscount::Percentage 对象的脚本方法

方法	返回类型	描述
.code	字符串	返回用于应用折扣的折扣码。
.percentage	十进制	返回折扣的百分比值。
.reject({ message: String })	零	拒绝应用于购物车的折扣码。需要一条消息。
.rejected?	布尔	返回折扣码是否被拒绝。

CartDiscount::Shipping

使用 CartDiscount::Shipping 对象的脚本方法

方法	返回类型	描述
.code	字符串	返回用于应用折扣的折扣码。
.reject({ message: String })	零	拒绝应用于购物车的折扣码。需要一条消息。
.rejected?	布尔	返回折扣码是否被拒绝。

客户

使用 Customer 对象的脚本方法

方法	返回类型	描述
.id	整数	返回客户的 ID 编号。
.email	字符串	返回客户的电子邮件地址。
.tags	列表<Tag>	返回字符串的列表，这些字符串表示为客户设置的任何标记。
.orders_count	整数	返回某个客户的总下单数。
.total_spent	金钱	返回客户在所有订单上花费的总金额。
.accepts_marketing?	布尔	返回客户是否接受营销。

LineItem

<tdgrams

使用 LineItem 对象的脚本方法

方法	返回类型	描述
.grams	返回订单项的总重量。
.line_price	金钱	订单项目的价格。
.discounted?	布尔	返回订单项目的价格是否已通过脚本进行打折或手动应用了折扣。使用折扣码不会影响返回值。
.properties	哈希	返回为此订单项目指定的属性。
.variant	多属性	返回订单项目代表的特定产品多属性。
.quantity	整数	返回订单项目的数量。
.selling_plan_id	整数	返回订单项目所对应销售计划的 ID。如果商店销售订阅，并且您希望脚本能检测出产品多属性是何时以订阅形式销售的，则此方法非常有用。

列表

使用 List 对象的脚本方法

方法	返回类型	描述
.new	列表	新建表示列表的新对象。
.[]	元素或零	返回指定索引处的元素。
.&	列表	返回一个新列表，其中包含两个列表共有的元素且没有重复项。
.delete_if	列表	使用可选代码块删除元素。查看文档，了解 Ruby 的 delete_if 方法。
.empty?	布尔	如果该列表不包含任何元素，则返回 true。
.first	元素或零	返回第一个元素，如果列表为空，则返回零。
.index(*args, &block)	整数或零	返回列表第一个元素的索引。如果给出了一个块而不是参数，则返回 block 为 true 的第一个元素的索引。
.rindex(*args, &block)	整数或零	返回列表中最后一个元素的索引。如果给定的是块而不是参数，则返回该块为 true 的第一个元素的索引。
.last	元素或零	返回最后一个元素，如果列表为空，则返回零。
.length	int	返回列表中的元素数量。
.size	int	length 的别名。
.each(*args, &block)	列表	为列表中的每个元素调用一次块，将元素作为参数传递给块。

发货地址

使用 ShippingAddress 对象的脚本方法

方法	返回类型	描述
.name	string	返回与收货地址关联的人员的姓名。
.address1	string	返回收货地址的街道地址部分。
.address2	string	返回收货地址的街道地址部分中的可选附加字段。
.phone	string	返回收货地址的电话号码。
.city	string	返回收货地址的城市。
.zip	string	返回收货地址的邮政编码。
.province	string	返回收货地址的省份/州。
.province_code	string	返回收货地址的省（或直辖市/自治区）/州的缩写值。
.country_code	string	返回收货地址的国家/地区的缩写值。

金钱

使用 Money 对象的脚本方法

方法	返回类型	描述
.derived_from_presentment(customer_cents:X)	金钱	将金额（以美分为单位）从客户的本地（显示）币种转化为您商店的货币。此方法接受 customer_cents 参数，该参数接受以美分为单位的数字。例如，Money.derived_from_presentment(customer_cents: 500)。
.new	金钱	创建代表价格的新对象。
.zero	金钱	新建价格为零的对象。
+	金钱	添加两个 Money 对象。
-	金钱	从一个 Money 对象中减去另一个 Money 对象。
*	金钱	将 Money 对象乘以数字。

Money 示例

Money.new(cents: 1000)

创建代表 1000 美分或 10 美元的 Money 对象。

Money.new(cents: 100) * 50

创建代表 1 美元的 Money 对象，然后将该金额乘以 50。返回代表 50 美元的 Money 对象。

多属性

使用 Variant 对象的脚本方法

方法	返回类型	描述
.id	整数	返回多属性的 ID 号。
.price	金钱	返回多属性的单价。
.product	产品	返回多属性的相关产品。
.skus	List<String>	返回多属性的货号 (SKU)，通常用于跟踪库存。
.title	字符串	返回多属性标题。

产品

使用 Product 对象的脚本方法

方法	返回类型	描述
.id	整数	返回产品的 ID 号。
.gift_card?	布尔	返回产品是否为礼品卡。
.tags	列表<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

订单项方法

以下方法仅适用于订单项目脚本：

购物车

在订单项目脚本中使用 Cart 对象的脚本方法

方法	返回类型	描述
.subtotal_price_was	金钱	返回应用任何折扣之前购物车的小计价格。
.subtotal_price_changed?	布尔	返回小计价格是否已更改。

LineItem

在订单项目脚本中使用 LineItem 对象的脚本方法

方法	返回类型	描述
.change_line_price(Money new_price, { message: String })	金钱	将订单项的价格更改为指定金额。需要一条消息。new_price 必须低于当前价格。
.original_line_price	金钱	返回应用脚本和折扣之前订单项目的原始价格。
.line_price_was	金钱	返回在当前脚本应用更改之前订单项目的价格。
.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

多属性

在订单项目脚本中使用 Variant 对象的脚本方法

方法	返回类型	描述
.compare_at_price	金钱	返回多属性的原价。如果多属性没有原价，则返回零。

发货方式

以下方法在发货脚本中可用：

输入

在发货脚本中使用 Input 对象的脚本方法

方法	返回类型	描述
.shipping_rates	ShippingRateList	返回所有运费的列表。

ShippingRateList

在发货脚本中使用 ShippingRateList 对象的脚本方法

方法	返回类型	描述
.delete_if	ShippingRateList	使用可选代码块删除运费。查看文档，了解 Ruby 的 delete_if 方法。
.sort!	ShippingRateList	使用比较运算符或可选代码块对运费进行排序。查看文档，了解 Ruby 的 sort! 方法。
.sort_by!	ShippingRateList	使用可选代码块对运费进行排序。查看文档，了解 Ruby 的 sort_by! 方法。

ShippingRate

在发货脚本中使用 ShippingRate 对象的脚本方法

方法	返回类型	描述
.code	字符串	返回运费代码。
.markup	金钱	返回运费的标记（如果适用）。
.name	字符串	返回运费名称。可以使用 change_name 方法对其进行修改。
.price	金钱	返回运费价格。
.source	字符串	返回与运费关联的来源（承运商）（如果相关）。无法进行修改。
.change_name(String new_name)	字符串	更改运费的名称（最多 255 个字符）。无法更改、删除或隐藏源。
.apply_discount(Money discount, { message: String })	金钱	应用指定固定金额的折扣。价格不能低于 0。需要一条消息。
.phone_required?	布尔	如果需要电话号码来获取运费，则返回 true；如果不需要电话号码，则返回 false。

支付方式

以下方法适用于付款脚本：

输入

在付款脚本中使用 Input 对象的脚本方法

方法	返回类型	描述
.payment_gateways	PaymentGatewaysList	返回商店中所有支付网关的列表。

PaymentGatewayList

在付款脚本中使用 PaymentGatewayList 对象的脚本方法

方法	返回类型	描述
.delete_if	PaymentGatewayList	使用可选代码块删除支付网关。查看文档，了解 Ruby 的 delete_if 方法。
.sort!	PaymentGatewayList	使用比较运算符或可选代码块对支付网关进行排序。查看文档，了解 Ruby 的 sort! 方法。
.sort_by!	PaymentGatewayList	使用可选代码块对支付网关进行排序。查看文档，了解 Ruby 的 sort_by! 方法。

PaymentGateway

方法	返回类型	描述
.name	字符串	返回支付网关的名称。
.enabled_card_brands	List<String>	如果支付网关支持信用卡，则返回商店接受的信用卡类型列表。如果网关不支持信用卡，则返回空列表。
.change_name(String new_name)	字符串	更改支付网关的名称。无法重命名具有 logo 的支付网关。

示例

在以下订单商品脚本示例中，当客户订购非礼品卡的产品时，产品价格会降低 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

详细了解

详细了解以下内容：

• Ruby 的基础知识
• 创建脚本
• 测试和调试您的脚本
• 更新用于脚本的 Liquid 模板
• Shopify 脚本