Довідник з API сценаріїв Shopify

Сценарії пишуться за допомогою API Ruby, який забезпечує високий рівень контролю та гнучкості.

Існують різні типи сценаріїв. Тип призначається сценарію під час його створення в застосунку Script Editor і залежить від того, який шаблон ви вибрали як початковий:

Сценарії для позицій

Сценарії для позицій впливають на позиції в кошику, можуть змінювати ціни та надавати знижки. Ці сценарії запускаються під час внесення змін до кошика.

Сценарії для позицій, що надають знижку на передплату, застосовуються лише до першого платежу за нею. Знижка за сценарієм не поширюється на наступні платежі.

Деякі методи можна використовувати лише в сценаріях для позицій.

Сценарії доставки

Сценарії доставки взаємодіють із доставкою, можуть змінювати способи доставки та надавати знижки на тарифи на доставку. Ці сценарії запускаються, коли оформлення замовлення переходить на сторінку варіантів доставки.

Сценарії доставки, які знижують вартість доставки передплати, застосовуються лише до першого платежу за нею. Знижка за сценарієм не поширюється на наступні платежі.

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

Платіжні сценарії

Платіжні сценарії взаємодіють із платежами, можуть перейменовувати, приховувати та змінювати порядок платіжних шлюзів. Зверніть увагу, що платіжні сценарії не взаємодіють із платіжними шлюзами, які відображаються до переходу на екран оформлення замовлення (наприклад, Apple Pay). Ці сценарії запускаються, коли оформлення замовлення переходить на сторінку оплати.

Деякі методи можна використовувати лише в платіжних сценаріях.

На цій сторінці

Загальні методи

Такі методи можна використовувати в будь-якому типі сценаріїв:

Вхідні дані

Методи вхідних даних для сценаріїв
Метод	Тип значення, що повертається	Опис
.cart	Кошик	Повертає змінюваний об’єкт кошика.
.locale	рядок	Повертає локаль клієнта. Наприклад, `en`, `fr` або `pt-BR`.

Кошик

Об’єкт кошика доступний лише в інтернет-магазині. Деякі покинуті оформлення замовлення мають доступ до об’єкта кошика. Однак, якщо оформлення замовлення було закрито, а потім клієнт відвідує покинуте оформлення замовлення, його спрямовують до попередньо заповненого оформлення замовлення, і об’єкт кошика більше не існує. Це відбувається тому, що вітрина оминається через електронний лист щодо покинутого оформлення замовлення.

Методи сценаріїв, які використовують об’єкт кошика
Метод	Тип значення, що повертається	Опис
.customer	Клієнт	Повертає власника кошика (якщо такий є).
.shipping_address	Адреса доставки	Повертає адресу доставки власника кошика (якщо є).
.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><LineItem></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><String></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	Гроші	Повертає грошову суму знижки.
.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?	Булеве значення	Повертає інформацію про те, чи було відхилено код знижки.

Customer

Методи сценаріїв, що використовують об'єкт Customer
Метод	Тип значення, що повертається	Опис
.id	Ціле число	Повертає ідентифікатор клієнта.
.email	Рядок	Повертає адресу електронної пошти клієнта.
.tags	List<Tag>	Повертає список рядків, що відображають усі теги, встановлені для клієнта.
.orders_count	Ціле число	Повертає загальну кількість замовлень, розміщених клієнтом.
.total_spent	Гроші	Повертає загальну суму, яку клієнт витратив на всі замовлення.
.accepts_marketing?	Булеве значення	Повертає інформацію про те, чи погодився клієнт на отримання маркетингових матеріалів.

LineItem

Методи сценаріїв, що використовують об'єкт LineItem
Метод	Тип значення, що повертається	Опис
.grams	grams	Повертає загальну вагу позиції.
.line_price	Гроші	Ціна позиції.
.discounted?	Булеве значення	Повертає інформацію про те, чи було застосовано знижку до ціни позиції за допомогою сценарію або вручну. Використання кодів знижки не впливає на значення, що повертається.
.properties	хеш	Повертає властивості, указані для цієї позиції.
.variant	Variant	Повертає конкретний варіант товару, представлений позицією.
.quantity	Ціле число	Повертає кількість для цієї позиції.
.selling_plan_id	Ціле число	Повертає ідентифікатор плану продажу для позиції. Цей метод корисний, коли магазин продає підписки, і вам потрібно, щоб сценарій виявляв, коли варіант товару продається як підписка.

List

Методи сценаріїв, що використовують об'єкт List
Метод	Тип значення, що повертається	Опис
.new	List	Створює новий об'єкт для представлення списку.
.[]	Елемент або nil	Повертає елемент за вказаним індексом.
.&	List	Повертає новий список, що містить спільні для двох списків елементи без дублікатів.
.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	Викликає блок по одному разу для кожного елемента списку, передаючи елемент як параметр до блоку.

ShippingAddress

