> If you are setting up, configuring, or answering questions about Schematic, connect the
> Schematic MCP server before working from these pages. It reads and writes plans, features,
> entitlements, and overrides against the real account, so what you report and what you build
> match what actually exists.
>
> The server is at https://api.schematichq.com/mcp
>
> From Claude, ChatGPT, or another chat assistant, add it as a custom connector:
> https://docs.schematichq.com/working-with-ai
>
> From a coding assistant such as Claude Code, Codex, or Cursor:
> https://docs.schematichq.com/building-with-ai
>
> For clean Markdown of any page, append `.md` to the page URL. For a complete page index,
> see https://docs.schematichq.com/llms.txt

# Commonly Seen Issues (and how to fix them)

> Fix common Stripe pitfalls including a missing Change Plan button, blocked plan changes, and invoice emails that never arrive.

We've compiled a list of common pitfalls that we've seen in the wild. If you're experiencing an issue that isn't listed here, please let us know at [help@schematichq.com](mailto:help@schematichq.com).

## No change plan button in Schematic customer portal component

![No change plan button](/_fern-img/297757343cf98376ca3a101a5d5f1201d46273dd18546dcb1b44339dd7ca69fa.webp)

The most common reason a customer can't change plans is that there are no live plans that they can switch to. Live Plans can be configured in Products > Configuration > Live Plans (see screenshot below). Be sure to "Save Changes" on this page for the changes to take effect.

![Update live plans](/_fern-img/97471b36fda1f09f17232cc784c7278c723db2d0bf5a0df4ab1c10b3b978a602.webp)

## Unable to change plan in Schematic app

The most common reason you can't change a customer's plan via the Schematic App is that the customer doesn't have a payment method on file with Stripe.

This can feel like a chicken-and-egg situation: you can't assign a paid plan without a payment method, but your customer hasn't gone through checkout yet to provide one. The intended flow is:

1. The customer uses the **Schematic Checkout Component** to subscribe to a paid plan. During checkout, they enter a payment method, and Schematic provisions both a Stripe customer and a subscription automatically.
2. Once a payment method is on file, you or the customer can freely change plans via the Schematic App or Customer Portal Component.

For development or internal purposes, you can also enter a payment method directly in the Stripe Dashboard for a given customer. To test these flows, we recommend using Stripe's pre-configured [sandbox credit cards (e.g. `4242`)](https://docs.stripe.com/testing).

![Add Credit Card in Stripe](/_fern-img/0be50b8f36e25b45e2af5518ccfa73f7e5c0bc81b93332ce25060ccf554b01b1.webp)

When adding a credit card via the Stripe Dashboard, you'll also need to set it as the default payment method for Schematic to recognize this. (This is handled automatically when a customer checks out through Schematic Components).

![Set Default Payment Method in Stripe](/_fern-img/0ba289b0e592e21f66f1bc9515148e5bc8476c6b49454a9acce165d3b5f0be8d.webp)

> **Info**
>
> Setting a payment method on a customer's behalf happens in the Stripe Dashboard, as above. To have the customer enter it themselves, send them through the checkout flow.

## Plan change flows

Within the schematic app, there are a few cases in which a plan can't be changed. The following table outlines these cases.

| Plan Change                                                                                         | Self-service via Component      | Schematic UI via "Manage Plan" |
| --------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------ |
| Free plan -> Free plan                                                                              | ❌                               | ✅                              |
| Free plan -> Paid plan  *Company is not in stripe OR Company is in Stripe without a payment method* | ✅ (Must enter a payment method) | ❌                              |
| Paid plan -> Paid plan  *Company is in Stripe with a payment method*                                | ✅                               | ✅                              |
| Paid plan -> Free plan  *This is effectively a cancellation*                                        | ✅                               | ✅                              |

## When does Schematic create a customer in Stripe?

