Skip to main content

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.

​
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: 
{
  "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

SettingAction
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

SettingValuesDefaultDescription
Create invoice asDraft / OpenDraftDraft: invoice is created but not finalized. Open: invoice is finalized immediately.
Send invoice by email (via Stripe)Yes / NoNoStripe sends the finalized invoice to the customer. Only active when invoice is Open.
Send payment link + invoice (via Qwoty)Yes / NoNoSends a Stripe Checkout payment link and the invoice PDF via email. Only active when invoice is Open.
Payment methodStripe defaultStripe defaultPayment 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.
FieldValue
Invoice total€9,102.00
First installment€2,275.50 (25%)
Payment link amount€2,275.50
PDF attachedStripe invoice PDF
Link expiry24 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.