Shopify Scripts

The Script Editor app lets you create scripts that are run each time a customer adds items to their cart. Scripts can have many uses, from discounting products with specific tags to running promotions such as "buy 2, get 1 free". Scripts are written with a Ruby API that allows a great deal of control and flexibility.

Are you unfamiliar with Ruby? Learn the basics ›

Did you know?

Scripts and the Script Editor app are available to Shopify Plus merchants only.

Input

Method Return type Description
.cart Cart Returns a mutable cart object.

Cart

Method Return type Description
.customer Customer Returns the owner of the cart (if any).
.discount_code varies Returns:

discount_code will be present if a discount has been applied to the cart. This does not necessarily mean that the price of the cart will change. For example, if a discount applies to carts above $50, and a script reduces the cart price below $50, discount_code will be present but the price of the cart will not change.

See an example of discount_code.

.line_items array Returns an array containing the line items in the cart.
.subtotal_price Money Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.
.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.

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 integer 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.
.email string Returns the customer's email address.
.tags array Returns an array 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
.line_price Money The price of the line item.
.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.
.discounted? boolean Returns whether a discount has changed the price of the line item.
.line_price_changed? boolean Returns whether the price of the line item has changed.
.properties hash Returns the properties that were specified for this line items.
.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.
.variant Variant Returns the specific product variant represented by the line item.
.quantity integer Returns the quantity of this line item.
.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

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

This example script splits a line item called original_line_item into two line items. The new line item will have 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".

Money

Method Return type Description
.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

Money.new(cents: 1000)

Creates a Money object representing 1000 cents, or $10.

Money.new(cents: 100) * 50

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.
.compare_at_price Money Returns the compare at price of the variant. Returns nil if the variant doesn't have a compare at price.
.skus array Returns the stock keeping units (SKUs) of the variant, which are often used for tracking inventory.
.product Product Returns the associated product 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 array 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

customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end