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 Billing integration transforms a signed Qwoty order into a Stripe Subscription Schedule. Each pricing plan phase becomes a Stripe phase with its own items, billing frequency, and duration. One-off charges (setup fees, hardware, onboarding) are attached as invoice items on the first billing cycle. Discounts are applied as native Stripe coupons at the item, phase, or add-invoice-item level. If the order contains a start delay, the integration automatically creates a trial period of that duration before billing begins.

​
Authentication

1

Access your Stripe Dashboard

Go to dashboard.stripe.com and sign in.
2

Create a restricted API key

Navigate to Developers → API keys → Create restricted key.Grant write access to: Customers, Subscriptions, Subscription Schedules, Invoices, Tax rates, Coupons.
3

Copy the secret key

Copy the key starting with sk_live_ (or sk_test_ for testing).
4

Paste into the integration settings

Paste the key into the Workspace API token field below.
If you use multiple Stripe accounts (one per business unit), set Token scope to business_unit and provide one key per business unit ID.

​
Settings

​
Authentication

KeyDefaultDescription
token_scopeworkspaceworkspace — one global key. business_unit — one key per business unit. Required.
workspace_api_token—Stripe secret key (if token_scope = workspace). Required.

​
Billing

KeyDefaultDescription
collection_methodcharge_automaticallyHow Stripe collects payment. charge_automatically charges the customer’s saved payment method. send_invoice sends an invoice by email.
days_until_due30Days the customer has to pay (only used when collection_method = send_invoice).
payment_behaviorallow_incompleteBehavior if the first payment fails. allow_incomplete — creates the subscription in incomplete status. default_incomplete — incomplete only if payment is required. error_if_incomplete — returns an error and does not create the subscription.

​
Taxes

KeyDefaultDescription
tax_modemanualautomatic — Stripe Tax computes tax rates automatically (requires Stripe Tax activation). manual — tax rates are taken from the Qwoty order and synced to Stripe.
When tax_mode = automatic, no tax rates from Qwoty are sent to Stripe. Stripe Tax must be configured in your Stripe Dashboard.

​
Trial

KeyDefaultDescription
trial_end_behaviorcreate_invoiceWhat happens if the customer has no payment method when the trial ends. create_invoice — generates an invoice anyway. pause — pauses the subscription. cancel — cancels the subscription.
A trial is created automatically when the order’s billing start type is sign_day with a delay_days > 0. The trial lasts exactly delay_days days.

​
Post-creation

KeyDefaultDescription
post_actionnoneAction after the schedule is created. none — nothing. send_email — sends a confirmation email via Qwoty.

​
Output

​
What gets created in Stripe

1. Customer (if not already linked) The integration looks up the customer by their Qwoty ID (stored in Stripe metadata), then by email. If not found, a new Stripe customer is created and the Stripe ID is written back to Qwoty (external_ids.accounting). 2. Coupons (one per unique discount amount) For each discount in the order, the integration looks up an existing Stripe coupon with the ID qwoty_{orderId}_{amountCents}_{currency}_{duration} before creating a new one. All Qwoty coupons are prefixed with qwoty_ for easy identification in your Stripe Dashboard. 3. Tax rates (manual mode only) Tax rates are resolved via external_ids.accounting on each tax entry. If not found, the integration searches Stripe by percentage and country, then creates a new tax rate if absent. 4. Subscription Schedule
CPQ sourceStripe fieldNotes
Customer resolvedcustomer
start.type = sign_daystart_date = "now"
start.type = datestart_dateUnix timestamp
Last phase foreverend_behavior = "release"Auto-renews
Last phase with endend_behavior = "cancel"Cancels at end
order.idmetadata.quote_id
order.quote_numbermetadata.quote_number
order.opportunity_idmetadata.opportunity_idIf set
Phases — one per CPQ plan phase:
CPQ sourceStripe fieldNotes
end.durationiterationsConverted to billing cycle count
end.dateend_dateUnix timestamp
end.forever(absent)Last phase, unlimited
delay_days > 0 (phase 0)trial_endUnix timestamp, now + delay_days
Items per phase — one per billable line item:
CPQ sourceStripe fieldNotes
product.nameprice_data.product_data.name
amounts.unit_priceprice_data.unit_amountGross price × 100 (cents)
billing_frequencyprice_data.recurringinterval + interval_count
amounts.discount_amountitems[M].discounts[0].couponCoupon duration = forever
Tax resolveddefault_tax_rates[]Manual mode only
One-off items (from product sections, added to phase 0):
CPQ sourceStripe fieldNotes
product.nameprice_data.product_data.name
amounts.unit_priceprice_data.unit_amountGross price × 100
amounts.discount_amountadd_invoice_items[M].discounts[0].couponCoupon duration = once
Global discountsphases[0].discounts[0].couponCoupon duration = once
Tax resolvedadd_invoice_items[M].tax_rates[]Manual mode only

​
Example — 2-phase subscription with setup fee

A Qwoty order with one setup fee and two 12-month recurring phases produces: 
Subscription Schedule
├── start_date: now
├── end_behavior: cancel
├── Phase 1 (12 iterations)
│   ├── add_invoice_items
│   │   └── "Setup Fee" — 1 400 € HT
│   └── items
│       └── "Licence Enterprise" — 490 €/month × 10 seats
│           └── coupon: qwoty_xxx_4900_eur_forever (-49 €/month)
└── Phase 2 (12 iterations)
    └── items
        └── "Licence Enterprise" — 590 €/month × 10 seats
All prices are sent as gross amounts (HT). Tax is applied by Stripe at invoice generation time, either automatically (Stripe Tax) or via the resolved tax rates.