> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Tax

> Découvrez comment configurer Stripe Tax avec Metronome pour le calcul automatique de la sales tax sur les factures Stripe.

[Stripe Tax](https://docs.stripe.com/tax) est le moteur natif de calcul de taxe de Stripe. Une fois configuré, Stripe calcule et applique automatiquement la sales tax aux factures que Metronome crée dans Stripe.

<Note>
  Cette page couvre **Stripe Tax** — le produit de taxe de Stripe. Si vous utilisez **Anrok** ou **Avalara** via l'[intégration Stripe Tax](https://docs.stripe.com/tax/third-party-apps), consultez la [configuration d'Anrok](/fr/integrations/tax-integrations/anrok) ou la [configuration d'Avalara](/fr/integrations/tax-integrations/avalara).
</Note>

## Prérequis

Avant de commencer :

1. [Activez et configurez Stripe Tax](https://docs.stripe.com/tax/set-up) dans votre dashboard Stripe sous **Settings > Tax**.
   1. [Effectuez l'enregistrement fiscal](https://docs.stripe.com/tax/registering) dans les juridictions applicables pour la sales tax, la TVA et la GST.
2. [Connectez votre compte Stripe](/fr/integrations/invoice-integrations/stripe) à Metronome.
3. Liez chaque client Metronome à son Stripe customer ID.
4. Assurez-vous que chaque client Stripe a une [**Customer Address**](https://docs.stripe.com/api/customers/object#customer_object-address) définie et est marqué comme **Taxable**.
5. Une fois la configuration initiale terminée, informez-en votre représentant Metronome pour qu'il puisse activer l'application de la taxe sur votre compte.

<Note>
  Le champ Customer Address est l'objet `address` sur l'[objet Customer de Stripe](https://docs.stripe.com/api/customers/object#customer_object-address), qui détermine la juridiction fiscale. L'absence d'attribution d'une Customer Address entraîne l'échec de l'application de la taxe.
</Note>

## Étape 1 : Créer des produits Stripe

Stripe Tax utilise le **produit** de chaque ligne de facture pour [déterminer le tax code applicable](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior) et le taux. Créez au moins un produit Stripe et attribuez-lui le [tax code](https://docs.stripe.com/tax/tax-codes) approprié dans Stripe (sous **Product Settings > Tax code**).

Vous pouvez mapper plusieurs produits Metronome au même produit Stripe tant qu'ils partagent le même tax code. Créez des produits Stripe supplémentaires uniquement lorsque vous avez besoin d'une classification fiscale différente.

## Étape 2 : Créer le champ personnalisé Stripe Product ID dans Metronome

Créez un [champ personnalisé](/fr/api-reference/custom-fields) sur l'entité **Product** dans Metronome pour stocker l'ID du produit Stripe :

1. Allez dans **General Settings > Custom fields** (ou utilisez l'API Custom fields).
2. Créez un nouveau champ personnalisé :
   * **Entity** : Product
   * **Key** : `stripe_product_id`
3. Pour chaque produit Metronome, définissez la valeur de `stripe_product_id` sur l'ID de produit Stripe correspondant (par exemple, `prod_ABC123`).

<Warning>
  **N'activez pas** « Enforce uniqueness » (`enforce_uniqueness`). Le même Stripe product ID est intentionnellement réutilisé pour plusieurs produits Metronome. L'activation de l'unicité ne peut pas être annulée — vous devrez archiver le champ et en créer un nouveau.
</Warning>

## Étape 3 : Configurer le mapping d'entité

Configurez le mapping d'entité afin que Metronome transmette l'ID du produit à Stripe sur chaque ligne de facture :

1. Allez dans **Connections > Integrations > Stripe > Edit Mapping**.
2. Ajoutez le mapping suivant :

| Entité vendor Stripe | Clé vendor Stripe | Entité Metronome  | Clé Metronome       |
| -------------------- | ----------------- | ----------------- | ------------------- |
| `invoiceitem.price`  | `product`         | `ContractProduct` | `stripe_product_id` |

3. Cliquez sur **Save**.

**Optionnel : mappings d'entité supplémentaires**

Si vous devez transmettre des métadonnées supplémentaires, vous pouvez ajouter d'autres mappings :

| Entité Metronome                             | Entité Stripe            | Cas d'usage                                                                                            |
| -------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
| Product (n'importe quel champ personnalisé)  | `invoiceitem.metadata.*` | Transmettre des métadonnées au niveau de la ligne (par exemple, `TaxCode`)                             |
| Customer (n'importe quel champ personnalisé) | `invoice.metadata.*`     | Transmettre des métadonnées au niveau de la facture (par exemple, la classification fiscale du client) |

## Tester votre configuration

Après avoir terminé la configuration fiscale :

1. Créez un client de test dans votre environnement sandbox avec un client Stripe valide.
2. Générez une facture dans Metronome.
3. Vérifiez la facture Stripe correspondante pour confirmer que la taxe a été calculée et appliquée.

Si la taxe n'est pas calculée, vérifiez que :

* Stripe Tax est [**activé**](https://docs.stripe.com/tax/set-up) dans votre dashboard Stripe.
* Le client Stripe a une **Customer Address** et est **Taxable**.
* Le mapping d'entité est enregistré et le champ personnalisé `stripe_product_id` a des valeurs définies sur vos produits Metronome.
* Le produit Stripe a un [**tax code**](https://docs.stripe.com/tax/tax-codes) valide attribué.

<Note>
  Si la taxe automatique n'est pas appliquée sur les factures Stripe synchronisées, contactez votre représentant Metronome.
</Note>

## Facturation par seuil

Pour les clients utilisant des [seuils de solde prépayé](/fr/guides/customers-billing/optimize-customer-experience/prepaid-balance-thresholds) ou des spend thresholds, la taxe est configurée différemment des factures à terme échu.

<Warning>
  L'activation de la taxe au niveau du compte ne s'applique **pas** à la facturation par seuil — vous devez définir explicitement le type de taxe dans l'API.
</Warning>

Lors de la configuration de `payment_gate_config`, spécifiez `tax_type: "STRIPE"` et `"payment_type": "INVOICE"` :

```json theme={null}
{
  "prepaid_balance_threshold_configuration": {
    "is_enabled": true,
    "threshold_amount": 500,
    "recharge_to_amount": 1500,
    "commit": {
      "product_id": "<your-product-id>",
      "name": "Auto-recharge credits"
    },
    "payment_gate_config": {
      "payment_gate_type": "STRIPE",
      "tax_type": "STRIPE",
      "stripe_config": {
        "payment_type": "INVOICE"
      }
    }
  }
}
```

Il en va de même lors de l'ajout d'engagements ponctuels à paiement préalable via l'endpoint edit contract.

Pour les spend thresholds, la configuration est similaire :

```json theme={null}
{
  "spend_threshold_configuration": {
    "is_enabled": true,
    "threshold_amount": 5000,
    "commit": {
      "product_id": "<your-product-id>"
    },
    "payment_gate_config": {
      "payment_gate_type": "STRIPE",
      "tax_type": "STRIPE",
      "stripe_config": {
        "payment_type": "INVOICE"
      }
    }
  }
}
```

## Paramètres qui affectent la taxe

### Méthode d'encaissement : charge\_automatically versus send\_invoice

Les deux méthodes d'encaissement fonctionnent avec tous les fournisseurs de taxe. La méthode d'encaissement détermine ce qui se passe après la finalisation de la facture avec la taxe :

* `charge_automatically` — Stripe prélève le [moyen de paiement par défaut](https://docs.stripe.com/api/customers/update#update_customer-invoice_settings-default_payment_method) enregistré du client. Le client doit avoir un moyen de paiement par défaut défini dans Stripe avant la finalisation de la facture, sinon le paiement échouera. Le client ne reçoit pas d'e-mail de facture par défaut (mais vous pouvez activer les [Successful Payments](https://docs.stripe.com/invoicing/automatic-charging) pour les e-mails de reçu dans Stripe).
* `send_invoice` — Stripe envoie la facture par e-mail au client avec les instructions de paiement. Vous devez spécifier `days_until_due`.

<Info>
  La taxe est appliquée quelle que soit la méthode d'encaissement. Le choix entre ces méthodes est indépendant de votre configuration fiscale.
</Info>

### Laisser les factures en brouillon

Ce paramètre (sous **Connections > Integrations > Stripe > Settings**) contrôle si Metronome finalise immédiatement les factures dans Stripe ou les laisse en brouillon. La [taxe automatique](https://docs.stripe.com/tax) de Stripe calcule la taxe en ligne lorsque la facture est finalisée. Il est généralement recommandé de basculer cette préférence sur **OFF** pour le calcul automatique de la taxe lors de la synchronisation de la facture.

Si vous préférez laisser les factures en brouillon afin de pouvoir les examiner et les finaliser manuellement dans Stripe, cochez l'option « leave invoices as drafts » dans Metronome.

## FAQ et dépannage

**Q : Puis-je réutiliser le même produit Stripe pour plusieurs produits Metronome ?**

Oui, tant qu'ils partagent le même [tax code](https://docs.stripe.com/tax/tax-codes). Si vos produits sont taxés différemment, créez des produits Stripe distincts avec des tax codes différents.

**Q : Pourquoi ma facture de facturation par seuil ne calcule-t-elle pas la taxe ?**

L'activation de la taxe au niveau du compte ne s'applique qu'aux factures à terme échu. Pour la facturation par seuil, vous devez définir `tax_type: "STRIPE"` dans `payment_gate_config` lors de la création ou de la modification du contrat. Consultez la section [Facturation par seuil](#threshold-billing) ci-dessus.

**Q : Mes factures échouent ou sont finalisées sans taxe — que dois-je vérifier ?**

Les causes les plus courantes sont une [Customer Address](https://docs.stripe.com/api/customers/object#customer_object-address) manquante sur le client Stripe ou un mapping d'entité incomplet dans Metronome. Commencez par confirmer que le client Stripe dispose d'informations de localisation suffisantes pour calculer avec précision les taux de taxe applicables. Vérifiez ensuite si le mapping d'entité est complet dans Metronome. Si les deux sont vérifiés et que la taxe n'est toujours pas appliquée, contactez votre représentant Metronome pour vérifier la configuration de votre compte.

**Q : Dois-je définir un comportement de taxe par défaut dans Stripe ?**

Dans le dashboard Stripe, assurez-vous d'avoir un comportement de taxe par défaut sélectionné pour garantir que la taxe est correctement ajoutée à chaque facture.