API-naslaghandleiding voor Shopify-scripts

Scripts worden geschreven met een Ruby-API die een grote mate van controle en flexibiliteit mogelijk maakt.

Abonnementvereiste

Shopify-scripts en de Script Editor-app zijn alleen beschikbaar voor winkels waarvoor je een Shopify Plus-abonnement hebt. Je kunt de Script Editor-app niet langer downloaden in de Shopify App Store.

Op 28 augustus 2025 worden Shopify-scripts verwijderd en zullen ze niet meer werken. Migreer je bestaande scripts vóór deze datum naar Shopify Functions.

Er zijn verschillende soorten scripts. Aan een script wordt een type toegewezen wanneer je het script in de Script Editor-app maakt. Het type wordt bepaald op basis van de scripttemplate die je kiest als uitgangspunt:

Orderregelscripts

Orderregelscripts zijn van invloed op orderregels in de winkelwagen en kunnen prijzen en kortingen wijzigen. Deze scripts worden uitgevoerd wanneer er een wijziging in de winkelwagen wordt doorgevoerd.

Orderregelscripts die korting geven op een abonnement gelden alleen voor de eerste betaling van het abonnement. Op daaropvolgende betalingen wordt geen korting toegepast door het script.

Sommige methoden kunnen alleen worden gebruikt in regelartikelscripts.

Verzendscripts

Verzendscripts hebben betrekking op verzending en kunnen verzendmethoden wijzigen en kortingen op verzendtarieven verlenen. Deze scripts worden uitgevoerd wanneer tijdens de checkout de pagina met verzendopties is bereikt.

Verzendscripts die korting geven op de verzendtarieven van een abonnement gelden alleen voor de eerste betaling van het abonnement. Op daaropvolgende betalingen wordt geen korting toegepast door het script.

Sommige methoden kunnen alleen in verzendscripts worden gebruikt.

Betalingsscripts

Betalingsscripts hebben betrekking op betalingen en kunnen betalingsgateways hernoemen, verbergen en opnieuw ordenen. Houd er rekening mee dat betalingsscripts geen betrekking hebben op betalingsgateways die vóór het betaalscherm worden weergegeven, zoals Apple Pay. Deze scripts worden uitgevoerd wanneer tijdens het afrekenen de betaalpagina is bereikt.

Sommige methoden kunnen alleen worden gebruikt in betalingsscripts.

Algemene methoden

De volgende methoden kunnen in elk type script worden gebruikt:

Invoer

Invoermethoden voor scripts

Wijze	Retourobject	Beschrijving
.cart	Winkelwagen	Retourneert een veranderlijk winkelwagenobject.
.locale	string	Zet de landinstellingen van de klant terug. Bijvoorbeeld: en, fr of pt-BR.

Winkelwagen

Het cart-object is alleen beschikbaar in de webshop. Sommige afgebroken checkouts hebben toegang tot het cart-object. Als een checkout echter is afgesloten en een klant vervolgens naar de afgebroken checkout gaat, wordt de klant naar de vooraf ingevulde checkout gestuurd en bestaat het cart-object niet meer. Dit komt omdat de webwinkel is overgeslagen door de e-mail over een afgebroken checkout.

Scriptmethoden met behulp van het Cart-object

