Référence de l'API des scripts Shopify

Cette page a été imprimée le Apr 22, 2023. Pour la dernière version, allez à https://help.shopify.com/fr/manual/checkout-settings/script-editor/shopify-scripts.

Les scripts sont écrits avec une API Ruby qui vous donne une grande marge de contrôle et de flexibilité.

Il existe plusieurs types de scripts différents. Un script est associé à un type lors de sa création dans l'application Script Editor, en fonction du modèle de script que vous choisissez pour commencer :

Scripts de rubriques

Les scripts de rubriques affectent les rubriques du panier et permettent de modifier les prix ainsi que d'accorder des réductions. Ces scripts sont exécutés chaque fois qu'une modification est apportée au panier.

Les scripts de rubrique qui accordent une réduction sur un abonnement ne l’appliquent qu'au premier paiement de l’abonnement. Ils ne prévoient pas de réduction sur les paiements suivants.

Certaines méthodesne sont utilisables que dans les scripts de rubrique.

Scripts d'expédition

Les scripts d'expédition interagissent avec l'expéditionet peuvent modifier les modes d'expédition ou accorder des réductions sur les frais d'expédition. Ces scripts sont exécutés lorsque votre client accède à la page des options d'expédition au moment du paiement.

Les scripts d’expédition qui accordent une réduction sur les frais d’expédition d’un abonnement ne l’appliquent qu’au premier paiement de l’abonnement. Ils ne prévoient pas de réduction sur les paiements suivants.

Certaines méthodesne sont utilisables que dans les scripts d'expédition.

Scripts de paiement

Les scripts de paiement interagissent avec lespaiementset peuvent renommer, cacher ou réorganiser les passerelles de paiement. Veuillez noter que les scripts de paiement n'interagissent pas avec les passerelles de paiement affichées avant l'écran de passage à la caisse, telles qu'Apple Pay. Ces scripts sont exécutés une fois sur la page de paiement.

Certaines méthodesne sont utilisables que dans les scripts de paiement.

Méthodes générales

Les méthodes suivantes sont utilisables, quel que soit le type de script :

Entrée

Méthodes d’entrée de script
Méthode Type de retour Description
.cart Panier Renvoie un objet de panier modifiable.
. paramètres régionaux chaîne Renvoie les paramètres régionaux du client. Par exemple,en,fr, orpt-BR.

Panier

L'objet paiement est uniquement disponible sur la boutique en ligne. Certains paiements abandonnés ont accès à l'objet paiement. Cependant, si un passage à la caisse a été fermé et qu'un client se rend sur le paiement abandonné, il est directement acheminé jusqu'sur la page de paiement prérempli et l'objet paiement n'existe plus. Cela est dû au fait que l'e-mail de relance de panier abandonné a contourné la boutique en ligne.

Méthodes de script utilisant l’objet Cart
Méthode Type de retour Description
.customer Client Renvoie le propriétaire du panier (le cas échéant).
.shipping_address ShippingAddress Renvoie l'adresse d'expédition du propriétaire du panier (le cas échéant).
.discount_code varie Renvoie :

discount_codeest présent si une réduction a été appliquée au panier. Cela ne signifie pas forcément que le prix du panier change. Par exemple, si une réduction s'applique aux paniers de plus de 50 $ et qu'un script fait baisser le prix du panier en dessous de 50 $,discount_codeest toujours présent, mais le prix du panier ne change pas.

Voir un exemple dediscount_code.
.line_items List Renvoie une liste contenant toutes les rubriques du panier.
.presentment_currency List Renvoie la devise locale (présentation) du client (au formatISO 4217). Par exemple, USD.
.subtotal_price Argent (filtre financier) Renvoie le sous-total du panier après l'application des réductions de rubrique, mais avant celle des codes de réduction.
.total_weight grams Renvoie le poids total de toutes les rubriques du panier.

CartDiscount::FixedAmount

Méthodes de script utilisant l’objet CartDiscount:: FixedAmount
Méthode Type de retour Description
.code Chaîne Renvoie le code de réduction utilisé pour appliquer la réduction.
.amount Argent (filtre financier) Renvoie le montant de la réduction.
.reject({ message: String }) nil Rejette le code de réduction appliqué au panier. Unmessageest requis.
.rejected? Booléen Indique si le code de réduction a été rejeté ou non.

CartDiscount::Percentage

Méthodes de script utilisant l’objet CartDiscount::P ercentage
Méthode Type de retour Description
.code Chaîne Renvoie le code de réduction utilisé pour appliquer la réduction.
.percentage Décimale Renvoie le pourcentage de la réduction.
.reject({ message: String }) nil Rejette le code de réduction appliqué au panier. Unmessageest requis.
.rejected? Booléen Indique si le code de réduction a été rejeté ou non.

CartDiscount::Shipping

Méthodes de script utilisant l’objet CartDiscount:: Shipping
Méthode Type de retour Description
.code Chaîne Renvoie le code de réduction utilisé pour appliquer la réduction.
.reject({ message: String }) nil Rejette le code de réduction appliqué au panier. Unmessageest requis.
.rejected? Booléen Indique si le code de réduction a été rejeté ou non.

Client

Méthodes de script utilisant l’objet Customer
Méthode Type de retour Description
.id Entier Renvoie le号d 'identification du client.
.email Chaîne 杜Renvoie l本电子邮件客户端。
.tags List Renvoie une liste des chaînes de caractères représentant les balises définies pour un client.
.orders_count Entier Renvoie le nombre total de commandes passées par un client.
.total_spent Argent (filtre financier) Renvoie le montant total dépensé par le client sur toutes les commandes.
.accepts_marketing? Booléen Indique si le client accepte les communications marketing.

LineItem

grams Renvoie le poids total de la rubrique.
Méthodes de script utilisant l’objet rubrique
Méthode Type de retour Description
.grams
.line_price Argent (filtre financier) Le prix de la rubrique.
.discounted? Booléen Retourne si le prix d’une rubrique a été réduit par un script ou par une réduction appliquée manuellement. L’utilisation de codes de réduction n’influence pas la valeur de retour.
.properties hash Renvoie les propriétés spécifiées pour cette rubrique.
.variant Variante Renvoie la variante spécifique du produit représenté par la rubrique.
.quantity Entier Renvoie la quantité de cette rubrique.
.selling_plan_id Entier Renvoie l’identifiant du forfait de vente de la rubrique. Avec cette méthode, lorsque la boutique propose des abonnements, le script détecte quand une variante de produit estvendue dans le cadre d'un abonnement.

Liste

Méthodes de script utilisant l’objet List
Méthode Type de retour Description
.new Liste Crée un nouvel objet pour représenter une liste.
.[] Élément ou nul

Renvoie l'élément à l'index spécifié.
.& Liste

Renvoie une nouvelle liste contenant les éléments communs aux deux listes, sans doublon.
.delete_if Liste Supprime les éléments à l'aide d'un bloc de code facultatif. Voir la documentation sur laméthodedelete_ifde Ruby.
.empty? Booléen

Renvoietruesi la liste ne contient aucun élément
.first Élément ou nul

Renvoie le premier élément ounilsi la liste est vide.
.index(*args, &block) int ou nil

Renvoie l'index du premier élément de la liste. Si un bloc est fourni au lieu d'un argument, renvoie l'index du premier élément pour lequel le bloc est vrai.
.rindex(*args, &block) int ou nil

Renvoie l'index du dernier élément de la liste. Si un bloc est fourni au lieu d'un argument, renvoie l'index du premier élément pour lequel le bloc est vrai.
.last Élément ou nul

Renvoie le dernier élément ounulsi la liste est vide.
.length int

Renvoie le nombre d'éléments dans la liste.
.size int

Alias de la longueur.
.each(*args, &block) Liste

Appelle un bloc une fois pour chaque élément de la liste, en le passant en tant que paramètre du bloc.

ShippingAddress

Méthodes de script utilisant l’objet ShippingAddress
Méthode Type de retour Description
.name chaîne Renvoie le nom de la personne associée à l'adresse d'expédition.
.address1 chaîne Renvoie la partie de l'adresse d'expédition correspondant à la rue.
.address2 chaîne Renvoie le champ supplémentaire facultatif de la partie de l'adresse d'expédition correspondant à la rue.
.phone chaîne Renvoie le numéro de téléphone de l'adresse d'expédition.
.city chaîne Renvoie la ville de l'adresse d'expédition.
.zip chaîne Renvoie le code postal de l'adresse d'expédition.
.province chaîne Renvoie la province, l'État fédéral ou la région de l'adresse d'expédition.
.province_code chaîne Renvoie la valeur abrégée de la province ou de l'État de l'adresse d'expédition.
.country_code chaîne Renvoie勒杜ISO代码支付de l d 'expedit本ion.

Argent (filtre financier)

