Guide de migration des prix dans Checkout

L’API Prices apporte de nouvelles fonctionnalités et une plus grande flexibilité dans la manière de facturer les clients. Cette nouvelle intégration offre :

• Une modélisation plus unifiée pour les articles de Checkout de sorte qu’au lieu de plans, d’unités de gestion des stocks et de postes en série, chaque article est désormais un tarif.
• La possibilité de présenter les images de produit pour les postes récurrents.
• Créez un catalogue de produits et de tarifs réutilisables au lieu de postes ponctuels.
• Créer des tarifs en ligne pour des abonnements.
• Appliquer des taux de taxe dynamiques aux abonnements et aux paiements ponctuels.

Vous ne souhaitez pas effectuer la migration ? Vous pouvez continuer à utiliser votre intégration actuelle, mais les nouvelles fonctionnalités ne sont pas prises en charge. Vous pouvez utiliser toute nouvelle offre ou tout tarif récurrent que vous créez dans le paramètre plan de vos appels à l’API actuels.

Vue d’ensemble des produits et des prix

Les tarifs sont une nouvelle entité de base dans Stripe qui fonctionne avec les abonnements, les factures et Checkout. Chaque tarif est lié à un seul produit, et chaque produit peut avoir plusieurs tarifs. Les différents biens physiques ou niveaux de service doivent être représentés par des produits. La tarification de ce produit doit être représentée par des tarifs.

Les prix définissent le prix de base, la devise et, pour les produits récurrents, le cycle de facturation. Ceci vous permet de modifier ou d’ajouter des prix sans avoir à changer les détails de ce que vous proposez. Par exemple, vous pourriez avoir un seul produit « or » dont les prix sont de 10 USD/mois, 100 USD/an, 9 EUR/mois et 90 EUR/an, ou bien vous pourriez avoir un t-shirt bleu avec des prix de 20 USD et 15 EUR.

Paiements ponctuels

Voici les modifications apportées aux intégrations pour les paiements ponctuels :

• Au lieu de postes ad-hoc (c’est-à-dire configurer le nom, le montant et la devise), la création d’une session Checkout demande la création d’un produit et, généralement, d’un prix.
• Le mode est désormais requis.

Le code côté client reste le même.

Tableau de correspondance

Au lieu de définir chaque champ dans line_items, Checkout utilise les objets Product et Price sous-jacents pour déterminer le nom, la description, le montant, la devise et les images. Vous pouvez créer des produits et des prix à l’aide de l’API ou du Dashboard.

Code côté serveur pour les postes en série

Auparavant, vous pouviez uniquement créer des postes ponctuels en série. Avec l’API Prices, vous pouvez continuer à configurer vos postes en série, mais vous pouvez aussi définir vos tarifs de manière dynamique avec price_data lorsque vous créez la session Checkout.

Lorsque vous créez la session Checkout avec price_data, référencez un identifiant produit actuel avec price_data.product ou définissez les informations du produit de manière dynamique à l’aide de price_data.product_data. L’exemple suivant illustre le flux pour créer un poste ponctuel.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price_data][unit_amount]"=2000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][product_data][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][price_data][product_data][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][price_data][currency]"=usd \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Code côté serveur pour les prix ponctuels

Grâce à cette nouvelle intégration, vous pouvez créer un catalogue de produits et de prix à l’avance au lieu d’avoir à définir le montant, la devise et le nom chaque fois que vous créez une session Checkout.

Vous pouvez créer un produit et un prix avec l’API Price ou par le biais du Dashboard. Il vous faudra l’identifiant du prix pour créer la session Checkout. L’exemple suivant illustre comment créer un produit et un prix avec l’API :

curl https://api.stripe.com/v1/products \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d name=T-shirt \
  -d description="Comfortable cotton t-shirt" \
  -d "images[]"="https://example.com/t-shirt.png"

curl https://api.stripe.com/v1/prices \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d product="{{PRODUCT_ID}}" \
  -d unit_amount=2000 \
  -d currency=usd

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d mode=payment \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Abonnements

Voici les modifications apportées aux intégrations pour les paiements récurrents :

• Au lieu de subscription_data.items, tous les postes sont transmis dans un champ line_items unique.
• Le mode est désormais requis. Configurez mode=subscription si la session comprend des postes récurrents.

Le code côté client reste le même. Les plans actuels peuvent être utilisés partout où les prix récurrents sont acceptés.

Code côté serveur avec des plans

Voici un exemple avant et après la création d’une session Checkout avec un essai et l’utilisation d’un plan actuel, qui peut être utilisé de manière interchangeable avec un prix. Le plan est maintenant transmis dans line_items au lieu de subscription_data.items.

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "subscription_data[items][][plan]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Code côté serveur pour un prix récurrent avec des frais d’installation

Si vous avez des plans récurrents avec des frais d’installation ou initiaux, créez le produit et le prix représentant ces frais avant de créer la session Checkout. Consultez le tableau de correspondance pour savoir à quoi correspondent les anciens champs line_items dans la nouvelle intégration. Vous pouvez créer un produit ou un prix par le biais de l’API Prices ou du Dashboard Stripe. Vous pouvez également créer des postes ponctuels en série. L’exemple suivant utilise un identifiant de prix actuel :

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[0][amount]"=2000 \
  -d "line_items[0][name]"=T-shirt \
  -d "line_items[0][description]"="Comfortable cotton t-shirt" \
  -d "line_items[0][images][]"="https://example.com/t-shirt.png" \
  -d "line_items[0][currency]"=usd \
  -d "subscription_data[items][][plan]"="{{PLAN_ID}}" \
  -d "line_items[0][price]"="{{PRICE_OR_PLAN_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "line_items[1][price]"="{{ONE_TIME_PRICE_ID}}" \
  -d "line_items[1][quantity]"=1 \
  -d mode=subscription \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

Changements concernant l’objet Response

Au lieu de répertorier les postes avec display_items, l’objet Checkout Session utilise line_items. Le champ line_items ne s’affiche pas par défaut comme le faisait display_items, mais vous pouvez l’inclure en utilisant élargir lors de la création d’une session Checkout :

curl https://api.stripe.com/v1/checkout/sessions \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[]"="card" \
  -d "mode"="payment" \
  -d "line_items[0][price]"="{{PRICE_ID}}" \
  -d "line_items[0][quantity]"=1 \
  -d "success_url"="https://example.com/success" \
  -d "cancel_url"="https://example.com/cancel" \
  -d "expand[]"="line_items"

Changements concernant les webhooks

Depuis que line_items peut être inclus, la réponse du webhook checkout.session.completed n’affiche plus la liste des postes par défaut. L’objet Response plus petit vous permet de recevoir vos webhooks Checkout plus rapidement. Vous pouvez récupérer les postes avec le nouvel endpoint line_items :

curl https://api.stripe.com/v1/checkout/sessions/{{CHECKOUT_SESSION_ID}}/line_items \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Pour plus d’informations, consultez le guide sur la réalisation des commandes avec Checkout.