Match Stripe billing to Shopify Merchants

Fusionmetrics can combine Shopify billing with Stripe billing for the same app. To do that safely, each Stripe Customer must identify the Shopify Merchant that owns the subscription.

Use the permanent myshopify.com domain as the identity. Custom storefront domains can change and are not accepted for matching.

Add myshopify_domain to Stripe Customers

Set this metadata on every Stripe Customer that represents a Shopify Merchant:

Key:   myshopify_domain
Value: merchant-shop.myshopify.com

The value must contain one valid .myshopify.com domain. Fusionmetrics normalizes capitalization and a pasted URL, but storing the bare lowercase domain is the clearest convention.

Add metadata in the Stripe Dashboard

1. Open Customers in Stripe and select the Customer.
2. Find Metadata, then select Edit.
3. Add the key myshopify_domain.
4. Enter the Merchant's permanent domain, such as merchant-shop.myshopify.com.
5. Save the Customer.

Never copy production Merchant details or credentials into documentation screenshots or source control.

Add metadata through the Stripe API

Create a Customer with the Shopify identity:

curl https://api.stripe.com/v1/customers \
  -u "$STRIPE_SECRET_KEY:" \
  -d "metadata[myshopify_domain]=merchant-shop.myshopify.com"

Update an existing Customer:

curl https://api.stripe.com/v1/customers/cus_demo123 \
  -u "$STRIPE_SECRET_KEY:" \
  -d "metadata[myshopify_domain]=merchant-shop.myshopify.com"

Create a restricted Stripe key

Create a restricted API key in Stripe for Fusionmetrics. Grant only the access needed to read billing data.

Stripe resource	Permission	Why Fusionmetrics uses it
Customers	Read, required	Resolve myshopify_domain and Customer details
Charges	Read, required	Import charge-based billing activity
Invoices	Read, required	Reconstruct invoice-backed recurring revenue
Subscriptions	Read, required	Reconstruct active Stripe subscriptions
Account	None required	Fusionmetrics does not require Account read permission

Customers, Charges, Invoices, and Subscriptions are all required for new Fusionmetrics connections. Fusionmetrics validates each permission before saving the key, so do not omit a permission because a Stripe resource is currently empty.

Existing legacy connections that only expose Customers and Charges can still use the limited Charges compatibility import. Update those restricted keys with Invoices and Subscriptions read access before reconnecting or replacing them.

How Merchant matching works

Fusionmetrics applies deterministic precedence:

1. If metadata.myshopify_domain exists, it is the authoritative value.
2. If that key is absent, Fusionmetrics examines legacy metadata values and accepts them only when exactly one valid .myshopify.com domain is present.
3. Invalid values, multiple different domains, or no domain remain unmatched.

An invalid myshopify_domain does not fall back to another metadata field. Correct the authoritative value in Stripe instead. This avoids silently assigning revenue to the wrong Merchant.

Connect Stripe and run the first synchronization

1. In Fusionmetrics, open the app's Settings page.
2. Under Data sources, enter a label and the restricted Stripe key.
3. Select Connect Stripe.
4. Fusionmetrics validates the key immediately against Stripe and checks the required Customers, Charges, Invoices, and Subscriptions access.
5. Start or refresh the app import to synchronize Stripe billing history and prepared dashboard data.

The connection reports permission failures before an import begins. A successful key validation does not guarantee that every Stripe Customer can be matched; matching depends on Customer metadata.

Fusionmetrics currently imports Stripe billing in USD only. Do not treat non-USD Stripe amounts as converted revenue.

Backfill existing Stripe Customers

Before the first full synchronization:

• Export or enumerate the Stripe Customers that belong to the Shopify app.
• Resolve each Customer to exactly one permanent .myshopify.com domain from your app's own records.
• Update metadata.myshopify_domain through the Stripe API or Dashboard.
• Review duplicates and shared Stripe Customers before assigning a domain.
• Re-run the Fusionmetrics import after the backfill.
• Review unmatched Merchants and correct the source metadata instead of editing prepared dashboard data.

Make the metadata write part of the app's Stripe Customer create/update flow so new Merchants do not need another backfill.

Select a billing provider in the dashboard

After Stripe data has been synchronized, use the billing-provider control to compare:

• Any for Shopify and Stripe billing combined.
• Shopify for Shopify Partner billing only.
• Stripe for matched Stripe billing only.

If Any and Shopify are identical, confirm that the Stripe import completed, Stripe revenue falls inside the selected date range, and Customers matched a Merchant.

Troubleshoot unmatched Merchants

Check these conditions in order:

1. The Stripe Customer has myshopify_domain, spelled exactly.
2. The value ends in .myshopify.com and identifies the permanent Shopify shop.
3. The value contains only one shop domain.
4. The restricted key can read Customers, Charges, Invoices, and Subscriptions.
5. The import ran after the metadata was added.
6. Stripe billing is in USD.

When a legacy metadata match is ambiguous, add the preferred key rather than deleting useful metadata. Fusionmetrics will use myshopify_domain on the next synchronization.