Wijze	Retourobject	Beschrijving
.customer	Klant	Retourneert de eigenaar van de winkelwagen (indien aanwezig).
.shipping_address	Bezorgadres	Retourneert het bezorgadres van de eigenaar van de winkelwagen (indien aanwezig).
.discount_code	varieert	Retourzendingen nil als de winkelwagen geen kortingscode heeft CartDiscount::FixedAmount als er een vast kortingsbedrag is gekoppeld aan de winkelwagen CartDiscount::Percentage als er een kortingspercentage is gekoppeld aan de winkelwagen CartDiscount::Shipping als de winkelwagen een verzendkorting heeft Retourneert één kortingscode (zie Beperkingen) discount_code is aanwezig als er een korting op de winkelwagen is toegepast. Dit betekent niet altijd dat de prijs van de winkelwagen verandert. Als een korting bijvoorbeeld van toepassing is op winkelwagens van meer dan $ 50, en een script de prijs van de winkelwagen verlaagt tot minder dan $ 50, is discount code nog steeds aanwezig, maar blijft de prijs van de winkelwagen onveranderd. Bekijk een voorbeeld van discount_code.
.line_items	List<LineItem>	Retourneert een lijst met de orderregels in de winkelwagen.
.presentment_currency	List<String>	Retourneert de lokale valuta (presentatievaluta) van de klant (in ISO 4217-indeling), bijvoorbeeld USD.
.subtotal_price	Geld	Retourneert de subtotaalprijs van de winkelwagen nadat kortingen op regelniveau zijn toegepast, maar voordat kortingscodes zijn toegepast.
.total_weight	grams	Retourneert het totale gewicht van alle orderregels in de winkelwagen.

CartDiscount::FixedAmount

Scriptmethoden met behulp van het CartDiscount::FixedAmount-object

Wijze	Retourobject	Beschrijving
.code	String	Retourneert de kortingscode die wordt gebruikt om de korting toe te passen.
.amount	Geld	Retourneert het geldbedrag van de korting.
.reject({ message: String })	nil	Weigert de kortingscode die op de winkelwagen is toegepast. Je moet een bericht opgeven bij message.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

CartDiscount::Percentage

Scriptmethoden met behulp van de CartDiscount::Percentage-object

Wijze	Retourobject	Beschrijving
.code	String	Retourneert de kortingscode die wordt gebruikt om de korting toe te passen.
.percentage	Decimaal	Retourneert het percentagebedrag van de korting.
.reject({ message: String })	nil	Weigert de kortingscode die op de winkelwagen is toegepast. Je moet een bericht opgeven bij message.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

CartDiscount::Shipping

Scriptmethoden met behulp van de CartDiscount::Shipping-object

Wijze	Retourobject	Beschrijving
.code	String	Retourneert de kortingscode die wordt gebruikt om de korting toe te passen.
.reject({ message: String })	nil	Weigert de kortingscode die op de winkelwagen is toegepast. Je moet een bericht opgeven bij message.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

Klant

Scriptmethoden met behulp van het klant-object

Wijze	Retourobject	Beschrijving
.id	Geheel getal	Retourneert het ID-nummer van de klant.
.email	String	Retourneert het e-mailadres van de klant.
.tags	List<Tag>	Retourneert een lijst met reeksen die alle tags voorstellen die voor een klant zijn ingesteld.
.orders_count	Geheel getal	Retourneert het totale aantal bestellingen dat een klant heeft geplaatst.
.total_spent	Geld	Retourneert het totale bedrag dat de klant aan alle bestellingen heeft uitgegeven.
.accepts_marketing?	Boolean	Retourneert of de klant marketing accepteert.

LineItem

<tdgrams

Scriptmethoden met behulp van het line item-object

Wijze	Retourobject	Beschrijving
.grams	Retourneert het totale gewicht van de orderregel.
.line_price	Geld	De prijs van de orderregel.
.discounted?	Boolean	Retourneert of de prijs van een orderregel nu is afgeprijsd door een script of door een handmatig toegepaste korting. Het gebruik van kortingscodes heeft geen invloed op de retourwaarde.
.properties	hash	Retourneert de eigenschappen die zijn opgegeven voor dit orderregel.
.variant	Variant	Retourneert de specifieke productvariant die wordt aangegeven door de orderregel.
.quantity	Geheel getal	Retourneert de hoeveelheid van dit orderregel.
.selling_plan_id	Geheel getal	Retourneert de ID van het verkoopplan voor de orderregel. Deze methode is handig wanneer de winkel abonnementen verkoopt en je wilt dat het script detecteert wanneer een productvariant als een abonnement wordt verkocht.

Lijst

Scriptmethoden met behulp van het List-object

