Shopify 脚本 API 参考
脚本是使用 Ruby API 编写的,能实现高度的控制力和灵活性。
脚本分为不同类型。在 Script Editor 应用程序中创建脚本时,系统将根据您选择的脚本模板为脚本分配类型:
订单项目脚本
订单项目脚本会影响购物车中的订单项,可以更改价格和给予折扣。此类脚本会在购物车产生变化时运行。
提供订阅折扣的订单项目脚本仅适用第一笔订阅付款。该脚本不会为后续付款提供折扣。
部分方法仅能用于订单项目脚本。
通用方法
以下方法适用于任何类型的脚本:
输入
方法 | 返回类型 | 描述 |
---|---|---|
.cart | 购物车 | 返回可变的 Cart 对象。 |
.locale | 字符串 | 返回客户的区域设置。例如,en 、fr 或 pt-BR 。 |
购物车
Cart 对象仅适用于在线商店。某些弃单可以访问 Cart 对象。但是,如果客户在某一结账关闭后访问此弃单,它则会将客户导向至预先填写的结账处,并且 Cart 对象不再存在。这是因为弃单营销邮件绕过了店面。
方法 | 返回类型 | 描述 |
---|---|---|
.customer | 客户 | 返回购物车的所有者(如果有)。 |
.shipping_address | 发货地址 | 返回购物车所有者的收货地址(如果有)。 |
.discount_code | 不定 |
返回:
如果已将折扣应用于购物车,则存在 |
.line_items | List<LineItem> | 返回包含购物车中订单项目的列表。 |
.presentment_currency | List<String> | 返回客户的当地(显示)币种(采用 ISO 4217 格式)。例如 USD。 |
.subtotal_price | 金钱 | 返回应用订单项目折扣之后、应用折扣码之前的购物车小计价格。 |
.total_weight | grams | 返回购物车中所有订单项的总重量。 |
CartDiscount::FixedAmount
方法 | 返回类型 | 描述 |
---|---|---|
.code | 字符串 | 返回用于应用折扣的折扣码。 |
.amount | 金钱 | 退还折扣金额。 |
.reject({ message: String }) | 零 | 拒绝应用于购物车的折扣码。需要一条消息 。 |
.rejected? | 布尔 | 返回折扣码是否被拒绝。 |
CartDiscount::Percentage
方法 | 返回类型 | 描述 |
---|---|---|
.code | 字符串 | 返回用于应用折扣的折扣码。 |
.percentage | 十进制 | 返回折扣的百分比值。 |
.reject({ message: String }) | 零 | 拒绝应用于购物车的折扣码。需要一条消息 。 |
.rejected? | 布尔 | 返回折扣码是否被拒绝。 |
CartDiscount::Shipping
方法 | 返回类型 | 描述 |
---|---|---|
.code | 字符串 | 返回用于应用折扣的折扣码。 |
.reject({ message: String }) | 零 | 拒绝应用于购物车的折扣码。需要一条消息 。 |
.rejected? | 布尔 | 返回折扣码是否被拒绝。 |
客户
方法 | 返回类型 | 描述 |
---|---|---|
.id | 整数 | 返回客户的 ID 编号。 |
字符串 | 返回客户的电子邮件地址。 | |
.tags | 列表<Tag> | 返回字符串的列表,这些字符串表示为客户设置的任何标记。 |
.orders_count | 整数 | 返回某个客户的总下单数。 |
.total_spent | 金钱 | 返回客户在所有订单上花费的总金额。 |
.accepts_marketing? | 布尔 | 返回客户是否接受营销。 |
LineItem
方法 | 返回类型 | 描述 |
---|---|---|
.grams | <tdgrams返回订单项的总重量。 | |
.line_price | 金钱 | 订单项目的价格。 |
.discounted? | 布尔 | 返回订单项目的价格是否已通过脚本进行打折或手动应用了折扣。使用折扣码不会影响返回值。 |
.properties | 哈希 | 返回为此订单项目指定的属性。 |
.variant | 多属性 | 返回订单项目代表的特定产品多属性。 |
.quantity | 整数 | 返回订单项目的数量。 |
.selling_plan_id | 整数 | 返回订单项目所对应销售计划的 ID。如果商店销售订阅,并且您希望脚本能检测出产品多属性是何时以订阅形式销售的,则此方法非常有用。 |
列表
方法 | 返回类型 | 描述 |
---|---|---|
.new | 列表 | 新建表示列表的新对象。 |
.[] | 元素或零 |
返回指定索引处的元素。 |
.& | 列表 |
返回一个新列表,其中包含两个列表共有的元素且没有重复项。 |
.delete_if | 列表 | 使用可选代码块删除元素。查看文档,了解 Ruby 的 delete_if 方法。 |
.empty? | 布尔 |
如果该列表不包含任何元素,则返回 |
.first | 元素或零 |
返回第一个元素,如果列表为空,则返回 |
.index(*args, &block) | 整数或零 |
返回列表第一个元素的索引。如果给出了一个块而不是参数,则返回 block 为 true 的第一个元素的索引。 |
.rindex(*args, &block) | 整数或零 |
返回列表中最后一个元素的索引。如果给定的是块而不是参数,则返回该块为 true 的第一个元素的索引。 |
.last | 元素或零 |
返回最后一个元素,如果列表为空,则返回 |
.length | int |
返回列表中的元素数量。 |
.size | int |
length 的别名。 |
.each(*args, &block) | 列表 |
为列表中的每个元素调用一次块,将元素作为参数传递给块。 |
发货地址
方法 | 返回类型 | 描述 |
---|---|---|
.name | string | 返回与收货地址关联的人员的姓名。 |
.address1 | string | 返回收货地址的街道地址部分。 |
.address2 | string | 返回收货地址的街道地址部分中的可选附加字段。 |
.phone | string | 返回收货地址的电话号码。 |
.city | string | 返回收货地址的城市。 |
.zip | string | 返回收货地址的邮政编码。 |
.province | string | 返回收货地址的省份/州。 |
.province_code | string | 返回收货地址的省(或直辖市/自治区)/州的缩写值。 |
.country_code | string | 返回收货地址的国家/地区的缩写值。 |
金钱
方法 | 返回类型 | 描述 |
---|---|---|
.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
对象。
多属性
方法 | 返回类型 | 描述 |
---|---|---|
.id | 整数 | 返回多属性的 ID 号。 |
.price | 金钱 | 返回多属性的单价。 |
.product | 产品 | 返回多属性的相关产品。 |
.skus | List<String> | 返回多属性的货号 (SKU),通常用于跟踪库存。 |
.title | 字符串 | 返回多属性标题。 |
产品
方法 | 返回类型 | 描述 |
---|---|---|
.id | 整数 | 返回产品的 ID 号。 |
.gift_card? | 布尔 | 返回产品是否为礼品卡。 |
.tags | 列表<Tag> | 返回字符串的列表,这些字符串表示为此产品设置的标记。 |
.product_type | 字符串 | 可以标记产品的分类,通常用于筛选和搜索。 |
.vendor | 字符串 | 返回产品的厂商。 |
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 | 金钱 | 返回应用任何折扣之前购物车的小计价格。 |
.subtotal_price_changed? | 布尔 | 返回小计价格是否已更改。 |
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
多属性
方法 | 返回类型 | 描述 |
---|---|---|
.compare_at_price | 金钱 | 返回多属性的原价。如果多属性没有原价,则返回零 。 |
发货方式
以下方法在发货脚本中可用:
输入
方法 | 返回类型 | 描述 |
---|---|---|
.shipping_rates | ShippingRateList | 返回所有运费的列表。 |
ShippingRateList
方法 | 返回类型 | 描述 |
---|---|---|
.delete_if | ShippingRateList | 使用可选代码块删除运费。查看文档,了解 Ruby 的 delete_if 方法。 |
.sort! | ShippingRateList | 使用比较运算符或可选代码块对运费进行排序。查看文档,了解 Ruby 的 sort! 方法。 |
.sort_by! | ShippingRateList | 使用可选代码块对运费进行排序。查看文档,了解 Ruby 的 sort_by! 方法。 |
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 。 |
支付方式
以下方法适用于付款脚本:
输入
方法 | 返回类型 | 描述 |
---|---|---|
.payment_gateways | PaymentGatewaysList | 返回商店中所有支付网关的列表。 |
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
详细了解
详细了解以下内容: