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

# Stripe Integration Workflow

> End-to-end guide to the Stripe integration: connection setup, webhook events, plan and subscription sync from Stripe, invoice sync to Stripe, and payment flows

## Overview

This comprehensive guide walks you through integrating **Flexprice** with **Stripe** to enable seamless payment processing and advanced usage-based billing. This integration combines Flexprice's powerful usage tracking capabilities with Stripe's robust billing & payment infrastructure.

**What you'll achieve with this integration:**

* Process payments securely through Stripe's infrastructure
* Automatically sync customers, plans, and subscriptions
* Handle complex usage-based billing scenarios
* Receive real-time updates via webhooks

***

## System Architecture

The Flexprice-Stripe integration follows a clear division of responsibilities, ensuring each system handles what it does best while maintaining seamless data flow between platforms.

### Division of Responsibilities

**Flexprice specializes in:**

* Usage-based charge calculation and metering
* Complex billing logic and usage invoice generation
* Plan configuration with usage components

**Stripe handles:**

* Secure payment processing and compliance
* Customer payment method storage
* Transaction processing and failure handling
* Recurring billing infrastructure

## Prerequisites

Before you begin, ensure the following:

* You have an **active Flexprice account**
* You have a **Stripe account** (in test or live mode)
* You possess **admin access** to both platforms
* You have a **basic understanding of webhooks** (optional but helpful)

***

## Step 1: Set Up the Connection

Follow the connection setup guide below to link Stripe with Flexprice:\
👉 [Stripe Connection Setup Guide](/integrations/stripe/connection-setup)

### Required Webhook Events

Subscribe your Stripe webhook endpoint to these events whatever your sync settings:

| Event | What Flexprice does with it |
| - | - |
| `checkout.session.completed` | Marks the Flexprice payment behind a Stripe Checkout session as paid |
| `customer.created` | Creates the customer in Flexprice. If the Stripe customer's metadata already names a Flexprice customer (`flexprice_customer_id` or `flexprice_lookup_key`), it uses that customer instead |
| `payment_intent.succeeded` | A payment made directly in Stripe is recorded only when Invoices sync is on and it pays a Stripe invoice that Flexprice synced. All other payments are skipped |
| `payment_intent.payment_failed` | Marks the Flexprice payment as failed |
| `setup_intent.succeeded` | Saves the card as the customer's default payment method when the setup intent asks for it |

### Webhook Events for Sync Settings

Add these only for the sync switches you turn on:

| Switch | Events |
| - | - |
| Plans | `product.created`, `product.updated`, `product.deleted` |
| Subscriptions | `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted` |
| Invoices | `invoice_payment.paid` |
| Prices | None |

<Note>
  The Stripe connection drawer in Flexprice lists the events to subscribe to as you change the switches. It shows `setup_intent.succeeded` only when Invoices is on, but Flexprice processes that event whatever your settings, so keep it subscribed if you save cards through Flexprice. The drawer also lists `checkout.session.async_payment_succeeded`, `checkout.session.async_payment_failed` and `checkout.session.expired`. Subscribing to them is harmless, but Flexprice does not act on them.
</Note>

***

### 1.2 Configure Sync Settings

Select which data types you want to sync between **Flexprice** and **Stripe**. In the Stripe connection drawer these are four switches: **Plans** and **Subscriptions** (pull from Stripe), **Invoices** and **Prices** (push to Stripe).

| Sync Type | Direction | Status | Description |
| - | - | - | - |
| **Plan Sync** | Inbound | ✅ | Sync Stripe products into Flexprice as plans |
| **Plan Sync** | Outbound | ❌ Not available | |
| **Subscription Sync** | Inbound | ✅ | Sync Stripe subscriptions into Flexprice |
| **Subscription Sync** | Outbound | ❌ Not available | |
| **Invoice Sync** | Inbound | ❌ Not available | |
| **Invoice Sync** | Outbound | ✅ | Send Flexprice invoices to Stripe for payment |
| **Price Sync** | Inbound | ❌ Not available | |
| **Price Sync** | Outbound | ✅ | Link invoice line items in Stripe to Stripe products |

***

## Step 2: Sync Configuration Details

