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

Cette page a été imprimée le Sep 09, 2024. 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éthodes ne sont utilisables que dans les scripts de rubrique.

Scripts d'expédition

Les scripts d'expédition interagissent avec l'expédition et 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éthodes ne sont utilisables que dans les scripts d'expédition.

Scripts de paiement

Les scripts de paiement interagissent avec les paiements et 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éthodes ne sont utilisables que dans les scripts de paiement.

Sur cette page

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 , or pt-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_code est 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_code est toujours présent, mais le prix du panier ne change pas.

Voir un exemple de discount_code.
.line_items List<LineItem> Renvoie une liste contenant toutes les rubriques du panier.
.presentment_currency List<String> Renvoie la devise locale (présentation) du client (au format ISO 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. Un message est 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. Un message est 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. Un message est 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 numéro d'identification du client.
.email Chaîne Renvoie l'adresse e-mail du client.
.tags List<Tag> 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

<tdgrams
Méthodes de script utilisant l’objet rubrique
Méthode Type de retour Description
.grams Renvoie le poids total de la rubrique.
.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 est vendue 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 la méthode delete_if de Ruby.
.empty? Booléen

Renvoie true si la liste ne contient aucun élément
.first Élément ou nul

Renvoie le premier élément ou nil si 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 ou nul si 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 le code ISO du pays de l'adresse d'expédition.

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ètre customer_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 objets Money (financiers).
- Argent (filtre financier) Soustrait un objet Money (financier) d'un autre.
* Argent (filtre financier) Multiplie un objet Money (financier) par un nombre.

Exemples Argent

Money.new(cents: 1000)

Crée un objet Money représentant 1000 cents, ou 10 $.

Money.new(cents: 100) * 50

Crée un objet Money représentant 1 $, puis multiplie de 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'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<String> 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<Tag> 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.
.fournisseur Chaîne Renvoie le vendeur de ce produit.

Kernel

Kernel est 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 none Termine l'exécution du script actuel sans erreur. En cas d'exécution sans qu'aucun élément n'ait été associé avec Output.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.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

Méthodes de rubrique

Les méthodes suivantes sont uniquement utilisables dans les scripts 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(Money new_price, { message: String }) Argent (filtre financier) Passe le prix de la rubrique au montant spécifié. Un message est 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(hash new_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 dans properties_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. take indique quelle quantité doit être retirée de la rubrique d'origine pour en créer une deuxième.

Exemple .split

Cet exemple de script divise en deux une rubrique intitulée original_line_item. La nouvelle rubrique a une quantité de 1 (spécifiée par take: 1). Le script applique alors un prix réduit à la nouvelle rubrique avec le message suivant : « 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 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. Renvoie nil (nul) si la variante n’a pas de prix avant réduction.

Méthodes d'expédition

Les méthodes suivantes sont uniquement utilisables dans les scripts 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 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 optionnel. Voir la documentation sur la méthode sort! de Ruby.
.sort_by! ShippingRateList Trie les frais d'expéditions à l'aide d'un bloc de code optionnel. Voir la documentation sur 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 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éthode change_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(String new_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(Money discount, { 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 Renvoie true si un numéro de téléphone est requis pour obtenir les frais d'expédition, ou false dans le cas contraire.

Moyens de paiement

Les méthodes suivantes sont utilisables dans les scripts 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

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 optionnel. Voir la documentation sur la méthode delete_if de 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 la méthode sort! de Ruby.
.sort_by! PaymentGatewayList Trie les passerelles de paiement à l'aide d'un bloc de code optionnel. Voir la documentation sur la méthode sort_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<String>

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