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

Les scripts sont écrits avec une API Ruby qui vous offre beaucoup de contrôle et de flexibilité.

Forfait requis

Les scripts Shopify et l’appli Script Editor ne sont accessibles qu’aux boutiques disposant du forfait Shopify Plus. L’appli Script Editor n’est plus disponible au téléchargement sur la Shopify App Store.

Le 30 juin 2026, les scripts Shopify seront supprimés et ne fonctionneront plus. Si vous souhaitez continuer à bénéficier de l’assistance pour vos cas d’utilisation existants des scripts Shopify, vous devez passer à des solutions de remplacement Shopify Functions compatibles pour vos scripts de paiement, d’expédition ou d’article du panier. En savoir plus sur la migration des scripts Shopify vers Shopify Functions.

Il existe différents types de script. Un type est attribué à un script lorsque vous le créez dans l’appli Script Editor, en fonction du modèle de script que vous choisissez au départ :

Scripts d’article du panier

Les scripts d’article du panier affectent les articles du panier et peuvent modifier les prix et octroyer des réductions. Ces scripts s’exécutent lorsqu’une modification est apportée au panier.

Les scripts d’article du panier qui appliquent une réduction à un abonnement s’appliquent uniquement au premier paiement de l’abonnement. Les paiements suivants ne bénéficient pas de la réduction du script.

Certaines méthodes ne peuvent être utilisées que dans les scripts d’article du panier.

Scripts d’expédition

Les scripts d’expédition interagissent avec l’expédition, et peuvent modifier les modes d’expédition et octroyer des réductions sur les tarifs d’expédition. Ces scripts s’exécutent lorsque le processus de paiement atteint la page des options d’expédition.

Les scripts d’expédition qui appliquent une réduction sur les frais d’expédition d’un abonnement s’appliquent uniquement au premier paiement de l’abonnement. Les paiements suivants ne bénéficient pas de la réduction du script.

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

Scripts de paiement

Les scripts de paiement interagissent avec les paiements, et peuvent renommer, masquer et réorganiser les passerelles de paiement. Notez que les scripts de paiement n’interagissent pas avec les passerelles de paiement affichées avant la page de paiement, comme Apple Pay. Ces scripts s’exécutent lorsque le processus de paiement atteint la page de paiement.

Certaines méthodes ne peuvent être utilisées que dans les scripts de paiement.

Méthodes générales

Les méthodes suivantes sont utilisables dans n’importe quel type de script :

Entrée

Méthodes d’entrée de script

Méthode	Type de retour	Description
.cart	Panier	Renvoie un objet panier modifiable.
.locale	chaîne	Renvoie les paramètres régionaux du client. Par exemple, en, fr ou pt-BR.

Panier

L’objet panier est uniquement disponible sur la boutique en ligne. Certains paiements abandonnés ont accès à l’objet panier. Toutefois, si un paiement a été fermé et qu’un client se rend ensuite sur le paiement abandonné, il est dirigé vers le paiement pré-rempli et l’objet panier n’existe plus. En effet, la boutique en ligne a été contournée par l’e-mail de relance de paiement abandonné.

Méthodes de script utilisant l’objet Panier

Méthode	Type de retour	Description
.customer	Client	Renvoie le propriétaire du panier (le cas échéant).
.shipping_address	Adresse de livraison	Renvoie l’adresse de livraison du propriétaire du panier (le cas échéant).
.discount_code	variable	Renvoie : nil si le panier ne contient aucun code de réduction CartDiscount::FixedAmount si le panier bénéficie d’une réduction d’un montant fixe CartDiscount::Percentage si le panier bénéficie d’une réduction en pourcentage CartDiscount::Shipping si le panier bénéficie d’une réduction sur l’expédition Renvoie un code de réduction unique (voir les Limites) discount_code est présent si une réduction a été appliquée au panier. Cela ne signifie pas nécessairement que le prix du panier change. Par exemple, si une réduction s’applique aux paniers de plus de 50 $ et qu’un script réduit le prix du panier en dessous de 50 $, discount_code est toujours présent, mais le prix du panier ne change pas. <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

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	Montant	Renvoie le montant de la réduction.
.reject({ message: Chaîne })	nil	Rejette le code de réduction appliqué au panier. Un message est obligatoire.
.rejected?	Booléen	Renvoie si le code de réduction a été rejeté.

