API-naslaghandleiding voor Shopify-scripts

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

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

Regelartikelscripts

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

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 het afrekenen de pagina met verzendopties is bereikt.

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 onlinewinkel. Sommige afgebroken betaalprocedures hebben toegang tot het cart-object. Als een betaalprocedure echter is afgesloten en een klant vervolgens naar de betaalprocedure gaat, wordt de klant naar de vooraf ingevulde kassa gestuurd en bestaat het cart-object niet meer. Dit komt omdat de storefront is overgeslagen door de e-mail voor een afgebroken betaalprocedure.

Scriptmethoden met behulp van het Cart-object
Wijze Retourobject Beschrijving
.customer Klant Retourneert de eigenaar van de winkelwagen (indien aanwezig).
.shipping_address Verzendadres Retourneert het verzendadres van de eigenaar van de winkelwagen (indien aanwezig).
.discount_code varieert Retourzendingen

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 regelartikelen in de winkelwagen.
.presentment_currency List<String> Retourneert de lokale valuta (presentatievaluta) van de klant (in ISO 4217-indeling), bijvoorbeeld USD.
.subtotal_price Money 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 regelartikelen 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 Money 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 geweigerd.

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 Geheel getal 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 geweigerd.

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

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 Money Retourneert het totale bedrag dat de klant aan alle bestellingen heeft uitgegeven.
.accepts_marketing? Boolean Retourneert of de klant marketing accepteert.

LineItem

< tdgram
Scriptmethoden met behulp van het line item-object
Wijze Retourobject Beschrijving
.grams Retourneert het totale gewicht van het regelartikel.
.line_price Money De prijs van het regelartikel.
.discounted? Boolean Retourneert of een korting de prijs van het regelartikel heeft gewijzigd.
.properties hash Retourneert de eigenschappen die zijn opgegeven voor dit regelartikel.
.variant Variant Retourneert de specifieke productvariant die wordt aangegeven door het regelartikel.
.quantity Geheel getal Retourneert de hoeveelheid van dit regelartikel.

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.

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

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

Verzendadres

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

Money

Scriptmethoden met behulp van het Money-object
Wijze Retourobject Beschrijving
.derived_from_presentment(customer_cents:X) Money Converteert een bedrag (in centen) van de lokale valuta (presentatievaluta) van de klant naar de valuta van uw winkel. Deze methode accepteert de parameter customer_cents, die een waarde uitgedrukt in centen accepteert. Bijvoorbeeld: Money.derived_from_presentment(customer_cents: 500).
.new Money Maakt een nieuw object om een prijs te vertegenwoordigen.
.zero Money

Maakt een nieuw object met een prijs van nul.

+ Money Voegt twee Money-objecten toe.
- Money Trekt het ene Money-object van het andere af.
* Money 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 Money Retourneert de eenheidsprijs van de variant.
.product Product Retourneert het bijbehorende product van de variant.
.skus List<String> Retourneert de voorraadeenheden (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 regelartikelen

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 Money 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 }) Money Wijzig de prijs van het regelartikel in het opgegeven bedrag. Je moet een bericht opgeven bij message. new_price moet lager zijn dan de huidige prijs.
.original_line_price Money Retourneert de oorspronkelijke prijs van het regelartikel voordat scripts en kortingen werden toegepast.
.line_price_was Money Retourneert de prijs van het artikelregelvoordat wijzigingen door het huidige script werden toegepast.
.line_price_changed? Boolean Retourneert of de prijs van het artikelregelis 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 het regelartikel.
.properties_was hash Retourneert de hash van de oorspronkelijke eigenschappen van het artikelregelvoordat eventuele wijzigingen werden toegepast.
.properties_changed? Boolean Retourneert of de eigenschappen voor het artikelregelzijn gewijzigd.
.split({ take: Integer }) LineItem Splitst een regelartikel op in twee regelartikelen. take geeft aan welke hoeveelheid moet worden verwijderd van het oorspronkelijke regelartikel om het nieuwe regelartikel 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 regelitems
Wijze Retourobject Beschrijving
.compare_at_price Money Retourneert de vergelijkingsprijs van de variant. Retourneert nil als de variant geen vergelijkingsprijs heeft.

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 String Retourneert de beschrijving van de toeslag voor het verzendtarief.
.name String Retourneert de naam van het verzendtarief.
.price Money Retourneert de prijs van het verzendtarief.
.source String Retourneert de bron (de vervoerder) die aan het verzendtarief is gekoppeld.
.change_name(String new_name, { message: String }) String Wijzigt de naam (maximaal 255 tekens) van het verzendtarief. Je moet een bericht opgeven bij message.
.apply_discount(Money discount, { message: String }) Money 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.

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:

Klaar om te beginnen met verkopen met Shopify?

Probeer het gratis