Справочник за API на Shopify Scripts

Скриптовете се пишат с Ruby API, който Ви дава голям контрол и гъвкавост.

Изискване за план

Shopify Scripts и приложението Script Editor са достъпни само за магазини с план Shopify Plus. Приложението Script Editor вече не е достъпно за изтегляне от App Store.

На 30 юни 2026 г. Shopify Scripts ще бъдат премахнати и вече няма да работят. Ако искате продължаваща поддръжка за съществуващите си случаи на използване на Shopify Scripts, тогава трябва да преминете към съвместими заместители на Shopify Functions за съществуващите си скриптове за плащане, доставка или редове. Научете повече за преминаването от Shopify Scripts към Shopify Functions.

Има различни типове скриптове. На скрипта се присвоява тип, когато го създавате в приложението 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

Обектът Cart е достъпен само в онлайн магазина. Някои незавършени процеси на поръчка имат достъп до обекта Cart. Въпреки това, ако даден процес на плащане е бил затворен и след това клиент посети незавършения процес на поръчка, той го изпраща към предварително попълненото плащане и обектът Cart вече не съществува. Това е така, защото витрината е била заобиколена от имейла за изоставено плащане.

Методи на скрипта, използващи обекта Cart
Метод	Тип на връщаната стойност	Описание
.customer	Customer	Връща собственика на количката (ако има такъв).
.shipping_address	ShippingAddress	Връща адреса за доставка на собственика на количката (ако има такъв).
.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	Money	Връща паричната сума на отстъпката.
.reject({ message: String })	nil	Отхвърля кода за отстъпка, приложен към количката. Изисква се `съобщение`.
.rejected?	Булев	Връща информация дали кодът за отстъпка е отхвърлен.

CartDiscount::Percentage

Методи на скрипта, използващи обекта CartDiscount::Percentage
Метод	Тип на връщаната стойност	Описание
.code	Низ	Връща кода за отстъпка, използван за прилагане на отстъпката.
.percentage	Десетичен	Връща сумата на отстъпката в процент.
.reject({ message: String })	nil	Отхвърля кода за отстъпка, приложен към количката. Изисква се `съобщение`.
.rejected?	Булев	Връща информация дали кодът за отстъпка е отхвърлен.

CartDiscount::Shipping

Методи на скрипта, използващи обекта CartDiscount::Shipping
Метод	Тип на връщаната стойност	Описание
.code	Низ	Връща кода за отстъпка, използван за прилагане на отстъпката.
.reject({ message: String })	nil	Отхвърля кода за отстъпка, приложен към количката. Изисква се `съобщение`.
.rejected?	Булев	Връща информация дали кодът за отстъпка е отхвърлен.

Customer

Методи на скрипта, използващи обекта Customer
Метод	Тип на връщаната стойност	Описание
.id	Цяло число	Връща идентификационния номер на клиента.
.email	Низ	Връща имейл адреса на клиента.
.tags	List<Tag>	Връща списък с низове, представящи всички тагове, зададени за даден клиент.
.orders_count	Цяло число	Връща общия брой поръчки, които клиентът е направил.
.total_spent	Money	Връща общата сума, която клиентът е похарчил за всички поръчки.
.accepts_marketing?	Булев	Връща информация дали клиентът приема маркетингови съобщения.

LineItem

Методи на скрипта, използващи обекта LineItem
Метод	Тип на връщаната стойност	Описание
.grams	грамове	Връща общото тегло на реда.
.line_price	Money	Цената на реда.
.discounted?	Булев	Връща информация дали цената на даден ред е намалена чрез скрипт или ръчно приложена отстъпка. Използването на кодове за отстъпка не влияе на върнатата стойност.
.properties	Хеш	Връща свойствата, които са посочени за тези редове.
.variant	Variant	Връща конкретния продуктов вариант, представен от реда.
.quantity	Цяло число	Връща количеството на този ред.
.selling_plan_id	Цяло число	Връща идентификатора на плана за продажба за реда. Този метод е полезен, когато магазинът продава абонаменти и искате скриптът да открие кога даден продуктов вариант се продава като абонамент.

List

