shopify api php 开发,Shopify 脚本 API 参考

Shopify 脚本 API 参考

已于 Mar 19, 2021 打印了此页面。若要查看当前版本，请访问 https://help.shopify.com/zh-CN/manual/checkout-settings/script-editor/shopify-scripts。

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

脚本和 Script Editor 应用仅适用于 Shopify Plus 商家。

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

订单项目脚本

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

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

发货脚本

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

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

付款脚本

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

通用方法

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

输入

脚本输入方法

方法

返回类型

描述

.cart

返回可变的 Cart 对象。

.locale

字符串

返回客户的区域设置。例如，en、fr 或 pt-BR。

购物车

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

使用 Cart 对象的脚本方法

方法

返回类型

描述

.customer

返回购物车的所有者(如果有)。

.shipping_address

返回购物车所有者的收货地址(如果有)。

.discount_code

不定

返回：

如果已将折扣应用于购物车，则存在 discount_code。这并不一定意味着购物车的价格发生了更改。例如，如果将折扣应用于价格高于 50 美元的购物车，并且脚本将购物车价格减少至 50 美元以下，则 discount_code 仍然存在，但购物车的价格未发生更改。

查看 discount_code 的示例。

.line_items

List

返回包含购物车中订单项目的列表。

.presentment_currency

List

返回客户的当地(出示)货币(采用 ISO 4217 格式)。例如 USD。

.subtotal_price

返回应用订单项目折扣之后、应用折扣码之前的购物车小计价格。

.total_weight

返回购物车中所有订单项的总重量。

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

列表

返回字符串的列表，这些字符串表示为客户设置的任何标记。

.orders_count

整数

返回某个客户的总下单数。

.total_spent

返回客户在所有订单上花费的总金额。

.accepts_marketing?

布尔

返回客户是否接受营销。

LineItem

使用 LineItem 对象的脚本方法

方法

返回类型

描述

.grams

返回订单项的总重量。

.line_price

订单项目的价格。

.discounted?

布尔

返回折扣是否更改了订单项的价格。

.properties

哈希

返回为此订单项目指定的属性。

.variant

返回订单项目代表的特定产品多属性。

.quantity

整数

返回订单项目的数量。

.selling_plan_id

整数

如果商店销售订阅，并且您希望脚本能检测出产品多属性是何时以订阅形式销售的，则此方法非常有用。

列表

使用 List 对象的脚本方法

方法

返回类型

描述

.new

新建表示列表的新对象。

.[]

元素或零

返回指定索引处的元素。

.&

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

.empty?

布尔

如果该列表不包含任何元素，则返回 true。

.first

元素或零

返回第一个元素，如果列表为空，则返回零。

.index(*args, &block)

整数或零

返回列表第一个元素的索引。如果给出了一个块而不是参数，则返回 block 为 true 的第一个元素的索引。

.rindex(*args, &block)

整数或零

返回列表中最后一个元素的索引。如果给定的是块而不是参数，则返回该块为 true 的第一个元素的索引。

.last

元素或零

返回最后一个元素，如果列表为空，则返回零。

.length

int

返回列表中的元素数量。

.size

int

.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

返回多属性的货号 (SKU)，通常用于跟踪库存。

.title

字符串

返回多属性标题。

产品

使用 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 对象的脚本方法

方法

返回类型

描述

.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 })

将一个订单商品拆分为两个订单商品。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 对象的脚本方法

方法

返回类型

描述

.sort!

使用比较运算符或可选代码块对运费进行排序。查看文档，了解 Ruby 的 sort! 方法。

.sort_by!

使用可选代码块对运费进行排序。查看文档，了解 Ruby 的 sort_by! 方法。

ShippingRate

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

方法

返回类型

描述

.code

字符串

返回运费代码。

.markup

字符串

返回运费说明的标记。

.name

字符串

返回运费名称。

.price

返回运费价格。

.source

字符串

返回与运费关联的来源(承运商)。

.change_name(String new_name)

字符串

更改运费名称(最多 255 个字符)。

.apply_discount(Money discount, { message: String })

应用指定固定金额的折扣。价格不能低于 0。需要一条消息。

.phone_required?

布尔

如果需要电话号码来获取运费，则返回 true；如果不需要电话号码，则返回 false。

支付方式

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

输入

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

方法

返回类型

描述

.payment_gateways

返回商店中所有支付网关的列表。

PaymentGatewayList

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

方法

返回类型

描述

.sort!

使用比较运算符或可选代码块对支付网关进行排序。查看文档，了解 Ruby 的 sort! 方法。

.sort_by!

使用可选代码块对支付网关进行排序。查看文档，了解 Ruby 的 sort_by! 方法。

PaymentGateway

方法

返回类型

描述

.name

字符串

返回支付网关的名称。

.enabled_card_brands

List

如果支付网关支持信用卡，则返回商店接受的信用卡类型列表。如果网关不支持信用卡，则返回空列表。

.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

了解详细信息

详细了解以下内容：