Referentie voor Shopify Scripts-API

Scripts worden geschreven met een Ruby-API die je veel controle en flexibiliteit geeft.

Abonnementsvereiste

Shopify-scripts en de Script Editor-app zijn alleen beschikbaar voor winkels met een Shopify Plus-abonnement. De Script Editor-app is niet meer te downloaden in de Shopify App Store.

Op 30 juni 2026 worden Shopify-scripts verwijderd en werken ze niet meer. Als je doorlopende ondersteuning wilt voor je bestaande Shopify Scripts-gebruiksscenario's, moet je overstappen op compatibele Shopify Functions-vervangingen voor je bestaande betalings-, verzend- of orderregelscripts. Meer informatie over de overstap van Shopify-scripts naar Shopify Functions.

Er zijn verschillende scripttypen. Een script krijgt een type toegewezen wanneer je het script aanmaakt in de Script Editor-app. Dit is gebaseerd op de scripttemplate waarmee je begint:

Orderregelscripts

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

Orderregelscripts die korting geven op een abonnement, zijn alleen van toepassing op de eerste betaling van het abonnement. Volgende betalingen krijgen geen korting van het script.

Sommige methoden kunnen alleen in orderregelscripts worden gebruikt.

Verzendscripts

Verzendscripts hebben interactie met verzending en kunnen verzendmethoden wijzigen en kortingen geven op verzendtarieven. Deze scripts worden uitgevoerd wanneer de checkout de pagina met verzendopties bereikt.

Verzendscripts die korting geven op de verzendkosten van een abonnement, zijn alleen van toepassing op de eerste betaling van het abonnement. Volgende betalingen krijgen geen korting van het script.

<p>Some methods <a href="#shipping-methods">can only be used in shipping scripts</a>.</p>

Betalingsscripts

Betalingsscripts hebben interactie met betalingen en kunnen betalingsgateways hernoemen, verbergen en opnieuw rangschikken. Betalingsscripts hebben geen interactie met betalingsgateways die vóór het checkoutscherm worden weergegeven, zoals Apple Pay. Deze scripts worden uitgevoerd wanneer de checkout de betalingspagina bereikt.

Sommige methoden kunnen alleen in betalingsscripts worden gebruikt.

Algemene methoden

De volgende methoden kunnen in elk type script worden gebruikt:

Invoer

Invoermethoden voor scripts

Methode	Retourtype	Omschrijving
.cart	Winkelwagen	Retourneert een muteerbaar winkelwagenobject.
.locale	tekenreeks	Retourneert de landinstelling van de klant. Bijvoorbeeld en, fr of pt-BR.

Winkelwagen

Het winkelwagenobject is alleen beschikbaar in de webshop. Sommige afgebroken checkouts hebben toegang tot het winkelwagenobject. Als een checkout echter is gesloten en een klant vervolgens de afgebroken checkout bezoekt, wordt deze doorgestuurd naar de vooraf ingevulde checkout en bestaat het winkelwagenobject niet meer. Dit komt doordat de webshop is omzeild via de e-mail over de afgebroken checkout.

Scriptmethoden die het winkelwagenobject gebruiken

Methode	Retourtype	Omschrijving
.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	variabel	Retourneert: nil als de winkelwagen geen kortingscode heeft CartDiscount::FixedAmount als de winkelwagen een vast kortingsbedrag heeft CartDiscount::Percentage als de winkelwagen een percentuele korting heeft CartDiscount::Shipping als de winkelwagen een verzendkorting heeft Retourneert één kortingscode (zie Beperkingen) discount_code is aanwezig als er een korting is toegepast op de winkelwagen. Dit betekent niet noodzakelijkerwijs dat de prijs van de winkelwagen verandert. Als er bijvoorbeeld een korting geldt voor winkelwagens boven de $ 50 en een script de winkelwagenprijs verlaagt tot onder de $ 50, is de discount_code nog steeds aanwezig, maar verandert de prijs van de winkelwagen niet. <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>&lt;LineItem&gt;</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>&lt;String&gt;</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

