Documentation
PricePilot User Guide
Everything you need to know about changing, scheduling, and bulk migrating subscription prices right inside your Stripe Dashboard — no code required.
Getting Started
PricePilot is a Stripe App — it lives entirely inside your Stripe Dashboard with no separate login, no external portal, and no data stored outside of Stripe.
Installing from the Stripe Marketplace
Visit the Stripe App Marketplace listing and click Install app. Stripe will ask you to authorize the permissions the app requires — these cover reading and updating subscriptions, prices, and products within your account. After authorization, PricePilot is immediately active. No API keys to copy, no webhooks to configure.
Subscription requirement
PricePilot requires an active paid subscription at $15/month. After installing, you'll be prompted to subscribe via Stripe Billing. The subscription is managed entirely within Stripe — cancel any time from your Stripe Dashboard under Apps > Installed apps.
Where PricePilot appears
Once installed, PricePilot adds a panel across five locations in your Stripe Dashboard. The left-side drawer shows three entries — Subscriptions, Customers, and Products — and clicking any of them navigates you to the right page.
Single Subscription Price Change
The most common workflow: update one customer's subscription to a different price, with a live preview of what they'll be charged before you confirm.
Navigate to Billing > Subscriptions and click into any active subscription. PricePilot's panel appears automatically on the right side of the page under the heading Change Price.
The panel shows the subscription's current price, the product name, and the next renewal date (or trial end date if the subscription is in trial). This is your reference point before making any changes.
The New price dropdown lists every active price on the same product. The subscription's current price is excluded — you can only move to a different one. Prices are shown with their amount, currency, and billing interval (e.g. $29.00/month, $290.00/year).
Two options appear once you select a new price:
- Immediately (with proration) — The price changes right now. Stripe calculates a prorated amount for the remainder of the current billing period and generates an invoice immediately.
- At next billing cycle — The price change is queued and takes effect on the subscription's next renewal date. No mid-cycle invoice is generated.
The Impact Preview panel shows a side-by-side FROM → TO comparison of the old and new prices. When Immediately is selected, it also shows the exact prorated invoice amount the customer will be charged. This is a live calculation from Stripe's upcoming invoice API — it reflects any existing discounts or credits on the subscription.
Click the confirm button. If applying immediately, the button reads "Apply price change now". If scheduling, it reads "Schedule for [date]" with the next billing date shown. Once confirmed, a success message appears and Stripe reflects the change immediately in the subscription record.
Scheduling for Next Billing Cycle
Scheduling a price change for the next billing cycle is the gentler option — no mid-period invoice, no surprise charges. The customer continues on their current price until renewal, then automatically moves to the new one.
What happens under the hood
When you schedule a price change for the next cycle, PricePilot uses a Stripe Subscription Schedule. Specifically, it creates a schedule with two phases:
- Phase 1 — current period through the next renewal date, at the existing price
- Phase 2 — from the renewal date onward, at the new price
Stripe handles the transition automatically at the renewal date. No manual follow-up required.
How to confirm a change is scheduled
After confirming, the success message in the panel will display the scheduled date (e.g. "Price change scheduled for May 1, 2025."). In the Stripe Dashboard, the subscription will also show a Schedule badge on its detail page, and you can inspect the subscription schedule directly to see both phases.
Canceling a scheduled change
If you need to undo a scheduled price change before it takes effect:
- Open the subscription in the Stripe Dashboard
- Find the Subscription schedule section (visible on the subscription detail page)
- Click Release schedule — this removes the schedule and leaves the subscription on its current price with no future change queued
Releasing a schedule via the Stripe Dashboard UI is safe and immediate. The subscription continues uninterrupted on its current price.
Bulk Price Migration
Migrate every subscriber on a given price to a new price in one operation. This is the right tool when you're rolling out a price change across your entire subscriber base or a large cohort.
The bulk migration view is available from Product Catalog (the "Products" drawer entry), from any individual product page, or from the Subscriptions list. PricePilot's panel appears on the right. The workflow walks you through four steps.
Choose the price you want to migrate away from. The dropdown lists all prices across all your products — including prices that are archived (more on this in the Archived Prices section). After selecting, PricePilot fetches all active subscriptions currently on that price and shows you a count.
Choose which product the new price belongs to (usually the same product, but cross-product migrations are supported), then choose the specific price within that product. This is a two-step selection to keep the price list manageable when you have many products.
The review screen shows:
- Total number of subscriptions that will be migrated
- Revenue impact — per-subscription MRR change and total MRR delta across all affected subscribers
- Migration notes flagging any subscriptions that may need attention (trialing, discounts, multi-item, or already-scheduled subscriptions)
You can expand the full subscriber list and exclude individual subscriptions by unchecking them. Excluded subscriptions are skipped — they stay on their current price.
Select Immediately (with proration) or At next billing cycle — same options as the single-subscription flow, but applied to every included subscriber simultaneously. Click Run migration to start. PricePilot processes subscriptions in small batches to stay within Stripe's API rate limits, showing a live progress count as it runs.
Interpreting the results
When the migration finishes, a results summary shows:
Create New Price & Migrate
The Create & Migrate workflow is the right tool when you're launching an entirely new price — not just moving subscribers between existing prices. It handles the full rollout in one guided flow: define the new price, optionally archive the old one, set it as your product default, and migrate all existing subscribers.
Access this from Product Catalog or any individual product page. At the top of PricePilot's panel, click the Create new & migrate button to switch modes. If you're already on a product's page, the source price selector is automatically pre-filtered to that product's prices.
Pick the existing price all your current subscribers are on. PricePilot fetches the subscriber count automatically. This is the price that will be migrated away from (and optionally archived).
Configure the new price that will be created in Stripe:
- Price type — Flat rate (a single amount per billing interval) or Tiered (graduated or volume tiers — see the Tiered Pricing section)
- Amount — The unit price in the same currency as the source price
- Billing interval — Day, week, month, or year; with an optional interval count (e.g. every 3 months)
- Nickname (optional) — A label visible in Stripe but not shown to customers
Two checkboxes control what happens after the new price is created:
- Set as product default price — Updates the product's default price in Stripe to the newly created one. New customers who subscribe to this product will be on the new price automatically. Checked by default.
- Archive old price — Marks the source price as archived in Stripe, preventing any new subscriptions from being created on it. Existing subscribers are not affected by archiving — only new subscription creation is blocked. Checked by default.
Select Immediately or At next billing cycle, then click Create price & migrate. PricePilot will: (1) create the new price in Stripe, (2) optionally set it as default and archive the old one, then (3) migrate all subscribers from the source price to the new price using the same batched approach as bulk migration.
Tiered Pricing
PricePilot supports creating tiered prices — not just flat rates — as part of the Create & Migrate flow. This lets you define quantity breakpoints where the per-unit price changes depending on how many units a customer uses.
Graduated vs. Volume pricing
Stripe supports two tiered billing models. When you select Tiered as the price type in PricePilot, you choose which model to use:
- Graduated (recommended for most use cases) — Each unit is charged at the rate for the tier it falls in. Units 1–5 are charged at the first tier's rate, units 6–10 at the second rate, and so on. The total bill is a sum across tiers.
- Volume — All units are charged at the rate of the tier the total quantity reaches. If a customer uses 7 units and tier 2 covers 6+, all 7 units are charged at tier 2's rate.
Setting up tiers in PricePilot
When tiered pricing is selected, you define rows where each row represents one tier:
- Up to — The maximum number of units this tier covers. Leave blank for the last tier to make it open-ended (i.e. infinity).
- Per unit price — The amount charged per unit in this tier, in your account's currency.
You can add or remove tier rows using the Add tier and Remove controls. The last row must always have a blank Up to — that's your final catch-all tier.
Example: Two-tier graduated pricing
A SaaS company charges $10/unit for the first 5 seats, then $7/unit for every seat beyond that.
With graduated pricing, a customer using 8 seats would pay:
- 5 × $10 = $50 (Tier 1)
- 3 × $7 = $21 (Tier 2)
- Total: $71/month
Migrating from Archived Prices
Stripe allows prices to be archived, which prevents new subscriptions from being created on them — but existing subscribers remain on the archived price indefinitely. PricePilot is designed to handle this scenario.
Why archived prices appear as source options
When you select a source price in the Bulk Migration or Create & Migrate flow, PricePilot queries all active subscriptions across your account and determines which prices they're currently on — regardless of whether those prices are archived. If you have active subscribers on an archived price, that price will appear in the source price dropdown.
This is intentional. Archived prices are often the ones you most need to migrate away from. You may have archived a legacy price after introducing a new one, but some subscribers were grandfathered on the old rate.
The typical workflow
If you've already archived a legacy price but still have subscribers on it:
- Go to Product Catalog (or open the specific product) and open PricePilot's bulk view
- In the source price dropdown, select the archived price — it will appear with its name and amount
- Proceed through the normal bulk migration flow to move those subscribers to an active price
Once all subscribers have been migrated off the archived price, no subscriptions will remain on it.
FAQ
Answers to common questions about how PricePilot handles specific situations.
Will my customers be notified of price changes?
PricePilot itself does not send any emails or notifications to your customers. Whether Stripe sends a notification depends on your Stripe account settings and the type of change.
For immediate changes with proration, Stripe generates an invoice immediately — if you have customer email receipts enabled in your Stripe settings, your customer will receive the invoice by email. For scheduled changes (next billing cycle), no notification is sent by Stripe until the invoice is actually generated at the renewal date.
If you want to proactively notify customers of a price change, send that communication through your own email platform before running the migration. This is generally best practice for any price increase.
What happens to customers mid-billing-cycle when I apply immediately?
When you apply a price change immediately, Stripe calculates a prorated amount for the remainder of the current billing period. The proration works as follows:
Stripe credits the customer for the unused portion of the old price, then charges them for the corresponding portion of the new price. The net amount is what appears on the prorated invoice. If the new price is higher, this results in an immediate charge. If the new price is lower, the credit may reduce the next invoice to zero or even result in a credit balance.
The exact prorated amount is always shown in the Impact Preview panel before you confirm, so you can verify it looks correct. Stripe's proration algorithm accounts for any existing credits or discounts on the subscription.
Can I roll back a price change?
For scheduled changes (next billing cycle) that haven't yet taken effect: yes. Release the subscription schedule from the Stripe Dashboard and the queued change is cancelled. The subscription stays on its current price.
For immediate changes that have already been applied: there's no automatic rollback. You would need to run another price change — either through PricePilot's single-subscription flow or another bulk migration — to move subscribers back to the previous price. If an incorrect prorated invoice has already been generated, you can void or credit it from the Stripe Dashboard's invoices section.
Does this work with metered / usage-based billing?
Partially. PricePilot can migrate subscribers who are currently on metered prices to a new price — both single-subscription and bulk flows support this. What it cannot do is show a proration preview for metered subscriptions, because Stripe's upcoming invoice API doesn't support previewing metered billing subscriptions in all configurations.
PricePilot also cannot create new metered prices. The Create & Migrate flow creates licensed (quantity-based) flat-rate or tiered prices. If you need to migrate to a new metered price, create the destination price directly in your Stripe Dashboard first, then use PricePilot's standard Bulk Migration flow with that price as the target.
When a metered source price is selected in a bulk migration, PricePilot will show a note in the review screen advising that existing usage will be billed at the old rate before the new price takes effect.
Is my customer data stored anywhere outside Stripe?
No. PricePilot operates entirely within the Stripe App iframe — it has no external backend server, no database, and no external API calls. All data (subscriptions, prices, customer records) is fetched directly from Stripe's API using your account's credentials within the Stripe App sandbox. Nothing leaves Stripe.
This is by design. The Stripe App platform gives PricePilot scoped, read/write access to your account's data, but that data never transits through any servers we operate.
What if a bulk migration partially fails?
PricePilot processes each subscription independently. A failure on one subscription does not stop the migration — PricePilot continues through the remaining subscriptions and reports the final counts of successes and failures at the end.
Failed subscriptions are listed by ID in the results screen. Common causes of individual failures include: the subscription is paused or in an incompatible state, the target price uses a different currency than the subscription, or a Stripe API rate limit was hit. You can click through to those subscriptions in the Stripe Dashboard to investigate, then update them individually using PricePilot's single-subscription flow or directly via the Stripe Dashboard.
Successfully migrated subscriptions are not rolled back if other subscriptions in the same run fail — there is no all-or-nothing transaction. If you need to roll back a batch, use the bulk migration flow to move all affected subscribers back to the original price.