CartDiscount::Percentage

Méthodes de script utilisant l’objet CartDiscount::Percentage

Méthode	Type de retour	Description
.code	Chaîne	Renvoie le code de réduction utilisé pour appliquer la réduction.
.percentage	Décimal	Retourne le pourcentage de la réduction.
.reject({ message: Chaîne })	nil	Rejette le code de réduction appliqué au panier. Un message est obligatoire.
.rejected?	Booléen	Renvoie si le code de réduction a été rejeté.

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: Chaîne })	nil	Rejette le code de réduction appliqué au panier. Un message est obligatoire.
.rejected?	Booléen	Renvoie si le code de réduction a été rejeté.

Customer

Méthodes de script utilisant l’objet Customer

Méthode	Type de retour	Description
.id	Entier	Retourne l’ID du client.
.email	Chaîne	Retourne l’adresse e-mail du client.
.tags	List<Tag>	Retourne une liste de chaînes représentant les balises définies pour un client.
.orders_count	Entier	Retourne le nombre total de commandes qu’un client a passées.
.total_spent	Montant	Retourne le montant total que le client a dépensé pour toutes les commandes.
.accepts_marketing?	Booléen	Indique si le client accepte le marketing.

LineItem

Méthodes de script utilisant l’objet LineItem

Méthode	Type de retour	Description
.grams	grammes	Retourne le poids total de l’article du panier.
.line_price	Montant	Le prix de l’article du panier.
.discounted?	Booléen	Indique si le prix d’un article du panier a bénéficié d’une réduction appliquée par un script ou manuellement. L’utilisation de codes de réduction n’a aucune incidence sur la valeur de retour.
.properties	hash	Retourne les propriétés qui ont été spécifiées pour cet article du panier.
.variant	Variant	Retourne la variante de produit spécifique représentée par l’article du panier.
.quantity	Entier	Retourne la quantité de cet article du panier.
.selling_plan_id	Entier	Retourne l’ID du forfait de vente pour l’article du panier. Cette méthode est utile lorsque la boutique vend des abonnements et que vous souhaitez que le script détecte lorsqu’une variante de produit est vendue sous forme d’abonnement.

List

Méthodes de script utilisant l’objet List

Méthode	Type de retour	Description
.new	List	Crée un nouvel objet pour représenter une liste.
.[]	Élément ou nil	Retourne l’élément à l’index spécifié.
.&	List	Retourne une nouvelle liste contenant les éléments communs aux deux listes, sans doublons.
.delete_if	List	Supprime des éléments à l’aide d’un bloc de code facultatif. Consultez la documentation relative à la méthode delete_if de Ruby.
.empty?	Booléen	Retourne true si la liste ne contient aucun élément.
.first	Élément ou nil	Retourne le premier élément ou nil si la liste est vide.
.index(*args, &block)	int ou nil	Retourne l’index du premier élément de la liste. Si un bloc est fourni à la place d’un argument, la méthode retourne l’index du premier élément pour lequel le bloc est vrai.
.rindex(*args, &block)	int ou nil	Retourne l’index du dernier élément de la liste. Si un bloc est fourni à la place d’un argument, la méthode retourne l’index du premier élément pour lequel le bloc est vrai.
.last	Élément ou nil	Retourne le dernier élément ou nil si la liste est vide.
.length	int	Retourne le nombre d’éléments dans la liste.
.size	int	Alias de length.
.each(*args, &block)	List	Appelle un bloc une fois pour chaque élément de la liste, en transmettant l’élément en tant que paramètre au bloc.

ShippingAddress

Méthodes de script utilisant l’objet ShippingAddress

Méthode	Type de retour	Description
.name	chaîne	Retourne le nom de la personne associée à l’adresse de livraison.
.address1	chaîne	Retourne la partie de l’adresse de livraison correspondant à la rue.
.address2	chaîne	Retourne le complément d’adresse facultatif de l’adresse de livraison.
.phone	chaîne	Retourne le numéro de téléphone de l’adresse de livraison.
.city	chaîne	Retourne la ville de l’adresse de livraison.
.zip	chaîne	Retourne le code postal de l’adresse de livraison.
.province	chaîne	Retourne la province ou l’État de l’adresse de livraison.
.province_code	chaîne	Retourne la valeur abrégée de la province ou de l’État de l’adresse de livraison.
.country_code	chaîne	Retourne la valeur abrégée du pays de l’adresse de livraison.

Money

Méthodes de script utilisant l’objet Money

Méthode	Type de retour	Description
.derived_from_presentment(customer_cents:X)	Montant	Convertit un montant (en centimes) de la devise locale du client (devise de présentation) à la devise de votre boutique. Cette méthode accepte le paramètre customer_cents, qui accepte un nombre en centimes. Par exemple, Money.derived_from_presentment(customer_cents: 500).
.new	Montant	Crée un nouvel objet pour représenter un prix.
.zero	Montant	Crée un nouvel objet avec un prix de zéro.
+	Montant	Additionne deux objets Money.
-	Montant	Soustrait un objet Money d’un autre.
*	Montant	Multiplie un objet Money par un nombre.

Exemples de Money

Money.new(cents: 1000)

Crée un objet Money représentant 1 000 centimes, ou 10 $.

Money.new(cents: 100) * 50

Crée un objet Money représentant 1 $, puis multiplie ce montant par 50. Renvoie un objet Money représentant 50 $.

Variante

Méthodes de script utilisant l’objet Variant

Méthode	Type de retour	Description
.id	Entier	Renvoie le numéro d’ID de la variante.
.price	Montant	Renvoie le prix unitaire de la variante.
.product	Produit	Renvoie le produit associé à la variante.
.skus	Liste<chaîne>	Renvoie les unités de gestion des stocks (SKU) de la variante, qui sont souvent utilisées pour le suivi du stock.
.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’ID du produit.
.gift_card?	Booléen	Indique si le produit est une carte-cadeau.
.tags	List<Tag>	Renvoie une liste de chaînes représentant les balises qui sont définies pour ce produit.
.product_type	Chaîne	Catégorisation avec laquelle un produit peut être balisé, couramment utilisée pour le filtrage et la recherche.
.vendor	Chaîne	Renvoie le fournisseur de ce produit.

Kernel

Kernel est un module Ruby qui est inclus dans chaque classe. Par conséquent, ses méthodes sont disponibles pour chaque objet. Ces méthodes agissent de la même manière que les fonctions globales dans d’autres langages.

Méthodes de script utilisant l’objet Kernel

Méthode	Type de retour	Description
.exit	aucune	Met fin à l’exécution du script actuel sans erreur. Si cette commande est exécutée avant qu’un élément ne soit attribué à Output.cart, le script n’a aucun effet. C’est une façon utile de quitter les scripts, par exemple, si le client n’est pas admissible à l’exécution du script.

Exemple de Kernel

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

Méthodes d’article

Les méthodes suivantes ne sont utilisables que dans les scripts d’article :

Panier

Méthodes de script utilisant l’objet Panier dans les scripts d’article

Méthode	Type de retour	Description
.subtotal_price_was	Montant	Renvoie le sous-total du panier avant l’application de toute réduction.
.subtotal_price_changed?	Booléen	Indique si le sous-total a changé.

LineItem

Méthodes de script utilisant l’objet LineItem dans les scripts d’article

Méthode	Type de retour	Description
.change_line_price(Money new_price, { message: chaîne })	Montant	Modifie le prix de l’article pour le remplacer par le montant indiqué. Un message est obligatoire. new_price doit être inférieur au prix actuel.
.original_line_price	Montant	Renvoie le prix original de l’article avant l’application des scripts et des réductions.
.line_price_was	Montant	Renvoie le prix de l’article avant que le script actuel n’applique des modifications.
.line_price_changed?	Booléen	Indique si le prix de l’article a changé.
.change_properties(hash new_properties, { message: chaîne })	hash	Définit de nouvelles propriétés pour un article. Le hachage des propriétés d’origine est stocké dans properties_was et le hachage des propriétés transmis à la méthode devient les nouvelles propriétés de l’article.
.properties_was	hash	Renvoie le hachage des propriétés d’origine de l’article avant l’application de toute modification.
.properties_changed?	Booléen	Indique si les propriétés de l’article ont été modifiées.
.split({ take: Entier })	LineItem	Divise un article en deux articles. take spécifie la quantité à retirer de l’article d’origine pour créer le nouvel article.

