Shopify Scripts API reference
Scripts are written with a Ruby API that gives you a great deal of control and flexibility.
There are different script types. A script is assigned a type when you create the script in the Script Editor app, based on which script template you choose to start with:
Line item scripts
Line item scripts affect line items in the cart and can change prices and grant discounts. These scripts are run when a change is made to the cart.
Line item scripts that discount a subscription apply only to the first payment of the subscription. Subsequent payments are not discounted by the script.
Some methods can only be used in line item scripts.
Shipping scripts
Shipping scripts interact with shipping, and can change shipping methods and grant discounts on shipping rates. These scripts run when the checkout reaches the shipping options page.
Shipping scripts that discount the rate of shipping a subscription apply only to the first payment of the subscription. Subsequent payments are not discounted by the script.
Some methods can only be used in shipping scripts.
Payment Scripts
Payment scripts interact with payments, and can rename, hide and reorder payment gateways. Note that payment scripts do not interact with payment gateways shown before the checkout screen, such as Apple Pay. These scripts are run when the checkout reaches the payment page.
Some methods can only be used in payment scripts.
On this page
General methods
The following methods are usable in any type of script:
Input
Method | Return type | Description |
---|---|---|
.cart | Cart | Returns a mutable cart object. |
.locale | string | Returns the customer's locale. For example, en , fr , or pt-BR . |
Cart
The cart object is only available on the online store. Some abandoned checkouts have access to the cart object. However, if a checkout has been closed and then a customer visits the abandoned checkout, it sends them to the pre-filled checkout and the cart object no longer exists. This is because the storefront has been bypassed by the abandoned checkout email.
Method | Return type | Description |
---|---|---|
.customer | Customer | Returns the owner of the cart (if any). |
.shipping_address | ShippingAddress | Returns the shipping address of the owner of the cart (if any). |
.discount_code | varies |
Returns:
|
.line_items | List<LineItem> | Returns a list containing the line items in the cart. |
.presentment_currency | List<String> | Returns the customer's local (presentment) currency (in ISO 4217 format). For example, USD. |
.subtotal_price | Money | Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied. |
.total_weight | grams | Returns the total weight of all the line items in the cart. |
CartDiscount::FixedAmount
Method | Return type | Description |
---|---|---|
.code | String | Returns the discount code used to apply the discount. |
.amount | Money | Returns the money amount of the discount. |
.reject({ message: String }) | nil | Rejects the discount code applied to the cart. A message is required. |
.rejected? | Boolean | Returns whether the discount code was rejected. |
CartDiscount::Percentage
Method | Return type | Description |
---|---|---|
.code | String | Returns the discount code used to apply the discount. |
.percentage | Decimal | Returns the percentage amount of the discount. |
.reject({ message: String }) | nil | Rejects the discount code applied to the cart. A message is required. |
.rejected? | Boolean | Returns whether the discount code was rejected. |
CartDiscount::Shipping
Method | Return type | Description |
---|---|---|
.code | String | Returns the discount code used to apply the discount. |
.reject({ message: String }) | nil | Rejects the discount code applied to the cart. A message is required. |
.rejected? | Boolean | Returns whether the discount code was rejected. |
Customer
Method | Return type | Description |
---|---|---|
.id | Integer | Returns the customer's ID number. |
String | Returns the customer's email address. | |
.tags | List<Tag> | Returns a list of strings representing any tags set for a customer. |
.orders_count | Integer | Returns the total number of orders a customer has placed. |
.total_spent | Money | Returns the total amount that the customer has spent on all orders. |
.accepts_marketing? | Boolean | Returns whether the customer accepts marketing. |
LineItem
Method | Return type | Description |
---|---|---|
.grams | grams | Returns the total weight of the line item. |
.line_price | Money | The price of the line item. |
.discounted? | Boolean | Returns whether the price of a line item has been discounted by a script or a manually applied discount. The use of discount codes doesn't affect the return value. |
.properties | hash | Returns the properties that were specified for this line items. |
.variant | Variant | Returns the specific product variant represented by the line item. |
.quantity | Integer | Returns the quantity of this line item. |
.selling_plan_id | Integer | Returns the ID of the selling plan for the line item. This method is useful when the store sells subscriptions and you want the script to detect when a product variant is sold as a subscription. |
List
Method | Return type | Description |
---|---|---|
.new | List | Creates a new object to represent a list. |
.[] | Element or nil |
Returns the element at the specified index. |
.& | List |
Returns a new list containing elements common to the two lists, with no duplicates. |
.delete_if | List | Delete elements using an optional code block. See the documentation for Ruby's delete_if method. |
.empty? | Boolean |
Returns |
.first | Element or nil |
Returns the first element or |
.index(*args, &block) | int or nil |
Returns the index of the first element of the list. If a block is given instead of an argument, returns the index of the first element for which the block is true. |
.rindex(*args, &block) | int or nil |
Returns the index of the last element of the list. If a block is given instead of an argument, returns the index of the first element for which the block is true. |
.last | Element or nil |
Returns the last element or |
.length | int |
Returns the number of elements in the list. |
.size | int |
Alias for length. |
.each(*args, &block) | List |
Calls a block once for each element in the list, passing the element as a parameter to the block. |
ShippingAddress
Method | Return type | Description |
---|---|---|
.name | string | Returns the name of the of the person associated with the shipping address. |
.address1 | string | Returns the street address portion of the shipping address. |
.address2 | string | Returns the optional additional field of the street address portion of the shipping address. |
.phone | string | Returns the phone number of the shipping address. |
.city | string | Returns the city of the shipping address. |
.zip | string | Returns the ZIP code of the shipping address. |
.province | string | Returns the province/state of the shipping address. |
.province_code | string | Returns the abbreviated value of the province/state of the shipping address. |
.country_code | string | Returns the abbreviated value of the country of the shipping address. |
Money
Method | Return type | Description |
---|---|---|
.derived_from_presentment(customer_cents:X) | Money | Converts an amount (in cents) from the customer's local (presentment) currency to your store's currency. This method accepts the customer_cents parameter, which accepts a number in cents. For example, Money.derived_from_presentment(customer_cents: 500) . |
.new | Money | Creates a new object to represent a price. |
.zero | Money |
Creates a new object with a price of zero. |
+ | Money | Adds two Money objects. |
- | Money | Subtracts one Money object from another. |
* | Money | Multiplies a Money object by a number. |
Money examples
Creates a Money
object representing 1000 cents, or $10.
Creates a Money
object representing $1, then multiplies that amount by 50. Returns a Money
object representing $50.
Variant
Method | Return type | Description |
---|---|---|
.id | Integer | Returns the ID number of the variant. |
.price | Money | Returns the unit price of the variant. |
.product | Product | Returns the associated product of the variant. |
.skus | List<String> | Returns the stock keeping units (SKUs) of the variant, which are often used for tracking inventory. |
.title | String | Returns the title of the variant. |
Product
Method | Return type | Description |
---|---|---|
.id | Integer | Returns the ID number of the product. |
.gift_card? | Boolean | Returns whether the product is a gift card. |
.tags | List<Tag> | Returns a list of strings representing the tags that are set for this product. |
.product_type | String | A categorization that a product can be tagged with, commonly used for filtering and searching. |
.vendor | String | Returns the vendor of this product. |
Kernel
Kernel is a Ruby module that is included in every class. As a result, its methods are available to every object. These methods act in the same way as global functions act in other languages.
Method | Return type | Description |
---|---|---|
.exit | none | Ends execution of the current script without error. If this is run before anything is assigned to Output.cart , the script has no effect. This is a useful way to exit scripts, for example, if the customer is ineligible to run the script. |
Kernel example
Line item methods
The following methods are only usable in line item scripts:
Cart
Method | Return type | Description |
---|---|---|
.subtotal_price_was | Money | Returns the subtotal price of the cart before any discounts were applied. |
.subtotal_price_changed? | Boolean | Returns whether the subtotal price has changed. |
LineItem
Method | Return type | Description |
---|---|---|
.change_line_price(Money new_price, { message: String }) | Money | Change the price of the line item to the amount specified. A message is required. new_price must be lower than the current price. |
.original_line_price | Money | Returns the original price of the line item before scripts and discounts were applied. |
.line_price_was | Money | Returns the price of the line item before changes were applied by the current script. |
.line_price_changed? | Boolean | Returns whether the price of the line item has changed. |
.change_properties(hash new_properties, { message: String }) | hash | Sets new properties for a line item. The original properties hash is stored in properties_was and the properties hash that is passed to the method becomes the new properties for the line item. |
.properties_was | hash | Returns the original properties hash of the line item before any changes were applied. |
.properties_changed? | Boolean | Returns whether the properties for the line item have been changed. |
.split({ take: Integer }) | LineItem | Splits a line item into two line items. take specifies what quantity to remove from the original line item to create the new line item. |
.split example
This example script splits a line item called original_line_item
into two line items. The new line item has a quantity of 1 (specified by take: 1
). The script then applies a discounted price to the new line item with the message "Third hat for 5 dollars".
Variant
Method | Return type | Description |
---|---|---|
.compare_at_price | Money | Returns the compare-at price of the variant. Returns nil if the variant doesn't have a compare-at price. |
Shipping methods
The following methods are usable in shipping scripts:
Input
Method | Return type | Description |
---|---|---|
.shipping_rates | ShippingRateList | Returns a list of all the shipping rates. |
ShippingRateList
Method | Return type | Description |
---|---|---|
.delete_if | ShippingRateList | Delete shipping rates using an optional code block. See the documentation for Ruby's delete_if method. |
.sort! | ShippingRateList | Sort the shipping rates using the comparison operator or using an optional code block. See the documentation for Ruby's sort! method. |
.sort_by! | ShippingRateList | Sort the shipping rates using an optional code block. See the documentation for Ruby's sort_by! method. |
ShippingRate
Method | Return type | Description |
---|---|---|
.code | String | Returns the code of the shipping rate. |
.markup | Money | Returns the markup for a shipping rate, if applicable. |
.name | String | Returns the name of the shipping rate. It can be modified by using the change_name method. |
.price | Money | Returns the price of the shipping rate. |
.source | String | Returns the source (the carrier) associated with the shipping rate, if relevant. It can't be modified. |
.change_name(String new_name) | String | Changes the name (maximum of 255 characters) of the shipping rate. It's not possible to change, delete or hide the source. |
.apply_discount(Money discount, { message: String }) | Money | Applies a discount of the specified fixed amount. The price cannot be reduced below 0. A message is required. |
.phone_required? | Boolean | Returns true if a phone number is required to get the shipping rate, or false if a phone number is not required. |
Payment methods
The following methods are usable in payment scripts:
Input
Method | Return type | Description |
---|---|---|
.payment_gateways | PaymentGatewaysList | Returns a list of all the payment gateways in the store. |
PaymentGatewayList
Method | Return type | Description |
---|---|---|
.delete_if | PaymentGatewayList | Delete payment gateways using an optional code block. See the documentation for Ruby's delete_if method. |
.sort! | PaymentGatewayList | Sort the payment gateways using the comparison operator or using an optional code block. See the documentation for Ruby's sort! method. |
.sort_by! | PaymentGatewayList | Sort the payment gateways using an optional code block. See the documentation for Ruby's sort_by! method. |
PaymentGateway
Method | Return type | Description |
---|---|---|
.name | String | Returns the name of the payment gateway. |
.enabled_card_brands | List<String> |
If the payment gateway supports credit cards, returns a list of the credit card types that the store accepts. If the gateway doesn't support credit cards, returns an empty list. |
.change_name(String new_name) | String | Changes the name of the payment gateway. Payment gateways with logos can't be renamed. |
Examples
In the following line item script example, when a customer orders a product that is not a gift card, then the price of the product is reduced by $9. Also, the total amount that the customer has spent throughout all visits to your store is shown:
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
Learn more
Learn more about: