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

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.

<p>Certaines méthodes <a href="#shipping-methods">ne sont utilisables que dans les scripts d'expédition</a>.</p>

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.

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éthodeType de retourDescription
.cartPanierRenvoie un objet de panier modifiable.
. paramètres régionauxchaîneRenvoie les paramètres régionaux du client. Par exemple, en , fr , or pt-BR .
### Panier

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

Méthodes de script utilisant l’objet Cart
MéthodeType de retourDescription
.customerClientRenvoie le propriétaire du panier (le cas échéant).
.shipping_addressShippingAddressRenvoie l'adresse d'expédition du propriétaire du panier (le cas échéant).
.discount_codevarie 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.

<p><a href="/manual/checkout-settings/script-editor/examples/vat-script">Voir un exemple de <code>discount_code</code></a>.</p>
  </td>
</tr>
<tr>
  <td scope="row">.line_items</td>
  <td>

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_priceArgent (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_weightgramsRenvoie le poids total de toutes les rubriques du panier.
#### CartDiscount::FixedAmount
Méthodes de script utilisant l’objet CartDiscount:: FixedAmount
MéthodeType de retourDescription
.codeChaîneRenvoie le code de réduction utilisé pour appliquer la réduction.
.amountArgent (filtre financier)Renvoie le montant de la réduction.
.reject({ message: String })nilRejette le code de réduction appliqué au panier. Un message est requis.
.rejected?BooléenIndique si le code de réduction a été rejeté ou non.
#### CartDiscount::Percentage
Méthodes de script utilisant l’objet CartDiscount::P ercentage
MéthodeType de retourDescription
.codeChaîneRenvoie le code de réduction utilisé pour appliquer la réduction.
.percentageDécimaleRenvoie le pourcentage de la réduction.
.reject({ message: String })nilRejette le code de réduction appliqué au panier. Un message est requis.
.rejected?BooléenIndique si le code de réduction a été rejeté ou non.
#### CartDiscount::Shipping
Méthodes de script utilisant l’objet CartDiscount:: Shipping
MéthodeType de retourDescription
.codeChaîneRenvoie le code de réduction utilisé pour appliquer la réduction.
.reject({ message: String })nilRejette le code de réduction appliqué au panier. Un message est requis.
.rejected?BooléenIndique si le code de réduction a été rejeté ou non.
### Client
Méthodes de script utilisant l’objet Customer
MéthodeType de retourDescription
.idEntierRenvoie le numéro d'identification du client.
.emailChaîneRenvoie 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_countEntierRenvoie le nombre total de commandes passées par un client.
.total_spentArgent (filtre financier)Renvoie le montant total dépensé par le client sur toutes les commandes.
.accepts_marketing?BooléenIndique si le client accepte les communications marketing.
### LineItem {#lineitem-method}
Méthodes de script utilisant l’objet rubrique
MéthodeType de retourDescription
.gramsgramsRenvoie le poids total de la rubrique.
.line_priceArgent (filtre financier)Le prix de la rubrique.
.discounted?BooléenRetourne 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.
.propertieshashRenvoie les propriétés spécifiées pour cette rubrique.
.variantVarianteRenvoie la variante spécifique du produit représenté par la rubrique.
.quantityEntierRenvoie la quantité de cette rubrique.
.selling_plan_idEntierRenvoie 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
<tr>
  <td scope="row">.empty?</td>
  <td>Booléen</td>
  <td>
    <p>Renvoie <code>true</code> si la liste ne contient aucun élément</p>
  </td>
</tr>
<tr>
  <td scope="row">.first</td>
  <td>Élément ou nul</td>
  <td>
    <p>Renvoie le premier élément ou <code>nil</code> si la liste est vide.</p>
  </td>
</tr>
<tr>
  <td scope="row">.index(*args, &amp;block)</td>
  <td>int ou nil</td>
  <td>
    <p>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.</p>
  </td>
</tr>
<tr>
  <td scope="row">.rindex(*args, &amp;block)</td>
  <td>int ou nil</td>
  <td>
    <p>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.</p>
  </td>
</tr>
<tr>
  <td scope="row">.last</td>
  <td>Élément ou nul</td>
  <td>
    <p>Renvoie le dernier élément ou <code>nul</code> si la liste est vide.</p>
  </td>
</tr>
<tr>
  <td scope="row">

.length

Méthodes de script utilisant l’objet List
MéthodeType de retourDescription
.newListeCré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_ifListeSupprime les éléments à l'aide d'un bloc de code facultatif. Voir la documentation sur la méthode delete_if de Ruby.
int

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

.sizeint

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éthodeType de retourDescription
.namechaîneRenvoie le nom de la personne associée à l'adresse d'expédition.
.address1chaîneRenvoie la partie de l'adresse d'expédition correspondant à la rue.
.address2chaîneRenvoie le champ supplémentaire facultatif de la partie de l'adresse d'expédition correspondant à la rue.
.phonechaîneRenvoie le numéro de téléphone de l'adresse d'expédition.
.citychaîneRenvoie la ville de l'adresse d'expédition.
.zipchaîneRenvoie le code postal de l'adresse d'expédition.
.provincechaîneRenvoie la province, l'État fédéral ou la région de l'adresse d'expédition.
.province_codechaîneRenvoie la valeur abrégée de la province ou de l'État de l'adresse d'expédition.
.country_codechaîneRenvoie le code ISO du pays de l'adresse d'expédition.
### Argent (filtre financier)
Méthodes de script utilisant l’objet Money
MéthodeType de retourDescription
.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).
.newArgent (filtre financier)Crée un nouvel objet pour représenter un prix.
.zeroArgent (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éthodeType de retourDescription
.idEntierRenvoie le numéro d'identification de la variante.
.priceArgent (filtre financier)Renvoie le prix à l'unité de la variante.
.productProduitRenvoie 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.
.titleChaîneRenvoie le titre de la variante.
### Produit
Méthodes de script utilisant l’objet Product
MéthodeType de retourDescription
.idEntierRenvoie le numéro d'identification du produit.
.gift_card?BooléenIndique 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_typeChaîneCatégorisation pouvant être associée à produit par une balise, couramment utilisée pour le filtrage et les recherches.
.fournisseurChaîneRenvoie 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éthodeType de retourDescription
.exitnoneTermine 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éthodeType de retourDescription
.subtotal_price_wasArgent (filtre financier)Renvoie le sous-total du panier avant l'application des codes de réduction.
.subtotal_price_changed?BooléenIndique si le sous-total a changé.
### LineItem
Méthodes de script utilisant l’objet rubrique dans les scripts de rubrique
MéthodeType de retourDescription
.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_priceArgent (filtre financier)Renvoie le prix normal de la rubrique avant l'application des scripts et des codes de réduction.
.line_price_wasArgent (filtre financier)Renvoie le prix de la rubrique avant les modifications appliquées par le script en cours.
.line_price_changed?BooléenIndique si le prix de la rubrique a changé.
.change_properties(hash new_properties, { message: String }) hashDé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_washashRenvoie la valeur de hachage d'origine des propriétés de la rubrique avant l'application des modifications.
.properties_changed?BooléenIndique si les propriétés pour la rubrique ont été modifiées.
.split({ take: Integer })LineItemDivise 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 {#ex-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éthodeType de retourDescription
.compare_at_priceArgent (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éthodeType de retourDescription
.shipping_ratesShippingRateListRenvoie 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éthodeType de retourDescription
.delete_ifShippingRateListSupprime 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!ShippingRateListTrie 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!ShippingRateListTrie 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éthodeType de retourDescription
.codeChaîneRenvoie le code du tarif d'expédition.
.markupArgent (filtre financier)Renvoie le balisage du tarif d’expédition, le cas échéant.
.nameChaîneRenvoie le nom des frais d’expédition. Il est possible de le modifier en utilisant la méthode change_name.
.priceArgent (filtre financier)Renvoie le montant des frais d'expédition.
.sourceChaîneRenvoie 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éenRenvoie 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éthodeType de retourDescription
.payment_gatewaysPaymentGatewaysListRenvoie 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éthodeType de retourDescription
.delete_ifPaymentGatewayListSupprime les passerelles de paiement à l'aide d'un bloc de code optionnel. Voir la documentation sur la méthode delete_if de Ruby.
.sort!PaymentGatewayListTrie 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!PaymentGatewayListTrie 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éthodeType de retourDescription
.nameChaîneRenvoie 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îneModifie 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 :

Vous ne trouvez pas les réponses que vous recherchez ? Nous sommes là pour vous aider.