Générer des avoirs de manière programmatique

Pour réajuster le solde d’une facture open ou paid, générez un avoir.

Lorsque vous créez un avoir, vous pouvez appliquer des montants d’avoirs de trois manières différentes :

• Réduction d’un montant fixe sur un poste de facture.
• Réduction sur une quantité d’un poste de facture. La réduction totale est égale au montant de la réduction multipliée par le prix unitaire de ce poste.
• Appliquez une réduction au montant total de la facture en ajoutant un poste de réduction personnalisé avec une description, une quantité et un prix unitaire. La réduction totale correspond à la quantité multipliée par le prix unitaire.

Nous vous recommandons dans la mesure du possible d’appliquer des réductions aux postes de facture, car chaque avoir est associé à un poste de facture. L’ajout d’un poste de réduction personnalisé peut compliquer le reporting et le suivi, car l’avoir n’est pas associé à un poste de facture réel.

Avoirs sur les factures en cours

Lorsque vous créez un poste personnalisé sur un avoir pour une facture à l’état open, amount_due sur la facture est diminué en fonction des custom_line_items dans l’avoir. Cela s’ajoute aux réajustements effectués aux invoice_line_items existants. Par exemple, si le montant dû sur une facture à l’état open est de 100 dollars et que vous créez un custom_line_item avec quantity=1 et unit_amount=2000, le nouveau montant dû sur la facture est de 80 dollars.

Sur une facture, les avoirs apparaissent comme des postes après application des ristournes et des taxes. Il s’agit donc d’un montant ajusté après taxes. Nous calculons le montant dû de la facture dans l’ordre suivant :

1. Somme des postes de la facture
2. Ristournes
3. Total de la facture avant imposition
4. Taxes
5. Solde créditeur du client
6. Avoirs appliqués (au montant brut dû)
7. Nouveau montant dû

Si l’application d’un avoir à une facture modifie le montant dû de la facture à zéro, la facture passe automatiquement à l’état paid. Si vous voulez modifier la quantité ou le montant d’un poste existant, indiquez le numéro de facture, le numéro de poste et la nouvelle quantité ou nouveau montant. Lorsqu’un poste possède déjà une quantité et un montant, vous pouvez seulement mettre à jour la quantité. Sinon, vous ne pouvez que modifier le montant. L’exemple ci-dessous ajuste la quantité à deux :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{INVOICE_LINE_ITEM}} \
  -d "lines[0][quantity]"=2

Pour créer un poste personnalisé sur l’avoir, indiquez un numéro de facture, une description, la quantité et le montant unitaire. Si vous le souhaitez, vous pouvez aussi définir un taux de taxe. Cet exemple crée un poste personnalisé sur l’avoir pour 10 dollars :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=custom_line_item \
  -d "lines[0][description]"="Courtesy credit" \
  -d "lines[0][quantity]"=1 \
  -d "lines[0][unit_amount]"=1000

Avoirs sur les factures réglées

Lorsque vous créez un avoir pour une facture à l’état paid, le montant dû sur la facture n’est pas modifié. En revanche, l’utilisateur peut choisir une ou plusieurs des options suivantes :

Dans l’exemple suivant, l’avoir génère un remboursement :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{INVOICE_LINE_ITEM}} \
  -d "lines[0][quantity]"=2 \
  -d refund_amount=500

Ici, l’avoir génère un crédit sur le solde créditeur du client :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{INVOICE_LINE_ITEM}} \
  -d "lines[0][quantity]"=2 \
  -d credit_amount=500

Vous pouvez aussi combiner plusieurs paramètres. Les fonds restants après avoir soustrait les montants du remboursement et du crédit de la valeur amount de la facture provoquent un crédit en dehors de Stripe, en général en espèces ou par chèque :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{INVOICE_LINE_ITEM}} \
  -d "lines[0][quantity]"=2 \
  -d refund_amount=100 \
  -d credit_amount=200 \
  -d out_of_band_amount=200

Annulation des avoirs

Vous pouvez annuler un avoir uniquement s’il figure sur une facture en cours. L’annulation d’un avoir annule son réajustement et restaure le montant dû sur la facture au montant antérieur à l’application de l’avoir. Pour annuler un avoir :

curl -X POST https://api.stripe.com/v1/credit_notes/{{CREDIT_NOTE_ID}}/void \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Créditer des poste négatifs

Vous pouvez associer un avoir négatif à un invoice_line_item négatif en utilisant les paramètres amount ou quantity.

Par exemple, si vous avez une facture à l’état open comportant deux postes :

• un poste positif avec quantity=1 et unit_amount=10000
• et un poste négatif avec quantity=1 et unit_amount=-5000.

Cet exemple utilise le paramètre amount pour créer un avoir correspondant au montant total de chaque poste :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{POSITIVE_INVOICE_LINE_ITEM}} \
  -d "lines[0][amount]"=10000 \
  -d "lines[1][type]"=invoice_line_item \
  -d "lines[1][invoice_line_item]"={{NEGATIVE_INVOICE_LINE_ITEM}} \
  -d "lines[1][amount]"=-5000

Cet exemple utilise le paramètre quantity pour faire la même chose :

curl https://api.stripe.com/v1/credit_notes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d invoice={{INVOICE_ID}} \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"={{POSITIVE_INVOICE_LINE_ITEM}} \
  -d "lines[0][quantity]"=1 \
  -d "lines[1][type]"=invoice_line_item \
  -d "lines[1][invoice_line_item]"={{NEGATIVE_INVOICE_LINE_ITEM}} \
  -d "lines[1][quantity]"=1

Cette fonctionnalité est soumise aux restrictions suivantes :

• Le montant total de l’avoir doit rester positif.
• Le montant total crédité pour un poste de facture négatif doit être négatif.
• Le montant total crédité pour un poste négatif ne peut pas être inférieur au montant du poste de facture.

Vous ne pouvez pas non plus créer d’avoir négatif pour un poste custom_line_item. Nous prenons uniquement en charge les avoirs de montants négatifs portant sur des postes invoice_line_items.