Wijze	Retourobject	Beschrijving
.new	Lijst	Maakt een nieuw object om een lijst voor te stellen.
.[]	Element of nil	Retourneert het element bij de opgegeven index.
.&	Lijst	Retourneert een nieuwe lijst met elementen die voorkomen in de twee lijsten, zonder duplicaten.
.delete_if	Lijst	Elementen verwijderen met behulp van een optioneel codeblok. Raadpleeg de documentatie voor de delete_if-methode van Ruby.
.empty?	Boolean	Retourneert true als de lijst geen elementen bevat.
.first	Element of nil	Retourneert het eerste element of nil als de lijst leeg is.
.index(*args, &block)	int of nil	Retourneert de index van het eerste element van de lijst. Als er een blok wordt opgegeven in plaats van een argument, wordt de index geretourneerd van het eerste element waarvoor het blok waar is.
.rindex(*args, &block)	int of nil	Retourneert de index van het laatste element van de lijst. Als er een blok wordt opgegeven in plaats van een argument, wordt de index geretourneerd van het eerste element waarvoor het blok waar is.
.last	Element of nil	Retourneert het laatste element of nil als de lijst leeg is.
.length	int	Retourneert het aantal elementen in de lijst.
.size	int	Alias voor lengte.
.each(*args, &block)	Lijst	Roept een blok eenmaal aan voor elk element in de lijst, waarbij het element als een parameter aan het blok wordt doorgegeven.

Bezorgadres

Scriptmethoden met behulp van het ShippingAddress-object

Wijze	Retourobject	Beschrijving
.name	tekenreeks	Retourneert de naam van de persoon die aan het bezorgadres is gekoppeld.
.address1	tekenreeks	Retourneert de straatnaam uit het bezorgadres.
.address2	tekenreeks	Retourneert het optionele extra veld van het straatadresgedeelte uit het bezorgadres.
.phone	tekenreeks	Retourneert het telefoonnummer uit het bezorgadres.
.city	tekenreeks	Retourneert de plaats uit het bezorgadres.
.zip	tekenreeks	Retourneert de postcode uit het bezorgadres.
.province	tekenreeks	Retourneert de provincie/staat uit het bezorgadres.
.province_code	tekenreeks	Retourneert de afgekorte waarde van de provincie/staat uit het bezorgadres.
.country_code	tekenreeks	Retourneert de afgekorte waarde van het land uit het bezorgadres.

Geld

Scriptmethoden met behulp van het Money-object

Wijze	Retourobject	Beschrijving
.derived_from_presentment(customer_cents:X)	Geld	Converteert een bedrag (in centen) van de lokale valuta (presentatievaluta) van de klant naar de valuta van je winkel. Deze methode accepteert de parameter customer_cents, die een waarde uitgedrukt in centen accepteert. Bijvoorbeeld: Money.derived_from_presentment(customer_cents: 500).
.new	Geld	Maakt een nieuw object om een prijs te vertegenwoordigen.
.zero	Geld	Maakt een nieuw object met een prijs van nul.
+	Geld	Voegt twee Money-objecten toe.
-	Geld	Trekt het ene Money-object van het andere af.
*	Geld	Vermenigvuldigt een Money-object.

Voorbeelden met Money

Money.new(cents: 1000)

Creëert een Money object dat 1000 cent vertegenwoordigt, ofwel $ 10.

Money.new(cents: 100) * 50

Maakt een Money-object dat $ 1 vertegenwoordigt, en vermenigvuldigt dat bedrag vervolgens met 50. Retourneert a Money-object dat $ 50 vertegenwoordigt.

Variant

Scriptmethoden met behulp van het variant-object

Wijze	Retourobject	Beschrijving
.id	Geheel getal	Retourneert het ID-nummer van de variant.
.price	Geld	Retourneert de eenheidsprijs van de variant.
.product	Product	Retourneert het bijbehorende product van de variant.
.skus	List<String>	Retourneert de SKU's van de variant, die vaak worden gebruikt voor het bijhouden van voorraad.
.title	String	Retourneert de titel van de variant.

Product

Scriptmethoden met behulp van het product-object

