Shopify スクリプト API リファレンス
スクリプトは、高度な管理と優れた柔軟性を実現する Ruby API を使用して作成します。
スクリプトにはさまざまなタイプがあります。スクリプトのタイプは、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
カートオブジェクトは、オンラインストアでのみ利用できます。一部のチェックアウト離脱では、カートオブジェクトにアクセスできます。しかし、チェックアウトが終了してからお客様がチェックアウト離脱にアクセスすると、入力済みのチェックアウトに転送され、カートオブジェクトは存在しなくなります。これは、ストアフロントが決済未完了の通知メールによってバイパスされたためです。
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .customer | Customer | カートの所有者 (いる場合) を返します。 |
| .shipping_address | ShippingAddress | カートの所有者の配送先住所 (ある場合) を返します。 |
| .discount_code | 状況による |
返されるもの：
|
CartDiscount::FixedAmount
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .code | 文字列 | ディスカウントを適用するために使用されたディスカウントコードを返します。 |
| .amount | Money | ディスカウントの金額を返します。 |
| .reject({ message: String }) | nil | カートに適用されたディスカウントコードを拒否します。message は必須です。 |
| .rejected? | ブール値 | ディスカウントコードが拒否されたかどうかを返します。 |
CartDiscount::Percentage
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .code | 文字列 | ディスカウントを適用するために使用されたディスカウントコードを返します。 |
| .percentage | 小数 | ディスカウントのパーセンテージ額を返します。 |
| .reject({ message: String }) | nil | カートに適用されたディスカウントコードを拒否します。message は必須です。 |
| .rejected? | ブール値 | ディスカウントコードが拒否されたかどうかを返します。 |
CartDiscount::Shipping
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .code | 文字列 | ディスカウントを適用するために使用されたディスカウントコードを返します。 |
| .reject({ message: String }) | nil | カートに適用されたディスカウントコードを拒否します。message は必須です。 |
| .rejected? | ブール値 | ディスカウントコードが拒否されたかどうかを返します。 |
Customer
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .id | Integer | お客様の ID を返します。 |
| 文字列 | お客様のメールアドレスを返します。 | |
| .tags | List<Tag> | お客様に設定されているタグを表す文字列のリストを返します。 |
| .orders_count | Integer | お客様が行った注文の合計数を返します。 |
| .total_spent | Money | お客様がすべての注文で利用した合計金額を返します。 |
| .accepts_marketing? | ブール値 | お客様がマーケティングを受け入れるかどうかを返します。 |
LineItem
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .grams | grams | 項目の総重量を返します。 |
| .line_price | Money | 項目の価格です。 |
| .discounted? | ブール値 | スクリプトまたは手動で適用されたディスカウントによって項目の価格がディスカウントされたかどうかを返します。ディスカウントコードの使用は、戻り値に影響しません。 |
| .properties | ハッシュ | この項目に指定されたプロパティを返します。 |
| .variant | Variant | 項目によって表される特定の商品バリエーションを返します。 |
| .quantity | Integer | この項目の数量を返します。 |
| .selling_plan_id | Integer | 項目の販売計画の ID を返します。このメソッドは、ストアで定期購入が販売されており、商品バリエーションが 定期購入として販売されるタイミングをスクリプトで検出する場合に役立ちます。 |
List
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .new | List | リストを表す新しいオブジェクトを作成します。 |
| .[] | 要素または nil |
指定されたインデックスにある要素を返します。 |
| .& | List |
2 つのリストに共通する要素を含む新しいリストを、重複なしで返します。 |
| .delete_if | List | 任意のコードブロックを使用して要素を削除します。Ruby の delete_if メソッドに関するドキュメントを参照してください。 |
| .empty? | ブール値 |
リストに要素が含まれていない場合に `true` を返します。 |
| .first | 要素または nil |
最初の要素を返します。リストが空の場合は `nil` を返します。 |
| .index(*args, &block) | int または nil |
リストの最初の要素のインデックスを返します。引数の代わりにブロックが指定されている場合、ブロックが true になる最初の要素のインデックスを返します。 |
| .rindex(*args, &block) | int または nil |
リストの最後の要素のインデックスを返します。引数の代わりにブロックが指定されている場合、ブロックが true になる最初の要素のインデックスを返します。 |
| .last | 要素または nil |
最後の要素を返します。リストが空の場合は `nil` を返します。 |
| .length | int |
リスト内の要素数を返します。 |
| .size | int |
`length` のエイリアスです。 |
| .each(*args, &block) | List |
リスト内の各要素に対してブロックを 1 回呼び出し、その要素をパラメータとしてブロックに渡します。 |
ShippingAddress
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .name | 文字列 | 配送先住所に関連付けられている人の氏名を返します。 |
| .address1 | 文字列 | 配送先住所の、町名・番地部分を返します。 |
| .address2 | 文字列 | 配送先住所の、町名・番地部分の任意の追加フィールドを返します。 |
| .phone | 文字列 | 配送先住所の電話番号を返します。 |
| .city | 文字列 | 配送先住所の市区町村を返します。 |
| .zip | 文字列 | 配送先住所の郵便番号を返します。 |
| .province | 文字列 | 配送先住所の都道府県/州を返します。 |
| .province_code | 文字列 | 配送先住所の都道府県/州の省略形の値を返します。 |
| .country_code | 文字列 | 配送先住所の国の省略形の値を返します。 |
Money
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .derived_from_presentment(customer_cents:X) | Money | お客様の現地 (表示) 通貨からストアの通貨に、金額 (セント単位) を変換します。このメソッドは、セント単位の数値を受け入れる customer_cents パラメーターに対応しています。たとえば、Money.derived_from_presentment(customer_cents: 500) のように使用します。 |
| .new | Money | 価格を表す新しいオブジェクトを作成します。 |
| .zero | Money |
価格がゼロの新しいオブジェクトを作成します。 |
| + | Money | 2 つの Money オブジェクトを加算します。 |
| - | Money | ある Money オブジェクトから別のオブジェクトを減算します。 |
| * | Money | Money オブジェクトに数値を乗算します。 |
Money の例
Money.new(cents: 1000)1000 セント (10 ドル) を表す Money オブジェクトを作成します。
Money.new(cents: 100) * 501 ドルを表す Money オブジェクトを作成し、その金額に 50 を乗算します。50 ドルを表す Money オブジェクトが返されます。
バリエーション
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .id | Integer | バリエーションの ID 番号を返します。 |
| .price | Money | バリエーションの単価を返します。 |
| .product | Product | バリエーションに関連付けられている商品を返します。 |
| .skus | List<String> | バリエーションの最小管理単位 (SKU) を返します。これは、在庫の追跡によく使用されます。 |
| .title | 文字列 | バリエーションのタイトルを返します。 |
商品
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .id | Integer | 商品の ID 番号を返します。 |
| .gift_card? | ブール値 | 商品がギフトカードであるかどうかを返します。 |
| .tags | List<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項目メソッド
以下のメソッドは、項目スクリプトでのみ使用できます。
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 | 1 つの項目を 2 つの項目に分割します。take は、元の項目から削除して新しい項目を作成する数量を指定します。 |
.split の例
このスクリプトの例では、original_line_item という名前の項目を 2 つの項目に分割します。新しい項目の数量は 1 です (take: 1 で指定)。次に、スクリプトは、「3 つ目の帽子を 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 | Money | バリエーションの割引前価格を返します。バリエーションに割引前価格がない場合は、nil を返します。 |
配送方法
以下のメソッドは、配送スクリプトで使用できます。
入力
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .shipping_rates | ShippingRateList | すべての配送料のリストを返します。 |
ShippingRateList
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .delete_if | ShippingRateList | 任意のコードブロックを使用して配送料を削除します。Ruby の delete_if メソッドに関するドキュメントを参照してください。 |
| .sort! | ShippingRateList | 比較演算子または任意のコードブロックを使用して配送料を並べ替えます。Ruby の sort! メソッドに関するドキュメントを参照してください。 |
| .sort_by! | ShippingRateList | 任意のコードブロックを使用して配送料を並べ替えます。Ruby の sort_by! メソッドに関するドキュメントを参照してください。 |
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 を返します。 |
決済方法
以下のメソッドは決済スクリプトで使用できます。
入力
| メソッド | 戻り値の型 | 説明 |
|---|---|---|
| .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) | 文字列 | 決済ゲートウェイサービスの名前を変更します。ロゴ付きの決済ゲートウェイサービスは名前を変更できません。 |
例
次の項目スクリプトの例では、お客様がギフトカードではない商品を注文すると、商品の価格が 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詳しくはこちら
以下について詳しくはこちら