Scriptmethoden die het object CartDiscount::FixedAmount gebruiken

Methode	Retourtype	Omschrijving
.code	Tekenreeks	Retourneert de kortingscode die is gebruikt om de korting toe te passen.
.amount	Geld	Retourneert het geldbedrag van de korting.
.reject({ message: String })	nil	Wijst de kortingscode af die op de winkelwagen is toegepast. Een message is vereist.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

CartDiscount::Percentage

Scriptmethoden die het object CartDiscount::Percentage gebruiken

Methode	Retourtype	Omschrijving
.code	Tekenreeks	Retourneert de kortingscode die is gebruikt om de korting toe te passen.
.percentage	Decimaal	Retourneert het percentage van de korting.
.reject({ message: String })	nil	Wijst de kortingscode af die op de winkelwagen is toegepast. Een message is vereist.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

CartDiscount::Shipping

Scriptmethoden die het CartDiscount::Shipping-object gebruiken

Methode	Retourtype	Omschrijving
.code	Tekenreeks	Retourneert de kortingscode die is gebruikt om de korting toe te passen.
.reject({ message: String })	nil	Wijst de kortingscode af die op de winkelwagen is toegepast. Een message is vereist.
.rejected?	Boolean	Retourneert of de kortingscode is afgewezen.

Klant

Scriptmethoden die het Klant-object gebruiken

Methode	Retourtype	Omschrijving
.id	Integer	Retourneert het ID-nummer van de klant.
.email	Tekenreeks	Retourneert het e-mailadres van de klant.
.tags	List<Tag>	Retourneert een lijst met tekenreeksen die de voor een klant ingestelde tags vertegenwoordigen.
.orders_count	Integer	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.

Orderregel

Scriptmethoden die het Orderregel-object gebruiken

Methode	Retourtype	Omschrijving
.grams	gram	Retourneert het totale gewicht van de orderregel.
.line_price	Geld	De prijs van de orderregel.
.discounted?	Boolean	Retourneert of de prijs van een orderregel is verlaagd door een script of een handmatig toegepaste korting. Het gebruik van kortingscodes heeft geen invloed op de retourwaarde.
.properties	hash	Retourneert de eigenschappen die voor deze orderregel zijn opgegeven.
.variant	Variant	Retourneert de specifieke productvariant die door de orderregel wordt vertegenwoordigd.
.quantity	Integer	Retourneert de hoeveelheid van deze orderregel.
.selling_plan_id	Integer	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 abonnement wordt verkocht.

List

Scriptmethoden die het List-object gebruiken

Methode	Retourtype	Omschrijving
.new	List	Maakt een nieuw object aan dat een lijst vertegenwoordigt.
.[]	Element of nil	Retourneert het element op de opgegeven index.
.&	List	Retourneert een nieuwe lijst met elementen die de twee lijsten gemeen hebben, zonder duplicaten.
.delete_if	List	Verwijdert elementen met behulp van een optioneel codeblok. Zie 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 van het eerste element geretourneerd 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 van het eerste element geretourneerd 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 length.
.each(*args, &block)	List	Roept een blok één keer aan voor elk element in de lijst en geeft het element als parameter door aan het blok.

Bezorgadres

Scriptmethoden die het Bezorgadres-object gebruiken

Methode	Retourtype	Omschrijving
.name	tekenreeks	Retourneert de naam van de persoon die aan het bezorgadres is gekoppeld.
.address1	tekenreeks	Retourneert het straatadresgedeelte van het bezorgadres.
.address2	tekenreeks	Retourneert het optionele extra adresveld van het bezorgadres.
.phone	tekenreeks	Retourneert het telefoonnummer van het bezorgadres.
.city	tekenreeks	Retourneert de plaats van het bezorgadres.
.zip	tekenreeks	Retourneert de postcode van het bezorgadres.
.province	tekenreeks	Retourneert de provincie/staat van het bezorgadres.
.province_code	tekenreeks	Retourneert de afgekorte waarde van de provincie/staat van het bezorgadres.
.country_code	tekenreeks	Retourneert de afgekorte waarde van het land van het bezorgadres.