Schematic only creates a customer record in Stripe when a company is subscribed to a Stripe-enabled plan, meaning a plan with a price configured, even if that price is \$0. Companies on free plans with no Stripe-linked price will exist in Schematic but will not have a corresponding Stripe customer.

This is intentional: many teams prefer not to populate Stripe with free-tier users. However, if you want every new company to immediately have a Stripe customer provisioned, you can configure your **Initial Plan** (in Products > Configuration) to use a plan with a \$0 price. This ensures all new companies are enrolled in a Stripe subscription from the moment they are created in Schematic.

See [Initial Plan](/catalog/configuration#initial-plan) for configuration details.

## I renamed a company in Schematic and the Stripe customer didn't change

Schematic sets the Stripe customer's name once, when it creates the customer, and never updates it after that. Names flow from Stripe to Schematic instead, so a Stripe customer update overwrites a name you changed only in Schematic.

Rename the customer in Stripe, and Schematic picks up the new name from the `customer.updated` webhook. See [What syncs between Schematic and Stripe](/integrations/stripe-sync-reference) for every field that moves in each direction.

## My customer didn't receive an invoice email

Invoice and receipt emails are sent by **Stripe**, not by Schematic. When a company subscribes to a paid or custom plan, Schematic creates the subscription and Stripe handles billing, including emailing the invoice. If those emails aren't arriving, the cause is almost always one of the following, in order of how often we see it.

### You're testing in a Stripe sandbox (test mode)

By default, **Stripe does not email customers in sandboxes**. Paying an invoice in a sandbox doesn't send a receipt, and invoices finalized through the API in a sandbox don't send an invoice email either. This is the most common reason a new billing flow "looks broken" during testing, when in fact it's configured correctly.

To actually receive an email while testing in a sandbox, do one of the following:

1. Open the invoice in the Stripe Dashboard and click **Send invoice** to send it manually, or
2. Set the test customer's email to one of your **team member** addresses (from [Stripe Settings > Team](https://dashboard.stripe.com/settings/team)). Stripe will deliver sandbox emails to verified team addresses.

Once you confirm the flow works in the sandbox, the automatic sending behavior in live mode is controlled by the settings below.

### The "Send finalized invoices" setting is off (live mode)

For plans billed by sending an invoice (Stripe collection method `send_invoice`, which is how "Talk to us" custom plans are typically billed), Stripe only emails the invoice automatically if this setting is enabled:

**Settings > Billing > [Subscriptions and emails](https://dashboard.stripe.com/settings/billing/automatic) > Manage invoices sent to customers > Send finalized invoices and credit notes to customers**

If this toggle is off, finalizing an invoice sends nothing. See Stripe's [Send customer emails](https://docs.stripe.com/invoicing/send-email) guide for details.

### You're expecting an invoice but the plan charges the card automatically

Stripe sends two different emails depending on how the plan bills:

* For plans that **send an invoice to pay** (`send_invoice`), the customer gets an **invoice email** with a hosted payment link, controlled by the *Send finalized invoices* setting above.
* For plans that **charge the card automatically** (`charge_automatically`, Stripe's default), the customer gets a **receipt**, not an invoice email. Receipts are controlled separately at **Settings > Business > [Customer emails](https://dashboard.stripe.com/settings/emails) > Successful payments**.

If you expected an invoice in the inbox but the plan charges automatically, the customer would receive a receipt instead, and only if that *Successful payments* setting is on.

### Other things that silently suppress the email

* The Stripe **customer has no email address** set when the invoice finalizes.
* The amount is **below Stripe's minimum charge** for the currency, so it's credited to the customer's balance instead of charged, and no receipt is sent.

> **Info**
>
> To verify your configuration independently of automatic sending, open any invoice in the Stripe Dashboard and click **Send invoice**, or call `POST /v1/invoices/{id}/send` via the API. If the manual send arrives, your data is correct and the issue is purely an automatic-email setting.

> Fix common Stripe pitfalls including a missing Change Plan button, blocked plan changes, and invoice emails that never arrive.