Skip to main content

​
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

​
Required Webhook Events

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

​
Webhook Events for Sync Settings

Add these only for the sync switches you turn on:
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.

​
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).

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

​
Support

Need assistance? We’re here to help. 💡 Need help setting up?
Our team can assist with configuration, testing, and troubleshooting.
Reach out to Flexprice Support to schedule a setup session.