Méthodes de script utilisant l’objet Money
Méthode Type de retour Description
.derived_from_presentment(customer_cents:X) Argent (filtre financier) Convertit un montant (en centimes) de la devise locale (présentation) du client dans la devise de votre boutique. Cette méthode accepte le paramètrecustomer_cents, qui accepte un nombre en centimes. Par exemple,Money.derived_from_presentment (customer_cents: 500).
.new Argent (filtre financier) Crée un nouvel objet pour représenter un prix.
.zero Argent (filtre financier)

Crée un nouvel objet dont le prix est zéro.
+ Argent (filtre financier) Ajoute deux objetsMoney(financiers).
- Argent (filtre financier) Soustrait un objetMoney(financier) d'un autre.
* Argent (filtre financier) Multiplie un objetMoney(financier) par un nombre.

Exemples Argent

Money.new(cents:1000)

Crée un objetMoneyreprésentant 1000 cents, ou 10 $.

Money.new(cents:100)*50

Crée un objetMoneyreprésentant 1 $, puis multiplie de montant par 50. Renvoie un objetMoneyreprésentant 50 $.

Variante

Méthodes de script utilisant l’objet variant
Méthode Type de retour Description
.id Entier Renvoie le numéro d'identification de la variante.
.price Argent (filtre financier) Renvoie le prix à l'unité de la variante.
.product Produit Renvoie le produit associé à la variante.
.skus List Renvoie les unités de gestion des stocks (SKU) de la variante, qui sont souvent utilisées pour le suivi des stocks.
.title Chaîne Renvoie le titre de la variante.

Produit

Méthodes de script utilisant l’objet Product
Méthode Type de retour Description
.id Entier Renvoie le numéro d'identification du produit.
.gift_card? Booléen Indique si le produit est une carte-cadeau.
.tags List Renvoie une liste de chaînes de caractères représentant les balises définies pour ce produit.
.product_type Chaîne Catégorisation pouvant être associée à produit par une balise, couramment utilisée pour le filtrage et les recherches.
.vendor Chaîne Renvoie le vendeur de ce produit.

Kernel

Kernelest un module Ruby qui est inclus dans chaque classe. Ses méthodes sont donc disponibles pour chaque objet. Ces méthodes agissent comme les fonctions globales dans les autres langages.

Méthodes de script utilisant l’objet du noyau
Méthode Type de retour Description
.exit aucun Termine l'exécution du script actuel sans erreur. En cas d'exécution sans qu'aucun élément n'ait été associé avecOutput.cart, le script reste sans effet. Cette méthode est pratique pour sortir d'un script, par exemple dans le cas où le client n'est pas éligible à l'exécution du script.

Exemple de Kernel

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

Méthodes de rubrique

Les méthodes suivantes sont uniquement utilisables dans lesscripts de rubrique:

Panier

Méthodes de script utilisant l’objet Cart dans les scripts de rubrique
Méthode Type de retour Description
.subtotal_price_was Argent (filtre financier) Renvoie le sous-total du panier avant l'application des codes de réduction.
.subtotal_price_changed? Booléen Indique si le sous-total a changé.

LineItem

Méthodes de script utilisant l’objet rubrique dans les scripts de rubrique
Méthode Type de retour Description
.change_line_price(Moneynew_price, { message:String}) Argent (filtre financier) Passe le prix de la rubrique au montant spécifié. Unmessageest requis. Le nouveau prix (new_price) doit être inférieur au prix actuel.
.original_line_price Argent (filtre financier) Renvoie le prix normal de la rubrique avant l'application des scripts et des codes de réduction.
.line_price_was Argent (filtre financier) Renvoie le prix de la rubrique avant les modifications appliquées par le script en cours.
.line_price_changed? Booléen Indique si le prix de la rubrique a changé.
.change_properties(hashnew_properties, { message:String}) hash Définit de nouvelles propriétés pour une rubrique. La valeur de hachage d'origine des propriétés est stockée dansproperties_was, tandis que la valeur de hachage des propriétés transmise à la méthode devient les nouvelles propriétés de la rubrique.
.properties_was hash Renvoie la valeur de hachage d'origine des propriétés de la rubrique avant l'application des modifications.
.properties_changed? Booléen Indique si les propriétés pour la rubrique ont été modifiées.
.split({ take:Integer}) LineItem Divise une rubrique en deux rubriques.takeindique quelle quantité doit être retirée de la rubrique d'origine pour en créer une deuxième.

.split example

Cet exemple de script divise en deux une rubrique intituléeoriginal_line_item. La nouvelle rubrique a une quantité de 1 (spécifiée partake: 1). Le script applique alors un prix réduit à la nouvelle rubrique avec le message suivant : « Troisième chapeau pour 5 dollars. »

