Shopify 脚本 API 参考

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

脚本分为不同类型。在脚本编辑器应用程序中创建脚本时,系统将根据您选择的脚本模板为脚本分配类型:

订单产品脚本

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

部分方法仅能用于订单商品脚本

配送脚本

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

部分方法仅能用于配送脚本

付款脚本

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

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

通用方法

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

输入

脚本输入方法
方法 返回类型 描述
.cart 购物车 返回可变的 Cart 对象。
.locale 字符串 返回客户的区域设置。例如,enfrpt-BR

购物车

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

使用 Cart 对象的脚本方法
方法 返回类型 描述
.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 金钱 返回应用订单商品折扣之后、应用折扣码之前的购物车小计价格。
.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 整数 返回订单商品的数量。

列表

使用 List 对象的脚本方法
方法 返回类型 描述
.new 列表 新建表示列表的新对象。
.[] 元素或零

返回指定索引处的元素。

.& 列表

返回一个新列表,其中包含两个列表共有的元素且没有重复项。

.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 字符串 返回运费名称。
.price 金钱 返回运费价格。
.source 字符串 返回与运费关联的来源(承运人)。
.change_name(String new_name, { message: String }) 字符串 更改运费名称(最多 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) 字符串 更改支付网关的名称。

示例

在以下订单商品脚本示例中,当客户订购非礼品卡的产品时,产品价格会降低 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 进行销售了吗?

免费试用