Commonly Seen Issues (and how to fix them)

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.

No Change Plan Button in Schematic Customer Portal Component

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

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.

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 — that is, a plan with a price configured (even if the 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 Catalog > 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 for configuration details.

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

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