Wijze	Retourobject	Beschrijving
.id	Geheel getal	Retourneert het ID-nummer van het product.
.gift_card?	Boolean	Retourneert of het product een cadeaubon is.
.tags	List<Tag>	Retourneert een lijst met tekenreeksen die de tags vertegenwoordigen die voor dit product zijn ingesteld.
.product_type	String	Een categorisatie waarmee een product kan worden getagd, meestal gebruikt voor filteren en zoeken.
.vendor	String	Retourneert de leverancier van dit product.

Kernel

Kernel is een Ruby-module die in elke klasse is opgenomen. Hierdoor zijn de methoden van de module beschikbaar voor elk object. Deze methoden werken op dezelfde manier als algemene functies in andere talen.

Scriptmethoden met behulp van het kernel-object

Wijze	Retourobject	Beschrijving
.exit	geen	Beëindigt de uitvoering van het huidige script zonder fouten. Als dit wordt uitgevoerd voordat er iets is toegewezen aan Output.cart, heeft het script geen effect. Dit is een handige manier om scripts af te sluiten, bijvoorbeeld als de klant niet in aanmerking komt om het script uit te voeren.

Kernel-voorbeeld

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

Methoden voor orderregels

De volgende methoden zijn alleen bruikbaar in regelartikelscripts:

Winkelwagen

Scriptmethoden met behulp van het Cart-object in scripts met regelitems

Wijze	Retourobject	Beschrijving
.subtotal_price_was	Geld	Retourneert de subtotaalprijs van de winkelwagen voordat eventuele kortingen werden toegepast.
.subtotal_price_changed?	Boolean	Retourneert of de subtotaalprijs is gewijzigd.

LineItem

Scriptmethoden met behulp van het line item-object in scripts met regelitems

Wijze	Retourobject	Beschrijving
.change_line_price(Money new_price, { message: String })	Geld	Wijzig de prijs van de orderregel in het opgegeven bedrag. Je moet een bericht opgeven bij message. new_price moet lager zijn dan de huidige prijs.
.original_line_price	Geld	Retourneert de oorspronkelijke prijs van de orderregel voordat scripts en kortingen werden toegepast.
.line_price_was	Geld	Retourneert de prijs van de orderregel voordat wijzigingen door het huidige script werden toegepast.
.line_price_changed?	Boolean	Retourneert of de prijs van de orderregel is gewijzigd.
.change_properties(hash new_properties, { message: String })	hash	Stelt nieuwe eigenschappen in voor een regelartikel. De hash van de oorspronkelijke eigenschappen wordt opgeslagen in properties_was en de hash van de eigenschappen die wordt doorgegeven aan de methode wordt de nieuwe eigenschappen-hash voor de orderregel.
.properties_was	hash	Retourneert de hash van de oorspronkelijke eigenschappen van de orderregel voordat eventuele wijzigingen werden toegepast.
.properties_changed?	Boolean	Retourneert of de eigenschappen voor de orderregel zijn gewijzigd.
.split({ take: Integer })	LineItem	Splitst een orderregel op in twee orderregels. take geeft aan welke hoeveelheid moet worden verwijderd van de oorspronkelijke orderregel om de nieuwe orderregel te maken.

Voorbeeld met .split

Dit voorbeeldscript splitst een regelartikel met de naam original_line_item in twee regelartikelen. Het nieuwe regelartikel heeft een hoeveelheid van 1 (opgegeven door take: 1). Het script past vervolgens een kortingsprijs toe op het nieuwe regelartikel met het bericht '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

Scriptmethoden met behulp van het variant-object in scripts voor orderregels

Wijze	Retourobject	Beschrijving
.compare_at_price	Geld	Retourneert de prijsvergelijking van de variant. Retourneert nil als de variant geen prijsvergelijking bevat.

Verzendmethoden

De volgende methoden kunnen worden gebruikt in verzendscripts:

Invoer

Scriptmethoden met behulp van het input-object in scripts met verzending

Wijze	Retourobject	Beschrijving
.shipping_rates	ShippingRateList	Retourneert een lijst met alle verzendtarieven.

