Shopify 脚本 API 参考

脚本通过 Ruby API 编写，可为您提供极大的控制权和灵活性。

套餐要求

自 2026 年 6 月 30 日起，Shopify 脚本已弃用。您商店中仍在发布的所有脚本均已停用且不再生效。若要重新创建这些自定义，请迁移至 Shopify Functions。了解有关从 Shopify 脚本迁移至 Shopify Functions 的详细信息。

有不同类型的脚本。当您在 Script Editor 应用中创建脚本时，系统会根据您选择的起始脚本模板为脚本分配类型：

订单项目脚本

订单项目脚本会影响购物车中的订单项目，可以更改价格并授予折扣。对购物车进行更改时，将运行这些脚本。

为订阅提供折扣的订单项目脚本仅适用于订阅的首次付款。后续付款不会通过该脚本获得折扣。

某些方法只能在订单项目脚本中使用。

发货脚本

发货脚本与发货交互，可以更改发货方式并为运费提供折扣。当结账到达发货选项页面时，将运行这些脚本。

为订阅的发货费率提供折扣的发货脚本仅适用于订阅的首次付款。后续付款不会通过该脚本获得折扣。

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

付款脚本

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

某些方法只能在付款脚本中使用。

通用方法

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

输入

脚本输入方法

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

Cart

购物车对象仅在在线商店中可用。某些弃单可以访问购物车对象。但是，如果结账已关闭，然后客户访问弃单链接，系统会将其发送到预填写的结账页面，此时购物车对象不再存在。这是因为在线店面已被弃单营销邮件绕过。

使用 Cart 对象的脚本方法

方法	返回类型	描述
.customer	Customer	返回购物车的所有者（如果有）。
.shipping_address	ShippingAddress	返回购物车所有者的收货地址（如果有）。
.discount_code	因情况而异	返回： 如果购物车没有折扣码，则返回 nil 如果购物车有固定金额折扣，则返回 CartDiscount::FixedAmount 如果购物车有百分比折扣，则返回 CartDiscount::Percentage 如果购物车有免运费折扣，则返回 CartDiscount::Shipping 返回单个折扣码（请参阅限制） 如果折扣已应用于购物车，则会显示 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?	布尔值	返回折扣码是否被拒绝。

客户

使用客户对象的脚本方法

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

订单项目

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

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

列表

使用列表对象的脚本方法

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

收货地址

使用收货地址对象的脚本方法

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

金额

使用金额对象的脚本方法

方法	返回类型	描述
.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 对象。

Variant

使用 Variant 对象的脚本方法

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

Product

使用 Product 对象的脚本方法

方法	返回类型	描述
.id	整数	返回产品的 ID。
.gift_card?	布尔值	返回产品是否为礼品卡。
.tags	列表<标记>	返回一个字符串列表，其中包含为此产品设置的标记。
.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

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

方法	返回类型	描述
.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

Variant

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

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

发货方法

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

输入

在发货脚本中使用 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	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 的 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.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

详细了解

详细了解：

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