Методи на скрипта, използващи обекта List
Метод	Тип на връщаната стойност	Описание
.new	List	Създава нов обект, който да представлява списък.
.[]	Елемент или nil	Връща елемента на посочения индекс.
.&	List	Връща нов списък, съдържащ елементи, общи за двата списъка, без дубликати.
.delete_if	List	Изтрива елементи с помощта на незадължителен кодов блок. Вижте документацията за метода `delete_if` на Ruby.
.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)	Money	Конвертира сума (в центове) от местната валута на клиента (валута на плащане от клиента) във валутата на Вашия магазин. Този метод приема параметъра `customer_cents`, който приема число в центове. Например `Money.derived_from_presentment(customer_cents: 500)`.
.new	Money	Създава нов обект, който представя цена.
.zero	Money	Създава нов обект с нулева цена.
+	Money	Събира два обекта `Money`.
-	Money	Изважда един обект `Money` от друг.
*	Money	Умножава обект `Money` с число.

Примери за Money

Money.new(cents: 1000)

Създава обект Money, представляващ 1000 цента, или 10 USD.

Money.new(cents: 100) * 50

Създава обект Money, представляващ 1 USD, след което умножава тази сума по 50. Връща обект Money, представляващ 50 USD.

Вариант

Методи на скрипта, използващи обект Variant
Метод	Тип на връщаната стойност	Описание
.id	Цяло число	Връща идентификатора на варианта.
.price	Money	Връща единичната цена на варианта.
.product	Продукт	Връща свързания продукт на варианта.
.skus	Списък<Низ>	Връща складовите единици на продукта (SKU) на варианта, които често се използват за проследяване на наличностите.
.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

Методи на скрипта, използващи обект Cart в скриптове за редове
Метод	Тип на връщаната стойност	Описание
.subtotal_price_was	Money	Връща междинната сума на количката, преди да са приложени каквито и да било отстъпки.
.subtotal_price_changed?	Булев	Връща дали междинната сума се е променила.

LineItem

Методи на скрипта, използващи обект LineItem в скриптове за редове
Метод	Тип на връщаната стойност	Описание
.change_line_price(Money new_price, { message: Низ })	Money	Променя цената на реда на зададената сума. Изисква се `message`. `new_price` трябва да е по-ниска от текущата цена.
.original_line_price	Money	Връща първоначалната цена на реда, преди да са приложени скриптове и отстъпки.
.line_price_was	Money	Връща цената на реда, преди да са приложени промени от текущия скрипт.
.line_price_changed?	Булев	Връща дали цената на реда се е променила.
.change_properties(хеш new_properties, { message: Низ })	Хеш	Задава нови свойства за ред. Първоначалният хеш със свойства се съхранява в `properties_was`, а хешът със свойства, който се предава на метода, се превръща в новите свойства за реда.
.properties_was	Хеш	Връща първоначалния хеш със свойства на реда, преди да са приложени каквито и да било промени.
.properties_changed?	Булев	Връща дали свойствата за реда са били променени.
.split({ take: Цяло число })	Ред	Разделя ред на два реда. `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	Money	Връща сравнителната цена на варианта. Връща `nil`, ако вариантът няма сравнителна цена.

Начини на доставка

Следните методи могат да се използват в скриптове за доставка:

Вход

Методи на скрипта, използващи обект Input в скриптове за доставка
Метод	Тип на връщаната стойност	Описание
.shipping_rates	Списък с тарифи за доставка	Връща списък с всички тарифи за доставка.

ShippingRateList

Методи на скрипта, използващи обекта ShippingRateList в скриптове за доставка
Метод	Тип на връщаната стойност	Описание
.delete_if	Списък с тарифи за доставка	Изтриване на тарифи за доставка с помощта на незадължителен кодов блок. Вижте документацията за метода `delete_if` на Ruby.
.sort!	Списък с тарифи за доставка	Сортиране на тарифите за доставка с помощта на оператора за сравнение или на незадължителен кодов блок. Вижте документацията за метода `sort!` на Ruby.
.sort_by!	Списък с тарифи за доставка	Сортиране на тарифите за доставка с помощта на незадължителен кодов блок. Вижте документацията за метода `sort_by!` на Ruby.

ShippingRate

Методи на скрипта, използващи обекта 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`, ако не се изисква.

Начини на плащане

Следните методи могат да се използват в платежни скриптове:

Вход

Методи на скрипта, използващи обекта 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	Списък<Низ>	Ако платежният шлюз поддържа кредитни карти, връща списък с типовете кредитни карти, които магазинът приема. Ако шлюзът не поддържа кредитни карти, връща празен списък.
.change_name(String new_name)	Низ	Променя името на платежния шлюз. Платежни шлюзове с лога не могат да бъдат преименувани.

Примери

В следващия пример за скрипт за ред от поръчка, когато клиент поръча продукт, който не е карта за подарък, цената на продукта се намалява с 9 USD. Освен това се показва общата сума, която клиентът е похарчил при всички посещения в магазина Ви:

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

Научете повече

Научете повече за: