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

# Understand Stripe conversions

> Learn how Stripe trials, purchases, renewals, and refunds appear in Biqli.

Biqli records a Stripe conversion only when it can connect the Stripe object to a valid click in the selected workspace. Installing the app does not import Stripe history, and Biqli does not assign old or unrelated account activity to a campaign.

## The complete customer journey

A typical journey appears in this order:

1. **Link clicked** — the visitor opens a conversion-enabled Biqli link.
2. **Signed up** — your application records a signup lead with a stable customer identity. This step is optional but recommended.
3. **Stripe Free Trial** — an attributed subscription enters Stripe's `trialing` state.
4. **Purchase** or **Purchased …** — a one-time payment or the first paid subscription invoice succeeds.
5. **Renewed …** — a later paid invoice has Stripe billing reason `subscription_cycle`.
6. **Partial refund** or **Refund completed** — Stripe reports a successful refund against an attributed sale.

The order visible in the activity feed follows each event's occurrence time. Stripe events can be delivered out of order, so a newer event can finish processing before an older event and still appear in the correct chronological position.

## Leads

Biqli can show two legitimate lead types for one customer:

* the signup lead your application records through a Biqli SDK or tracking API;
* the **Stripe Free Trial** lead recorded when an attributed Stripe subscription is trialing.

They represent different funnel steps. Starting a free trial does not replace the application signup lead.

A subscription that is not trialing does not create a free-trial lead. A trial created directly in Stripe without an attributable Checkout flow is ignored.

## One-time sales

A paid one-time Checkout Session creates one sale using Stripe's integer `amount_total` and currency. For example, `1200` in `usd` appears as `$12.00`.

Biqli does not record a sale when:

* Checkout is still unpaid;
* the customer abandons or cancels Checkout;
* an asynchronous payment fails;
* the registered attribution expired before payment;
* the Stripe account, environment, or click belongs to a different workspace;
* no safe attribution mapping exists.

The success URL is not proof of payment. Biqli waits for a verified Stripe event.

## Subscription sales and renewals

Subscription revenue is based on `invoice.paid`, not the browser return from Checkout.

* The first non-zero paid invoice creates a **Stripe Subscription Payment** sale.
* A later invoice with billing reason `subscription_cycle` appears as **Renewed …** when product details are available.
* Each Stripe invoice ID can create only one Biqli sale, even if Stripe retries the event.
* A zero-value trial invoice does not create a sale.
* The subscription mapping remains available for future recurring invoices after the short-lived Checkout mapping expires.

Changing or canceling a subscription does not create revenue by itself. A cancellation prevents future renewal sales once no further invoice is paid. Biqli currently does not add a separate cancellation item to customer activity.

## Refunds and net revenue

Successful Stripe refunds reduce attributed revenue for the original sale:

* a refund smaller than the remaining sale value appears as **Partial refund**;
* when successful refunds reach the full original value, activity shows **Refund completed**;
* failed or canceled refunds do not reduce revenue;
* retrying the same Stripe refund does not subtract it again;
* net attributed revenue never falls below zero for that sale.

The **Sales** count remains the number of successful sales. A refund changes net revenue; it does not erase the original sale or decrement the historical sales count.

Example:

| Activity                 | Sales | Net attributed revenue |
| :----------------------- | ----: | ---------------------: |
| `$12.00` purchase        |     1 |               `$12.00` |
| `$5.00` partial refund   |     1 |                `$7.00` |
| Remaining `$7.00` refund |     1 |                `$0.00` |

## Customer identity

When Stripe supplies a customer ID, Biqli uses an environment- and account-scoped external identity. Checkout customer name and email can enrich that customer record. Your signup implementation should use the same Stripe customer identity when it creates the application lead so both activities resolve to one customer.

The country, browser, operating system, referrer, and location shown in **First-touch details** describe the attributed Biqli click. They are not the Stripe card country or billing address. A customer table should use the same attributed-click country as the customer detail page.

If Stripe creates a trial event before its Checkout completion event, the customer may appear without name or email for a short period. After Checkout is processed, Biqli enriches the same customer. Stripe retries a temporarily pending trial event after the Checkout mapping becomes available.

## Gross sales, net revenue, and currency

Biqli stores the original sale amount and the successful refund adjustments separately. Reports can therefore retain the purchase and show its net contribution.

Each event keeps its Stripe currency and a normalized USD value used by cross-currency reporting. The activity feed formats the original event amount. Refund currency must match the original sale currency or Biqli rejects the refund as inconsistent.

## What Biqli does not do

The managed Stripe App does not:

* import payments or subscriptions that occurred before attribution was established;
* assign direct Stripe Dashboard sales to the latest website visitor;
* treat a success-page visit as a conversion;
* create a sale for an unpaid, failed, or zero-value invoice;
* mutate a Stripe customer, payment, subscription, invoice, or refund;
* silently merge Stripe environments.

For the implementation contract, read [Stripe attribution and identity](/developers/integrations/stripe/attribution).