Money

Scriptmethoden die het Money-object gebruiken

Methode	Retourtype	Omschrijving
.derived_from_presentment(customer_cents:X)	Geld	Zet een bedrag (in centen) om van de lokale (gepresenteerde) valuta van de klant naar de valuta van je winkel. Deze methode accepteert de parameter customer_cents, die een getal in centen accepteert. Bijvoorbeeld: Money.derived_from_presentment(customer_cents: 500).
.new	Geld	Maakt een nieuw object aan dat een prijs vertegenwoordigt.
.zero	Geld	Maakt een nieuw object aan met een prijs van nul.
+	Geld	Telt twee Money-objecten bij elkaar op.
-	Geld	Trekt één Money-object van een ander af.
*	Geld	Vermenigvuldigt een Money-object met een getal.

Money-voorbeelden

Money.new(cents: 1000)

Maakt een Money-object aan dat 1000 cent (oftewel $ 10) vertegenwoordigt.

Money.new(cents: 100) * 50

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

Variant

Scriptmethoden die het object Variant gebruiken

Methode	Retourtype	Omschrijving
.id	Integer	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 (stock keeping units) van de variant, die vaak worden gebruikt om de voorraad bij te houden.
.title	Tekenreeks	Retourneert de titel van de variant.

Product

Scriptmethoden die het object Product gebruiken

Methode	Retourtype	Omschrijving
.id	Integer	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	Tekenreeks	Een categorisering waarmee een product kan worden getagd, die vaak wordt gebruikt voor filteren en zoeken.
.vendor	Tekenreeks	Retourneert de verkoper van dit product.

Kernel

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

Scriptmethoden die het object Kernel gebruiken

Methode	Retourtype	Omschrijving
.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 orderregelscripts:

Winkelwagen

Scriptmethoden die het object Cart gebruiken in orderregelscripts

Methode	Retourtype	Omschrijving
.subtotal_price_was	Geld	Retourneert de subtotaalprijs van de winkelwagen voordat er kortingen werden toegepast.
.subtotal_price_changed?	Boolean	Retourneert of de subtotaalprijs is gewijzigd.

Orderregel

Scriptmethoden die het object LineItem gebruiken in orderregelscripts

Methode	Retourtype	Omschrijving
.change_line_price(Money new_price, { message: String })	Geld	Wijzigt de prijs van de orderregel naar het opgegeven bedrag. Een message is vereist. 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 het huidige script wijzigingen toepaste.
.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 orderregel. De oorspronkelijke hash met eigenschappen wordt opgeslagen in properties_was en de hash met eigenschappen die aan de methode wordt doorgegeven, vormt de nieuwe eigenschappen voor de orderregel.
.properties_was	hash	Retourneert de oorspronkelijke hash met eigenschappen van de orderregel voordat er wijzigingen werden toegepast.
.properties_changed?	Boolean	Retourneert of de eigenschappen voor de orderregel zijn gewijzigd.
.split({ take: Integer })	LineItem	Splitst een orderregel in twee orderregels. take geeft aan welke hoeveelheid uit de oorspronkelijke orderregel moet worden verwijderd om de nieuwe orderregel aan te maken.

.split-voorbeeld

Dit voorbeeldscript splitst een orderregel met de naam original_line_item in twee orderregels. De nieuwe orderregel heeft een hoeveelheid van 1 (opgegeven door take: 1). Het script past vervolgens een kortingsprijs toe op de nieuwe orderregel 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 die het object Variant gebruiken in orderregelscripts

Methode	Retourtype	Omschrijving
.compare_at_price	Geld	Retourneert de vergelijkingsprijs van de variant. Retourneert nil als de variant geen vergelijkingsprijs heeft.

Verzendmethoden

De volgende methoden zijn bruikbaar in verzendscripts:

Invoer

Scriptmethoden die het object Input gebruiken in verzendscripts