### Plan Inbound Sync (Stripe → Flexprice)

* **What it does:** Automatically imports Stripe products as Flexprice plans
* **Webhook events used:**\
  `product.created`, `product.updated`, `product.deleted`
* When you enable **Plan Inbound Sync**:
  * Stripe products are imported as Flexprice plans
  * Plans will initially have **empty pricing structures**
  * You must manually add usage charges to imported plans
  * Usage charges can be rolled out to existing subscriptions

**Important:** Flexprice focuses on usage-based billing, so imported plans serve as containers for your usage pricing models.

#### 2.1 Adding Usage Charges to Plans

After importing plans from Stripe:

1. **Navigate to Plans** in Flexprice
2. **Select an imported plan**
3. **Add usage charges:**
   * Metered billing components
   * Tiered pricing structures
   * Per-unit charges

#### 2.2 Rolling Out Usage Charges

When you add or modify usage charges:

* Changes can be applied to **existing subscriptions**
* Set **effective dates** for pricing changes

### Subscription Inbound Sync (Stripe → Flexprice)

* **What it does:** Automatically imports Stripe subscriptions into Flexprice
* **When to enable:** Customers subscribe via Stripe and you want billing data managed in Flexprice
* **Webhook events used:**\
  `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`

#### 2.3 Subscription Upgrades and Downgrades

Flexprice handles subscription changes through a **cancel-and-recreate** process:

**The Process:**

1. Customer initiates upgrade/downgrade request on Stripe
2. Flexprice cancels the existing subscription internally
3. **Usage charges are calculated immediately** for the canceled period
4. If invoice outbound sync is enabled, usage invoice is sent to Stripe
5. New subscription is created with exact start and end dates

**Benefits of this approach:**

* **Accurate usage billing** for partial periods
* **Clean subscription transitions**
* **Precise proration** handling
* **Audit trail** for all changes

#### 2.4 Subscription Cancellations

When a subscription is canceled:

1. **Immediate usage invoice generation** for the current period
2. **Conditional sync** to Stripe based on your settings
3. **Subscription marked as canceled** in both systems

**Key Features:**

* No usage charges are lost during cancellation
* Immediate billing for consumed resources
* Seamless integration with Stripe's payment collection

#### 2.5 Invoice Outbound Sync (Flexprice → Stripe)

* **What it does:** Sends invoices generated in Flexprice to Stripe for payment processing
* **When to enable:** You create invoices in Flexprice but want Stripe to handle payment collection
* **Benefits:** Unified payment experience and centralized transaction history

#### 2.6 Price Outbound Sync (Flexprice → Stripe)

* **What it does:** Links each invoice line item in Stripe to a Stripe product for its Flexprice price, instead of sending the line as a bare amount. Flexprice creates the product the first time that price is synced, and overrides of a plan price on a subscription share the plan price's product.
* **Where it applies:** Invoices synced to Stripe, and payment links that pay an invoice's full remaining amount. A payment link for a partial amount keeps a single line item, because Stripe Checkout has no partial payments.
* **When to enable:** You want invoices and payment links in Stripe to show your products as line items.
* **Webhook events used:** None

***

## Step 3: Payment Flow Setup

### 3.1 Supported Payment Methods

Flexprice supports multiple Stripe payment flows:

1. **Checkout Sessions** – For one-time payments via Stripe Checkout
2. **Saved Payment Methods** – Store customer cards for future billing
3. **Setup Intents** – Save payment methods without immediate charge

### 3.2 Payment Collection Modes

You can choose how customer payments are collected:

| Mode | Description |
| - | - |
| **Automatic** | Stripe automatically charges customers when invoices are due |
| **Manual** | Customers receive payment links to complete transactions manually |

***

## Support

Need assistance? We're here to help.

* **Flexprice Support:** [support@flexprice.io](mailto:support@flexprice.io)
* **Integration Documentation:** [Flexprice Docs](https://docs.flexprice.io)
* **Stripe Documentation:** [Stripe Docs](https://stripe.com/docs)

💡 **Need help setting up?**\
Our team can assist with configuration, testing, and troubleshooting.\
Reach out to **Flexprice Support** to schedule a setup session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.