> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Stripe - Invoice
> Automatically create and send a Stripe invoice to your customer when a quote is accepted.
## Overview
The **Stripe — Invoice** integration creates a Stripe invoice from the line items of a Qwoty quote and optionally finalizes and delivers it to your customer.
Depending on your settings, the invoice can be sent directly via Stripe, or paired with a Stripe Checkout payment link and delivered by email via Qwoty with the invoice PDF attached.
***
## Authentication
Go to **Stripe Dashboard → Developers → API keys** and copy your secret key (`sk_live_...` in production, `sk_test_...` in test mode).
The secret key requires the following Stripe permissions:
* **Customers** — read and write (create, search)
* **Invoices** — read and write (create, finalize, send, attach payment)
* **Invoice items** — write (create)
* **Tax rates** — read and write (list, create)
* **Checkout Sessions** — write (create)
* **Webhook endpoints** — read and write (list, create)
Two token scopes are available depending on your organization:
**Workspace** — a single Stripe key shared across all quotes. Enter it in the **Workspace API token** field.
**Business unit** — a different Stripe key per business unit. Enter a JSON map in the **Business unit API tokens** field:
```json theme={null}
{
"business_unit_id_1": "sk_live_...",
"business_unit_id_2": "sk_live_..."
}
```
In **Business unit** mode, the quote must be associated with a business unit whose ID is present in the map. If not, the invoice will not be created.
***
## Behavior
### Customer
The integration automatically finds or creates a Stripe customer for each quote:
1. If a Stripe customer ID is already saved on the Qwoty contact (`external_ids.accounting`), it is used directly.
2. Otherwise, a search is performed in Stripe — first by Qwoty contact UUID, then by billing email.
3. If no match is found, a new Stripe customer is created with the contact's name, email, and billing address. The Stripe customer ID is then saved back to the Qwoty contact for future use.
### Line items
One Stripe invoice item is created per billable product in the quote's `product` sections. If a line item has a discount, a second negative item is added on the same line.
Global discounts on the quote are added as a single negative invoice item at the bottom.
Only sections of type `product` are included. Recurring sections (`plan`) are not supported in this integration.
### Taxes
Tax rates are resolved automatically for each line item:
1. If a Stripe Tax Rate ID is already saved on the Qwoty tax (`external_ids.accounting`), it is used directly.
2. Otherwise, the integration searches existing Stripe Tax Rates by percentage and country (parsed from the Qwoty `api_name` format — e.g. `vat_fr_200` → France, 20%).
3. If no match is found, a new Tax Rate is created in Stripe and its ID is saved back to Qwoty.
Tax rates are always exclusive (prices shown before tax).
### Invoice status
If **Create invoice as Draft**, the invoice is created but not finalized. No email or payment link is sent regardless of other settings.
If **Create invoice as Open**, the invoice is finalized and one of the following actions is triggered:
### Post-finalization actions
| Setting | Action |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Send invoice by email (via Stripe)** | Stripe sends the finalized invoice directly to the customer's email. |
| **Send payment link + invoice (via Qwoty)** | A Stripe Checkout payment link is created for the first installment amount. An email is sent via Qwoty with the invoice PDF attached and a link to pay. Once the customer completes payment, the Checkout Session is automatically attached to the invoice via a Stripe webhook. |
If both options are disabled, the invoice is finalized but not sent.
The **Send payment link + invoice** option requires a Stripe webhook to be registered. The integration handles this automatically on first use — no manual configuration is needed.
***
## Settings
| Setting | Values | Default | Description |
| ------------------------------------------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| **Create invoice as** | Draft / Open | Draft | `Draft`: invoice is created but not finalized. `Open`: invoice is finalized immediately. |
| **Send invoice by email (via Stripe)** | Yes / No | No | Stripe sends the finalized invoice to the customer. Only active when invoice is Open. |
| **Send payment link + invoice (via Qwoty)** | Yes / No | No | Sends a Stripe Checkout payment link and the invoice PDF via email. Only active when invoice is Open. |
| **Payment method** | Stripe default | Stripe default | Payment methods presented to the customer on the Checkout page. |
***
## Examples
**Accepted quote — 4 installments of €2,275.50**
The quote has 4 installments. The integration creates a Stripe invoice for the full amount and sends a Checkout payment link for the first installment (€2,275.50) by email.
| Field | Value |
| ------------------- | ------------------ |
| Invoice total | €9,102.00 |
| First installment | €2,275.50 (25%) |
| Payment link amount | €2,275.50 |
| PDF attached | Stripe invoice PDF |
| Link expiry | 24 hours |
Once the customer pays the Checkout Session, the payment is automatically attached to the invoice. The invoice status moves to `partially_paid`, and subsequent installments can be sent the same way.