Exemple de .split

Cet exemple de script divise un article appelé original_line_item en deux articles. Le nouvel article a une quantité de 1 (spécifiée par take: 1). Le script applique ensuite un prix réduit au nouvel article avec le message « Troisième chapeau pour 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

Variante

Méthodes de script utilisant l’objet Variant dans les scripts d’article

Méthode	Type de retour	Description
.compare_at_price	Montant	Renvoie le prix de comparaison de la variante. Renvoie nil si la variante n’a pas de prix de comparaison.

Modes d’expédition

Les méthodes suivantes sont utilisables dans les scripts d’expédition :

Entrée

Méthodes de script utilisant l’objet Input dans les scripts d’expédition

Méthode	Type de retour	Description
.shipping_rates	ShippingRateList	Retourne une liste de tous les tarifs 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 tarifs d’expédition à l’aide d’un bloc de code facultatif. Consultez la documentation de la méthode delete_if de Ruby.
.sort!	ShippingRateList	Trie les tarifs d’expédition à l’aide de l’opérateur de comparaison ou d’un bloc de code facultatif. Consultez la documentation de la méthode sort! de Ruby.
.sort_by!	ShippingRateList	Trie les tarifs d’expédition à l’aide d’un bloc de code facultatif. Consultez la documentation de la méthode sort_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	Retourne le code du tarif d’expédition.
.markup	Montant	Retourne la majoration d’un tarif d’expédition, le cas échéant.
.name	Chaîne	Retourne le nom du tarif d’expédition. Il peut être modifié à l’aide de la méthode change_name.
.price	Montant	Retourne le prix du tarif d’expédition.
.source	Chaîne	Retourne la source (le transporteur) associée au tarif d’expédition, le cas échéant. Elle ne peut pas être modifiée.
.change_name(String new_name)	Chaîne	Modifie le nom (255 caractères maximum) du tarif d’expédition. Il n’est pas possible de modifier, de supprimer ou de masquer la source.
.apply_discount(Money discount, { message: String })	Montant	Applique une réduction du montant fixe spécifié. Le prix ne peut pas être inférieur à 0. Un message est obligatoire.
.phone_required?	Booléen	Retourne true si un numéro de téléphone est requis pour obtenir le tarif d’expédition, ou false si aucun numéro de téléphone n’est requis.

Moyens de paiement

Les méthodes suivantes peuvent être utilisées dans les scripts de paiement :

Entrée

Méthodes de script utilisant l’objet Input dans les scripts de paiement

Méthode	Type de retour	Description
.payment_gateways	PaymentGatewaysList	Retourne une liste de toutes les passerelles de paiement de la boutique.

PaymentGatewayList

Méthodes de script utilisant 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 facultatif. Consultez la documentation de la méthode delete_if de Ruby.
.sort!	PaymentGatewayList	Trie les passerelles de paiement à l’aide de l’opérateur de comparaison ou d’un bloc de code facultatif. Consultez la documentation de la méthode sort! de Ruby.
.sort_by!	PaymentGatewayList	Trie les passerelles de paiement à l’aide d’un bloc de code facultatif. Consultez la documentation de la méthode sort_by! de Ruby.

PaymentGateway

Méthode	Type de retour	Description
.name	Chaîne	Retourne le nom de la passerelle de paiement.
.enabled_card_brands	Liste<chaîne>	Si la passerelle de paiement prend en charge les cartes de crédit, retourne une liste des types de cartes de crédit que la boutique accepte. Si la passerelle ne prend pas en charge les cartes de crédit, retourne une liste vide.
.change_name(String new_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 d’article de panier suivant, lorsqu’un client commande un produit qui n’est pas une carte-cadeau, le prix du produit est réduit de 9 $. De plus, le montant total que le client a dépensé au cours de toutes ses visites dans votre boutique est affiché :

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 :

• Les bases de Ruby
• La création de scripts
• Le test et le débogage de vos scripts
• La mise à jour de vos modèles Liquid pour les scripts
• Les scripts Shopify