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.

General methods

The following methods are usable in any type of script:

Input

Script input methods
MethodReturn typeDescription
.cartCartReturns a mutable cart object.
.localestringReturns 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.

Script methods using the Cart object
MethodReturn typeDescription
.customerCustomerReturns the owner of the cart (if any).
.shipping_addressShippingAddressReturns the shipping address of the owner of the cart (if any).
.discount_codevaries Returns:

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

See an example of discount_code.

.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_priceMoneyReturns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.
.total_weightgramsReturns the total weight of all the line items in the cart.

CartDiscount::FixedAmount

Script methods using the CartDiscount::FixedAmount object
MethodReturn typeDescription
.codeStringReturns the discount code used to apply the discount.
.amountMoneyReturns the money amount of the discount.
.reject({ message: String })nilRejects the discount code applied to the cart. A message is required.
.rejected?BooleanReturns whether the discount code was rejected.

CartDiscount::Percentage

Script methods using the CartDiscount::Percentage object
MethodReturn typeDescription
.codeStringReturns the discount code used to apply the discount.
.percentageDecimalReturns the percentage amount of the discount.
.reject({ message: String })nilRejects the discount code applied to the cart. A message is required.
.rejected?BooleanReturns whether the discount code was rejected.

CartDiscount::Shipping

Script methods using the CartDiscount::Shipping object
MethodReturn typeDescription
.codeStringReturns the discount code used to apply the discount.
.reject({ message: String })nilRejects the discount code applied to the cart. A message is required.
.rejected?BooleanReturns whether the discount code was rejected.

Customer

Script methods using the Customer object
MethodReturn typeDescription
.idIntegerReturns the customer's ID number.
.emailStringReturns the customer's email address.
.tags List<Tag>Returns a list of strings representing any tags set for a customer.
.orders_countIntegerReturns the total number of orders a customer has placed.
.total_spentMoneyReturns the total amount that the customer has spent on all orders.
.accepts_marketing?BooleanReturns whether the customer accepts marketing.

LineItem

Script methods using the LineItem object
MethodReturn typeDescription
.gramsgramsReturns the total weight of the line item.
.line_priceMoneyThe price of the line item.
.discounted?BooleanReturns 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.
.propertieshashReturns the properties that were specified for this line items.
.variantVariantReturns the specific product variant represented by the line item.
.quantityIntegerReturns the quantity of this line item.
.selling_plan_idIntegerReturns 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

Script methods using the List object
MethodReturn typeDescription
.newListCreates 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_ifListDelete elements using an optional code block. See the documentation for Ruby's delete_if method.
.empty?Boolean

Returns true if the list contains no elements.

.firstElement or nil

Returns the first element or nil if the list is empty.

.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.

.lastElement or nil

Returns the last element or nil if the list is empty.

.lengthint

Returns the number of elements in the list.

.sizeint

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

Script methods using the ShippingAddress object
MethodReturn typeDescription
.namestringReturns the name of the of the person associated with the shipping address.
.address1stringReturns the street address portion of the shipping address.
.address2stringReturns the optional additional field of the street address portion of the shipping address.
.phonestringReturns the phone number of the shipping address.
.citystringReturns the city of the shipping address.
.zipstringReturns the ZIP code of the shipping address.
.provincestringReturns the province/state of the shipping address.
.province_codestringReturns the abbreviated value of the province/state of the shipping address.
.country_codestringReturns the abbreviated value of the country of the shipping address.

Money

Script methods using the Money object
MethodReturn typeDescription
.derived_from_presentment(customer_cents:X)MoneyConverts 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).
.newMoneyCreates a new object to represent a price.
.zeroMoney

Creates a new object with a price of zero.

+MoneyAdds two Money objects.
-MoneySubtracts one Money object from another.
*MoneyMultiplies 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

Script methods using the Variant object
MethodReturn typeDescription
.idIntegerReturns the ID number of the variant.
.priceMoneyReturns the unit price of the variant.
.productProductReturns 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.
.titleStringReturns the title of the variant.

Product

Script methods using the Product object
MethodReturn typeDescription
.idIntegerReturns the ID number of the product.
.gift_card?BooleanReturns 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_typeStringA categorization that a product can be tagged with, commonly used for filtering and searching.
.vendorStringReturns 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.

Script methods using the Kernel object
MethodReturn typeDescription
.exitnoneEnds 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

Line item methods

The following methods are only usable in line item scripts:

Cart

Script methods using the Cart object in line item scripts
MethodReturn typeDescription
.subtotal_price_wasMoneyReturns the subtotal price of the cart before any discounts were applied.
.subtotal_price_changed?BooleanReturns whether the subtotal price has changed.

LineItem

Script methods using the LineItem object in line item scripts
MethodReturn typeDescription
.change_line_price(Money new_price, { message: String }) MoneyChange 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_priceMoneyReturns the original price of the line item before scripts and discounts were applied.
.line_price_wasMoneyReturns the price of the line item before changes were applied by the current script.
.line_price_changed?BooleanReturns whether the price of the line item has changed.
.change_properties(hash new_properties, { message: String }) hashSets 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_washashReturns the original properties hash of the line item before any changes were applied.
.properties_changed?BooleanReturns whether the properties for the line item have been changed.
.split({ take: Integer })LineItemSplits 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".

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

Script methods using the Variant object in line item scripts
MethodReturn typeDescription
.compare_at_priceMoneyReturns 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

Script methods using the Input object in shipping scripts
MethodReturn typeDescription
.shipping_ratesShippingRateListReturns a list of all the shipping rates.

ShippingRateList

Script methods using the ShippingRateList object in shipping scripts
MethodReturn typeDescription
.delete_ifShippingRateListDelete shipping rates using an optional code block. See the documentation for Ruby's delete_if method.
.sort!ShippingRateListSort the shipping rates using the comparison operator or using an optional code block. See the documentation for Ruby's sort! method.
.sort_by!ShippingRateListSort the shipping rates using an optional code block. See the documentation for Ruby's sort_by! method.

ShippingRate

Script methods using the ShippingRate object in shipping scripts
MethodReturn typeDescription
.codeStringReturns the code of the shipping rate.
.markupMoneyReturns the markup for a shipping rate, if applicable.
.nameStringReturns the name of the shipping rate. It can be modified by using the change_name method.
.priceMoneyReturns the price of the shipping rate.
.sourceStringReturns 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 })MoneyApplies a discount of the specified fixed amount. The price cannot be reduced below 0. A message is required.
.phone_required?BooleanReturns 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

Script methods using the Input object in payment scripts
MethodReturn typeDescription
.payment_gatewaysPaymentGatewaysListReturns a list of all the payment gateways in the store.

PaymentGatewayList

Script methods using the PaymentGatewayList object in payment scripts
MethodReturn typeDescription
.delete_ifPaymentGatewayListDelete payment gateways using an optional code block. See the documentation for Ruby's delete_if method.
.sort!PaymentGatewayListSort the payment gateways using the comparison operator or using an optional code block. See the documentation for Ruby's sort! method.
.sort_by!PaymentGatewayListSort the payment gateways using an optional code block. See the documentation for Ruby's sort_by! method.

PaymentGateway

MethodReturn typeDescription
.nameStringReturns 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)StringChanges 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:

Ready to start selling with Shopify?Try it free