iforiginal_line_item.quantity>=3new_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_itemend

Variante

Méthodes de script utilisant l’objet de variante dans les scripts de rubrique
Méthode Type de retour Description
.compare_at_price Argent (filtre financier) Renvoie le prix avant réduction de la variante. Renvoienilsi la variante n'a pas de prix avant réduction.

Méthodes d'expédition

Les méthodes suivantes sont uniquement utilisables dans lesscripts d'expédition:

Entrée

Méthodes de script utilisant l’objet d’entrée dans les scripts d’expédition
Méthode Type de retour Description
.shipping_rates ShippingRateList Renvoie une liste de tous les frais d'expédition.

ShippingRateList

Méthodes de script utilisant l’objet ShippingRateList dans les scripts d’expédition
Méthode Type de retour Description
.delete_if ShippingRateList Supprime les frais d'expédition à l'aide d'un bloc de code optionnel. Voir la documentation sur laméthodedelete_ifde Ruby.
.sort! ShippingRateList Trie les tarifs d'expédition à l'aide de l'opérateur de comparaison ou d'un bloc de code optionnel. Voir la documentation sur laméthodesort!de Ruby.
.sort_by! ShippingRateList Trie les frais d'expéditions à l'aide d'un bloc de code optionnel. Voir la documentation sur laméthodesort_by!de Ruby.

ShippingRate

Méthodes de script utilisant l’objet ShippingRate dans les scripts d’expédition
Méthode Type de retour Description
.code Chaîne Renvoie le code du tarif d'expédition.
.markup Argent (filtre financier) Renvoie le balisage du tarif d’expédition, le cas échéant.
.name Chaîne Renvoie le nom des frais d’expédition. Il est possible de le modifier en utilisant la méthodechange_name.
.price Argent (filtre financier) Renvoie le montant des frais d'expédition.
.source Chaîne Renvoie la source (le transporteur) associée aux frais d’expédition, le cas échéant. Elle ne peut pas être modifiée.
.change_name(Stringnew_name) Chaîne Modifie le nom (255 caractères maximum) des frais d’expédition. Vous ne pouvez pas modifier, supprimer ni masquer la source.
.apply_discount(Moneydiscount, { message: String }) Argent (filtre financier) Applique une réduction du montant fixe spécifié. Le prix ne peut pas être réduit en dessous de 0. Un message est requis.
.phone_required? Booléen Renvoietruesi un numéro de téléphone est requis pour obtenir les frais d'expédition, oufalsedans le cas contraire.

Moyens de paiement

Les méthodes suivantes sont utilisables dans lesscripts de paiement:

Entrée

Méthodes de script utilisant l’objet d’entrée dans les scripts de paiement
Méthode Type de retour Description
.payment_gateways PaymentGatewaysList Renvoie une liste de toutes les passerelles de paiement de la boutique.

PaymentGatewayList

方法de脚本中使用l 'objet PaymentGatewayList dans les scripts de paiement
Méthode Type de retour Description
.delete_if PaymentGatewayList Supprime les passerelles de paiement à l'aide d'un bloc de code optionnel. Voir la documentation sur laméthodedelete_ifde Ruby.
.sort! PaymentGatewayList Trie les passerelles de paiement à l'aide d'un opérateur de comparaison ou d'un bloc de code optionnel. Voir la documentation sur laméthodesort!de Ruby.
.sort_by! PaymentGatewayList Trie les passerelles de paiement à l'aide d'un bloc de code optionnel. Voir la documentation sur laméthodesort_by!de Ruby.

PaymentGateway

Méthode Type de retour Description
.name Chaîne Renvoie le nom de la passerelle de paiement.
.enabled_card_brands List

Si la passerelle de paiement prend en charge les cartes de crédit, renvoie une liste des types de cartes de crédit autorisées par la boutique. Si la passerelle ne prend pas en charge les cartes de crédit, renvoie une liste vide.
.change_name(Stringnew_name) Chaîne Modifie le nom de la passerelle de paiement. Les passerelles de paiement avec des logos ne peuvent pas être renommées.

Exemples

Dans l'exemple de script de rubrique suivant, lorsqu'un client commande un produit qui n'est pas une carte-cadeau, le prix du produit est réduit de 9 $. En outre, le montant total que le client a dépensé lors de ses visites sur votre boutique s'affiche :

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

En savoir plus

En savoir plus sur :

Prêt(e) à commencer à vendre avec Shopify ?

Essayez gratuitement