Methode	Retourtype	Omschrijving
.shipping_rates	ShippingRateList	Geeft een lijst met alle verzendtarieven terug.

ShippingRateList

Scriptmethoden die het ShippingRateList-object gebruiken in verzendscripts

Methode	Retourtype	Omschrijving
.delete_if	ShippingRateList	Verwijdert verzendtarieven met een optioneel codeblok. Zie de documentatie voor de delete_if-methode van Ruby.
.sort!	ShippingRateList	Sorteert de verzendtarieven met de vergelijkingsoperator of met een optioneel codeblok. Zie de documentatie voor de sort!-methode van Ruby.
.sort_by!	ShippingRateList	Sorteert de verzendtarieven met een optioneel codeblok. Zie de documentatie voor de sort_by!-methode van Ruby.

ShippingRate

Scriptmethoden die het ShippingRate-object gebruiken in verzendscripts

Methode	Retourtype	Omschrijving
.code	Tekenreeks	Geeft de code van het verzendtarief terug.
.markup	Geld	Geeft de prijsopslag voor een verzendtarief terug, indien van toepassing.
.name	Tekenreeks	Geeft de naam van het verzendtarief terug. Deze kan worden gewijzigd met de change_name-methode.
.price	Geld	Geeft de prijs van het verzendtarief terug.
.source	Tekenreeks	Geeft de bron (de vervoerder) terug die aan het verzendtarief is gekoppeld, indien relevant. Deze kan niet worden gewijzigd.
.change_name(Tekenreeks new_name)	Tekenreeks	Wijzigt de naam (maximaal 255 tekens) van het verzendtarief. Het is niet mogelijk om de bron te wijzigen, verwijderen of verbergen.
.apply_discount(Money korting, { message: Tekenreeks })	Geld	Past een korting toe van het opgegeven vaste bedrag. De prijs kan niet lager dan 0 worden. Een bericht is vereist.
.phone_required?	Boolean	Geeft true terug als een telefoonnummer vereist is om het verzendtarief te verkrijgen, of false als een telefoonnummer niet is vereist.

Betaalmethoden

De volgende methoden kunnen worden gebruikt in betalingsscripts:

Invoer

Scriptmethoden die het Input-object gebruiken in betalingsscripts

Methode	Retourtype	Omschrijving
.payment_gateways	PaymentGatewaysList	Geeft een lijst terug met alle betalingsgateways in de winkel.

PaymentGatewayList

Scriptmethoden die het PaymentGatewayList-object gebruiken in betalingsscripts

Methode	Retourtype	Omschrijving
.delete_if	PaymentGatewayList	Verwijdert betalingsgateways met een optioneel codeblok. Zie de documentatie voor de delete_if-methode van Ruby.
.sort!	PaymentGatewayList	Sorteert de betalingsgateways met de vergelijkingsoperator of met een optioneel codeblok. Zie de documentatie voor de sort!-methode van Ruby.
.sort_by!	PaymentGatewayList	Sorteert de betalingsgateways met een optioneel codeblok. Zie de documentatie voor de sort_by!-methode van Ruby.

PaymentGateway

Methode	Retourtype	Omschrijving
.name	Tekenreeks	Geeft de naam van de betalingsgateway terug.
.enabled_card_brands	List<String>	Als de betalingsgateway creditcards ondersteunt, geeft deze een lijst terug met de creditcardtypen die de winkel accepteert. Als de gateway geen creditcards ondersteunt, geeft deze een lege lijst terug.
.change_name(Tekenreeks new_name)	Tekenreeks	Wijzigt de naam van de betalingsgateway. De naam van betalingsgateways met een logo kan niet worden gewijzigd.

Voorbeelden

In het volgende voorbeeld van een orderregelscript wordt, wanneer een klant een product bestelt dat geen cadeaubon is, de prijs van het product verlaagd met $ 9,-. Ook wordt het totaalbedrag 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 basisprincipes van Ruby
• Scripts aanmaken
• Je scripts testen en debuggen
• Je Liquid-templates bijwerken voor scripts
• Shopify-scripts