ShippingRateList

Scriptmethoden met behulp van het ShippingRateList-object in scripts met verzending

Wijze	Retourobject	Beschrijving
.delete_if	ShippingRateList	Verzendtarieven verwijderen met een optioneel codeblok. Zie de documentatie voor de delete_if-methode van Ruby.
.sort!	ShippingRateList	De verzendtarieven sorteren met behulp van de vergelijkingsoperator of met behulp van een optioneel codeblok. Zie de documentatie voor de sort!-methode van Ruby.
.sort_by!	ShippingRateList	De verzendtarieven sorteren met behulp van een optioneel codeblok. Zie de documentatie voor de sort_by!-methode van Ruby.

ShippingRate

Scriptmethoden met behulp van het ShippingRate-object in scripts met verzending

Wijze	Retourobject	Beschrijving
.code	String	Retourneert de code van het verzendtarief.
.markup	Geld	Retourneert de prijsopslag voor een verzendtarief, indien van toepassing.
.name	String	Retourneert de naam van het verzendtarief. Deze kan met de methode change_name worden gewijzigd.
.price	Geld	Retourneert de prijs van het verzendtarief.
.source	String	Retourneert de bron (de vervoerder) die aan het verzendtarief is gekoppeld, indien relevant. Deze kan niet worden gewijzigd.
.change_name(String new_name)	String	Wijzigt de naam (maximaal 255 tekens) van het verzendtarief. Het is niet mogelijk om de bron te wijzigen, te verwijderen of te verbergen.
.apply_discount(Money discount, { message: String })	Geld	Past een korting toe in de vorm van het opgegeven vaste bedrag. De prijs kan niet lager zijn dan 0. Je moet een bericht opgeven bij message.
.phone_required?	Boolean	Retourneert true als een telefoonnummer nodig is om het verzendtarief op te vragen of false als hiervoor geen telefoonnummer nodig is.

Betaalmethoden

De volgende methoden zijn bruikbaar in betalingsscripts:

Invoer

Scriptmethoden met behulp van het invoer object in scripts met betalingen

Wijze	Retourobject	Beschrijving
.payment_gateways	PaymentGatewaysList	Retourneert een lijst met alle betalingsgateways in de winkel.

PaymentGatewayList

Scriptmethoden met behulp van het PaymentGatewayList-object in scripts met betalingen

Wijze	Retourobject	Beschrijving
.delete_if	PaymentGatewayList	Betalingsgateways verwijderen met behulp van een optioneel codeblok. Zie de documentatie voor de delete_if-methode van Ruby.
.sort!	PaymentGatewayList	De betalingsgateways sorteren met behulp van de vergelijkingsoperator of met behulp van een optioneel codeblok. Zie de documentatie voor de sort!-methode van Ruby.
.sort_by!	PaymentGatewayList	De betalingsgateway sorteren met behulp van een optioneel codeblok. Zie de documentatie voor de sort_by!-methode van Ruby.

PaymentGateway

Wijze	Retourobject	Beschrijving
.name	String	Retourneert de naam van de betalingsgateway.
.enabled_card_brands	List<String>	Als de betalingsgateway creditcards ondersteunt, wordt er een lijst geretourneerd met de creditcards die de winkel accepteert. Als de gateway geen creditcards ondersteunt, wordt er een lege lijst geretourneerd.
.change_name(String new_name)	String	Wijzigt de naam van de betalingsgateway. De naam van betalingsgateways met logo's kan niet worden gewijzigd.

Voorbeelden

Als in het volgende voorbeeld van een regelartikelscript een klant een product bestelt dat geen cadeaubon is, wordt de prijs van het product verlaagd met $ 9. Ook wordt het totale bedrag weergegeven dat de klant tijdens alle bezoeken aan je winkel heeft uitgegeven:

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

Meer informatie

Meer informatie over:

• De basisbeginselen van Ruby
• Scripts maken
• Scripts testen en debuggen
• Liquid-templates voor scripts bijwerken
• Shopify-scripts