Skip to navigation
IntegrateStripe

What Syncs Between Schematic and Stripe

Schematic and Stripe each own different parts of a customer’s record, and the sync moves most fields in only one direction. If you edit a field on the side that doesn’t own it, the edit either never reaches the other system or gets overwritten the next time that record changes. Check this page before you clean up customer data in bulk.

Company names

Schematic writes the Stripe customer’s name once, when it creates the customer, and never writes it again. Renaming a company in Schematic leaves the Stripe customer’s name, and the name on its invoices, as it was.

Name changes do flow the other way. Whenever a Stripe customer changes, Schematic copies the Stripe customer’s name onto the matching company, unless the Stripe name is blank. A name you change only in Schematic is overwritten the next time anything on that Stripe customer changes, such as an address change or a new default payment method.

To rename a company that has a Stripe customer, rename the customer in Stripe. The customer.updated webhook carries the new name into Schematic.

Schematic to Stripe

Stripe objectWhat Schematic writesWhen
CustomerName, email, and schematic_company_id metadata. The email comes from the company key named email, if the company has one.The first time the company needs a Stripe customer. See when Stripe customers are created.
CustomerDefault payment methodWhen a customer adds a payment method in checkout, and when a Stripe customer has exactly one payment method attached and no default
CustomerBilling email, phone, address, and tax IDsWhen a customer enters billing details in checkout
CustomerEmailWhen Schematic starts a subscription billed by sending an invoice
CustomerMetadataWhen a customer submits checkout with custom fields that store their values in Stripe
ProductPlan or add-on name, and controlled_by: schematichq metadataWhen you create a plan or add-on and choose to create a new Stripe product. After that, Schematic only archives the product, so renaming a plan leaves the Stripe product name as it was.
PriceAmount, interval, and metadata including controlled_by: schematichq and the plan versionWhen you publish a plan version with new pricing. Schematic deactivates the prices when the version is archived. See plan versions.
Billing meterA meter for the feature’s eventWhen you add a usage-based price to a feature and Stripe has no meter for its event yet
SubscriptionItems, quantities, schedules, and cancellationsWhen a plan changes through checkout, the customer portal, Manage Plan, the API, or a plan version migration
Meter eventUsage quantity for the company’s Stripe customerOn each event for a feature mapped to a metered price. Events sent in backfill mode are not reported.
InvoiceLine items for the purchaseWhen a customer buys a credit bundle, when you finalize a custom plan, and when Schematic bills an amount it calculates outside the subscription, such as overage
Subscription cancellationCancels the company’s subscriptionWhen you delete a company with “Cancel Stripe subscription upon deletion” on, or with cancel_subscription: true in the API. See deleting companies.

Subscription metadata

Every subscription Schematic creates carries metadata that ties it back to Schematic. Reconciliation and reporting logic built on Stripe data can read these keys instead of looking the company up by Stripe customer.

Metadata keyValue
schematic_company_idThe company the subscription is for
schematic_plan_idThe plan the subscription is for
schematic_plan_version_idThe version of that plan
schematic_billing_entity_idThe company paying for the subscription, present only when a billing entity pays

When a billing entity pays, the subscription sits on the billing entity’s Stripe customer rather than the subscribing company’s, so resolve the subscribing company from schematic_company_id. See billing entities for an example.

Stripe to Schematic

Schematic listens to Stripe webhooks and applies each change as it arrives. The Refresh data button on the Stripe integration page re-imports products and customers if you need to resync by hand.

Stripe objectEventsWhat Schematic does
Customercustomer.created, customer.updatedCreates or updates the company whose stripe_customer_id key matches, and sets the company name from the Stripe name when it isn’t blank. See company mapping.
Customercustomer.deletedDeletes Schematic’s copy of the Stripe customer. The company stays in Schematic.
Subscriptioncustomer.subscription.created, .updated, .deleted, .paused, .resumed, .trial_will_end, .pending_update_applied, .pending_update_expiredUpdates the company’s subscription, plan, and entitlements. See subscription statuses for how each status affects access.
Subscription schedulesubscription_schedule.created, .updated, .released, .canceled, .completed, .aborted, .expiringUpdates the company’s scheduled plan changes
Product and priceproduct.created, .updated, .deleted, price.created, .updated, .deletedImports the product or price so you can map it to a plan, add-on, or feature
Billing meterbilling.meter.created, .updatedImports the meter so you can map it to a usage-based feature
Invoiceinvoice.created, .updated, .paid, .voided, .marked_uncollectible, .deletedUpdates the invoices shown in the customer portal. A paid invoice activates a custom plan set to activate on payment.
Payment methodpayment_method.attached, .updated, .automatically_updated, .detachedUpdates the payment methods shown in checkout and the customer portal
Coupon and promotion codecoupon.created, .updated, .deleted, promotion_code.created, .updatedImports the discount so customers can enter it in checkout and you can apply it through the API

Schematic reads coupons and promotion codes from Stripe and never creates them, so create them in Stripe and they become available in Schematic. See pre-filling a promotion code for applying one in checkout.

Data that stays in Schematic

Schematic keeps the following data to itself, so reports and automations built on Stripe data don’t see any of it:

  • Company keys, other than the email key Schematic reads once when it creates the Stripe customer
  • Company and user traits
  • Users
  • Features, flags, and entitlements
  • Overrides
  • Credit balances and grants. The purchase of a credit bundle is invoiced in Stripe, but the balance lives in Schematic.

Use webhooks to send changes to this data to your own systems.