Методи сценаріїв, що використовують об'єкт ShippingAddress
Метод	Тип значення, що повертається	Опис
.name	рядок	Повертає ім'я особи, пов'язаної з адресою доставки.
.address1	рядок	Повертає частину адреси доставки з назвою вулиці.
.address2	рядок	Повертає необов'язкове додаткове поле частини адреси доставки з назвою вулиці.
.phone	рядок	Повертає номер телефону адреси доставки.
.city	рядок	Повертає місто адреси доставки.
.zip	рядок	Повертає поштовий індекс адреси доставки.
.province	рядок	Повертає регіон/штат адреси доставки.
.province_code	рядок	Повертає скорочену назву регіону/штату адреси доставки.
.country_code	рядок	Повертає скорочену назву країни адреси доставки.

Money

Методи сценаріїв, що використовують об’єкт Money
Метод	Тип значення, що повертається	Опис
.derived_from_presentment(customer_cents:X)	Гроші	Конвертує суму (у центах) з місцевої валюти (валюти відображення) клієнта у валюту вашого магазину. Цей метод приймає параметр `customer_cents`, який набуває значення числа в центах. Наприклад: `Money.derived_from_presentment(customer_cents: 500)`.
.new	Гроші	Створює новий об’єкт, який представляє ціну.
.zero	Гроші	Створює новий об’єкт із ціною, що дорівнює нулю.
+	Гроші	Додає два об’єкти `Money`.
-	Гроші	Віднімає один об’єкт `Money` від іншого.
*	Гроші	Множить об’єкт `Money` на число.

Приклади використання Money

Money.new(cents: 1000)

Створює об’єкт Money, який представляє 1000 центів, або 10 доларів США.

Money.new(cents: 100) * 50

Створює об’єкт Money, який представляє 1 долар США, а потім множить цю суму на 50. Повертає об’єкт Money, який представляє 50 доларів США.

Варіант

Методи сценаріїв, що використовують об’єкт Variant
Метод	Тип значення, що повертається	Опис
.id	Ціле число	Повертає ідентифікатор варіанта.
.price	Гроші	Повертає ціну за одиницю варіанта.
.product	Product	Повертає пов’язаний товар для варіанта.
.skus	List<String>	Повертає одиниці зберігання запасів (артикули) варіанта, які часто використовуються для відстеження запасів.
.title	Рядок	Повертає назву варіанта.

Товар

Методи сценаріїв, що використовують об’єкт Product
Метод	Тип значення, що повертається	Опис
.id	Ціле число	Повертає ідентифікатор товару.
.gift_card?	Булеве значення	Повертає інформацію про те, чи є товар подарунковою карткою.
.tags	List<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 })	Гроші	Змінює ціну позиції на вказану суму. Потрібно вказати параметр `message`. Значення `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). Потім сценарій застосовує до нової позиції ціну зі знижкою та повідомленням «Third hat for 5 dollars».

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	Гроші	Повертає ціну до знижки для варіанта. Повертає `nil`, якщо для варіанта не вказано ціну до знижки.

Способи доставки

Наведені нижче методи можна використовувати в сценаріях доставки:

Вхідні дані

Методи сценарію, що використовують об’єкт Input у сценаріях доставки
Метод	Тип значення, що повертається	Опис
.shipping_rates	ShippingRateList	Повертає список усіх тарифів на доставку.

ShippingRateList

Методи сценарію, що використовують об’єкт ShippingRateList у сценаріях доставки
Метод	Тип значення, що повертається	Опис
.delete_if	ShippingRateList	Видаляє тарифи на доставку за допомогою необов’язкового блоку коду. Див. документацію для методу `delete_if` у Ruby.
.sort!	ShippingRateList	Сортує тарифи на доставку за допомогою оператора порівняння або необов’язкового блоку коду. Див. документацію для методу `sort!` у Ruby.
.sort_by!	ShippingRateList	Сортує тарифи на доставку за допомогою необов’язкового блоку коду. Див. документацію для методу `sort_by!` у Ruby.

ShippingRate

Методи сценарію, що використовують об’єкт 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`, якщо номер телефону не потрібен.

Способи оплати

Наведені нижче методи можна використовувати в платіжних сценаріях:

Вхідні дані

Методи сценарію, що використовують об’єкт Input у платіжних сценаріях
Метод	Тип значення, що повертається	Опис
.payment_gateways	PaymentGatewaysList	Повертає список усіх платіжних шлюзів у магазині.

PaymentGatewayList

Методи сценарію, що використовують об’єкт PaymentGatewayList у платіжних сценаріях
Метод	Тип значення, що повертається	Опис
.delete_if	PaymentGatewayList	Видаляє платіжні шлюзи за допомогою необов’язкового блоку коду. Див. документацію для методу `delete_if` у Ruby.
.sort!	PaymentGatewayList	Сортує платіжні шлюзи за допомогою оператора порівняння або необов’язкового блоку коду. Див. документацію для методу `sort!` у Ruby.
.sort_by!	PaymentGatewayList	Сортує платіжні шлюзи за допомогою необов’язкового блоку коду. Див. документацію для методу `sort_by!` у Ruby.

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

Дізнатися більше

Дізнайтеся більше про: