# Personnalisation dynamique des options de livraison

Apprenez à créer différents tarifs de livraison pour vos clients.

Découvrez comment mettre à jour dynamiquement les options de livraison en fonction de l’adresse que votre client saisit lorsque vous utilisez Checkout.

### Cas d’utilisation

- **Valider une adresse** : Confirmez si vous pouvez expédier un produit à l’adresse d’un client en utilisant vos propres règles de validation personnalisées. Vous pouvez également créer une interface utilisateur personnalisée permettant aux clients de confirmer leur adresse préférée.
- **Afficher les options de livraison pertinentes** : Affichez uniquement les modes de livraison disponibles, en fonction de l’adresse du client. Par exemple, proposez la livraison le lendemain uniquement pour les adresses dans votre pays.
- **Calculer de manière dynamique les frais de livraison** : Calculez et affichez les frais de livraison en fonction de l’adresse de livraison du client.
- **Mettre à jour les frais de livraison en fonction du montant total de la commande** : Proposez des frais de livraison basés sur l’adresse de livraison ou le montant total de la commande (par exemple, la livraison gratuite pour les commandes supérieures à 100 USD). Pour les paiements autorisant les changements de quantité ou les ventes croisées, consultez la page [Mise à jour dynamique des postes](https://docs.stripe.com/payments/checkout/dynamically-update-line-items.md).

### Limitations

- Uniquement pris en charge en [mode paiement](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-mode). Les [frais de livraison](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_options) ne sont pas disponibles en mode abonnement.
- Incompatible avec le [composant Element Express Checkout](https://docs.stripe.com/elements/express-checkout-element.md). Les wallets tels qu’Apple Pay et Google Pay collectent l’adresse de livraison directement, ce qui contourne le flux de mise à jour côté serveur uniquement. Lorsque `permissions.update_shipping_details` est défini sur `server_only`, ces wallets sont automatiquement désactivés.

> #### API Payment Intents
> 
> Si vous utilisez l’API Payment Intents, vous devez mettre à jour manuellement les options d’expédition et modifier le montant du paiement en fonction d’une option d’expédition établie, ou en créant un nouveau PaymentIntent avec des montants réajustés.

## Configurer les autorisations de mise à jour pour la session Checkout [Côté serveur]

Définissez le paramètre : [ shipping_address_collection.allowed_countries ](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-shipping_address_collection-allowed_countries) en fonction de la liste des pays vers lesquels vous souhaitez proposer des services d’expédition.

Lorsque vous créez la session Checkout, transmettez l’option [ permissions.update_shipping_details=server_only ](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-permissions-update_shipping_details) pour désactiver la méthode [ updateShippingAddress ](https://docs.stripe.com/js/custom_checkout/update_shipping_address) côté client et permettre la mise à jour de l’adresse de livraison et des options d’expédition à partir de votre serveur.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d ui_mode=elements \
  -d "permissions[update_shipping_details]=server_only" \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  --data-urlencode "return_url=https://example.com/return"
```

## Personnaliser les options de livraison [Côté serveur]

Créer un endpoint sur votre serveur pour calculer les options de livraison établies en fonction de l’adresse de livraison du client.

1. [Récupérez ](https://docs.stripe.com/api/checkout/sessions/retrieve.md) la [Session Checkout ](https://docs.stripe.com/api/checkout/sessions/object.md) en utilisant le `checkoutSessionId` du corps de la requête.
2. Validez les informations de livraison du client fournies dans le corps de la demande.
3. Établir les options de livraison en fonction de l’adresse de livraison du client et des postes de la session Checkout.
4. [ Mettez à jour ](https://docs.stripe.com/api/checkout/sessions/update.md) la session Checkout avec les [ shipping_details ](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-collected_information-shipping_details) et les [ shipping_options ](https://docs.stripe.com/api/checkout/sessions/update.md#update_checkout_session-shipping_options) du client.

#### Ruby

```ruby
require 'sinatra'
require 'json'
require 'stripe'

set :port, 4242

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

# Return a boolean indicating whether the shipping details are valid
def validate_shipping_details(shipping_details)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Validate the shipping details the customer has entered.
  MSG
end

# Return an array of the updated shipping options or the original options if no update is needed
def calculate_shipping_options(shipping_details, session)
  # TODO: Remove error and implement...
  raise NotImplementedError.new(<<~MSG)
    Calculate shipping options based on the customer's shipping details and the
    Checkout Session's line items.
  MSG
end

post '/calculate-shipping-options' do
  content_type :json
  request.body.rewind
  request_data = JSON.parse(request.body.read)

  checkout_session_id = request_data['checkout_session_id']
  shipping_details = request_data['shipping_details']

  # 1. Retrieve the Checkout Session
  session = client.v1.checkout.sessions.retrieve(checkout_session_id)

  # 2. Validate the shipping details
  if !validate_shipping_details(shipping_details)
    return { type: 'error', message: "We can't ship to your address. Please choose a different address." }.to_json
  end

  # 3. Calculate the shipping options
  shipping_options = calculate_shipping_options(shipping_details, session)

  # 4. Update the Checkout Session with the customer's shipping details and shipping options
  if shipping_options
    client.v1.checkout.sessions.update(checkout_session_id, {
      collected_information: { shipping_details: shipping_details },
      shipping_options: shipping_options
    })

    return { type: 'object', value: { succeeded: true } }.to_json
  else
    return { type: 'error', message: "We can't find shipping options. Please try again." }.to_json
  end
end
```

## Mettre à jour le SDK client [Côté client]

#### HTML + JS

Initialiser Stripe.js.

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

#### React

Initialiser l’instance `stripe`.

```bash
npm install --save @stripe/react-stripe-js@^5.0.0 @stripe/stripe-js@^8.0.0
```

```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<<YOUR_PUBLISHABLE_KEY>>");
```

## Requête de mise à jour du serveur [Côté client]

#### HTML + JS

Créez une fonction asynchrone qui envoie une requête à votre serveur pour mettre à jour les options d’expédition et encapsulez-la dans [ runServerUpdate ](https://docs.stripe.com/js/custom_checkout/run_server_update) Une requête réussie met à jour l’objet [ Sessions ](https://docs.stripe.com/js/custom_checkout/session_object) avec les nouvelles options d’expédition.

L’exemple de code suivant montre comment mettre à jour les options de livraison avec l’`AddressElement`.

```html
  <div id="shipping-form">
    <!-- Shipping Address Element will be mounted here -->
    <div id="shipping-address-element"></div>
    <button id="save-button">Save</button>
    <div id="error-message"></div>
  </div>

  <div id="shipping-display" style="display: none">
    <div id="address-display"></div>
    <button id="edit-button">Edit</button>
  </div>
```

```javascript
// mount the Shipping Address Element
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address-element');

const toggleViews = (isEditing) => {
  document.getElementById('shipping-form').style.display = isEditing ? 'block' : 'none';
  document.getElementById('shipping-display').style.display = isEditing ? 'none' : 'block';
}

const displayAddress = (address) => {
  const displayDiv = document.getElementById('address-display');
  displayDiv.innerHTML = `
    <div>${address.name}</div>
    <div>${address.address.line1}</div>
    <div>${address.address.city}, ${address.address.state} ${address.address.postal_code}</div>
  `;
}

const updateShippingOptions = async (shippingDetails) => {
  const response = await fetch("/calculate-shipping-options", {
    method: "POST",
    headers: { 'Content-type': 'application/json' },
    body: JSON.stringify({
      checkout_session_id: 'session_id',
      shipping_details: shippingDetails
    })
  });

  const result = await response.json();

  if (result.type === 'error') {
    document.getElementById('error-message').textContent = result.message;
    toggleViews(true);
  } else {
    document.getElementById('error-message').textContent = '';
    toggleViews(false);
    displayAddress(actions.getSession().shippingAddress);
  }

  return result;
}

const handleSave = async () => {
  const addressElement = await checkout.getShippingAddressElement();
  if (!addressElement) {
    return;
  }

  const result = await addressElement.getValue();
  if (!result.complete) {
    return;
  }

  try {
    await checkout.runServerUpdate(() => updateShippingOptions(result.value));
  } catch (error) {
    document.getElementById('error-message').textContent = error?.message;
    toggleViews(true);
  }
}

// Event Listeners
document.getElementById('save-button').addEventListener('click', handleSave);
document.getElementById('edit-button').addEventListener('click', () => toggleViews(true));
```

#### React

Créez une fonction asynchrone qui envoie une requête à votre serveur pour mettre à jour les options d’expédition et encapsulez-la dans [ runServerUpdate ](https://docs.stripe.com/js/custom_checkout/run_server_update) Une requête réussie met à jour l’objet [ Sessions ](https://docs.stripe.com/js/custom_checkout/session_object) avec les nouvelles options d’expédition.

L’exemple de code suivant montre comment mettre à jour les options de livraison avec l’`AddressElement`.

```jsx
import React from 'react';
import {useCheckoutElements, ShippingAddressElement} from '@stripe/react-stripe-js/checkout';

const Shipping = () => {
  const [editing, setEditing] = React.useState(true);
  const [error, setError] = React.useState(null);
  const checkoutState = useCheckoutElements();
  if (checkoutState.type === 'loading') {
    return (
      <div>Loading...</div>
    );
  } else if (checkoutState.type === 'error') {
    return (
      <div>Error: {checkoutState.error.message}</div>
    );
  }
  const {runServerUpdate, id, shippingAddress, getShippingAddressElement} = checkoutState.checkout;

  const updateShippingOptions = async (shippingDetails) => {
    const response = await fetch("/calculate-shipping-options", {
      method: "POST",
      headers: {
        'Content-type': 'application/json',
      },
      body: JSON.stringify({
        checkout_session_id: id,
        shipping_details: shippingDetails,
      })
    });

    if (response.type === 'error') {
      setError(response.message);
      setEditing(true);
    } else {
      setError(null);
      setEditing(false);
    }

    return result;
  }

  const handleEdit = (event) => {
    event.preventDefault();
    setEditing(true);
  }

  const handleSave = async () => {
    const addressElement = getShippingAddressElement();
    if (!addressElement) {
      return;
    }
    const aeValue = await addressElement.getValue();
    if (!aeValue.complete) {
      return;
    }

    try {
      await runServerUpdate(() => updateShippingOptions(aeValue.value));
    } catch (e) {
      setError(e?.message);
      setEditing(true);
    }
  }

  if (!editing && shippingAddress) {
    const {line1, line2, city, postal_code, state, country} = shippingAddress.address;
    return (
      <div>
        <div>{shippingAddress.name}</div>
        <div>{line1}</div>
        <div>{line2}</div>
        <div>
          {city} {state} {postal_code} {country}
        </div>
        <button onClick={handleEdit}>Edit</button>
      </div>
    );
  }

  return (
    <div>
      <AddressElement options={{mode: 'shipping'}} />
      <button onClick={handleSave}>
        Save
      </button>
      {error && <div>{error}</div>}
    </div>
  );
};
```

## Tester l’intégration

Suivez ces étapes pour tester votre intégration et vous assurer que vos options de livraison personnalisées fonctionnent correctement.

1. Configurez un environnement de test qui reflète votre configuration en mode production. Utilisez les clés API d’environnement de test Stripe pour cet environnement.

2. Simulez différentes adresses de livraison pour vérifier que votre fonction `calculateShippingOptions` traite correctement les différents scénarios.

3. Vérifiez la logique côté serveur en utilisant des outils de journalisation ou de débogage pour confirmer que votre serveur&nbsp;:

   - Récupère la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md).
   - Valide les informations de livraison.
   - Calcule les options de livraison.
   - Ajoute de nouvelles informations et options de livraison à la [session Checkout](https://docs.stripe.com/api/checkout/sessions/object.md). Assurez-vous que la réponse de modification contient les nouvelles informations et options d’expédition.

4. Vérifiez la logique côté client en effectuant plusieurs fois le processus de paiement dans votre navigateur. Observez la façon dont l’interface utilisateur se met à jour après avoir saisi les informations de l’expédition. Vérifiez que&nbsp;:

   - La fonction `runServerUpdate` est appelée comme prévu.
   - Les options de livraison sont correctement mises à jour en fonction de l’adresse fournie.
   - Les messages d’erreur s’affichent correctement lorsque l’expédition n’est pas disponible.

5. Saisissez des adresses de livraison non valides ou simulez des erreurs de serveur pour tester la gestion des erreurs, côté serveur et côté client.