Orb supports a seamless migration from Stripe Billing, whether you’re using flat-rate subscriptions, usage-based pricing, pricing on seats, or you’ve implemented custom billing logic. This guide walks through the migration process step by step. Orb is designed to minimize engineering lift during migration by supporting historical data backfills, real-time usage ingestion, and integrations with Stripe Payments for collections. Unlike other billing providers, Orb is fundamentally architected to support event backfills, which makes it easy to replay historical usage and ensure that your billing setup is accurate before migrating to Orb.

​
Overview

A typical Stripe Billing migration includes:
  1. Modeling your product catalog in Orb
  2. Importing customers and subscriptions
  3. Backfilling historical usage data
  4. Sending real-time usage events
  5. Configuring invoicing and collections
  6. Validating results and cutting over
Note: Orb can operate in parallel with your existing Stripe Billing implementation while you validate data and invoices.

​
Step 1: Define Pricing in Orb

Use the dashboard or API to define your product catalog in Orb. This includes:
  • Items and plans: Representing your sellable products and how you package them.
  • Prices and adjustments: Defining how customers are charged (e.g. flat fees, usage-based charges, discounts, minimums)
  • Plan configurations: Supporting logic such as adjustments over many prices, prepaid allocations, and invoicing settings such as your net terms.

​
Step 2: Import Customers and Subscriptions

Customers and their active subscriptions can be imported via the API or dashboard.
  • Use the POST /customers endpoint to create Orb customers. Set the external_id to the customer ID in your system.
  • Use the POST /subscriptions endpoint to define each customer’s active plan and billing cycle. We recommend using a historical start_date on the subscription to preserve contract timelines and usage aggregation.

​
Step 3: Backfill Historical Usage (Optional)

If you want Orb to generate accurate invoices or analytics based on prior usage data, you can backfill events. Ensure that your account is not set to issue invoices before backfilling data, as issued invoices will not be recalculated.
  1. Export historical usage from Stripe or your internal systems
  2. Format events using Orb’s ingestion schema
  3. Use the official backfill script to upload events
  4. Close the backfill, which will trigger invoice recomputation to reflect the backfilled usage.
Note: Backfills support full idempotency and delayed event ingestion, making it safe to replay usage as needed.

​
Step 4: Send Live Usage Events

Send real-time usage events to Orb using the ingestion endpoint. Orb’s event ingestion system supports:
  • Out-of-order events
  • Backdated timestamps
  • Custom properties for analytics and aggregation
  • High-throughput ingestion
You can continue using your existing Stripe Billing implementation while sending events to Orb in parallel for validation.

​
Step 5: Set Up Invoicing and Payments

Orb can handle invoice generation and optionally integrate with Stripe for payments. You can configure:
  • Invoice frequency and timing
  • Line item formatting and grouping
  • Webhooks for invoice creation and payment updates
  • Stripe Payments integration for collections
See: Invoices Overview

​
Step 6: Cut Over to Orb

Once all customer data, subscriptions, and usage events are validated:
  1. Stop creating subscriptions in Stripe Billing
  2. Transition to using Orb as the source of truth for metering and invoicing
  3. (Optional) Keep Stripe Payments as your payment processor
Orb customers often use Stripe for payments, while Orb takes over all aspects of metering, pricing, and billing logic.

​
Frequently Asked Questions

​
Can I run Stripe Billing and Orb in parallel?

Yes. Many customers send usage to both systems during testing to compare invoice output and validate pricing changes.

​
Will I lose access to my Stripe payment or tax setup? Will customers need to re-input their payment instruments?

No. Orb integrates directly with Stripe Payments — your customer records, tax configurations, and payment methods remain intact.

​
How long does migration take?

A typical migration takes 2 weeks, depending on the complexity of your pricing model and historical usage data.

​
What if I have discounts, credits, or prepaid balances?

Orb natively supports discounts, prepaid usage, minimums, and credit-based models. These can be configured via the dashboard or API.