Configure for accuracy

Notice some numbers don’t quite match what you expected? Or maybe certain data seems to be missing? Don’t worry – this happens for a few common reasons. Sometimes you’re seeing your true numbers for the first time, or your plan structure is unique (like using usage charges or “free” plans).

Most often though, it’s because the Shopify Partner API needs a little help with key areas: missing customer data, plan cadence, trials, and discounts. Getting these right is essential since metrics like MRR depend on knowing who your customers are, what plans they’re on, and their subscription details. Let’s get everything dialed in perfectly.

Missing customer data

When you first connect Mantle to your Shopify Partner account, you’ll get tons of data automatically – but not everything. The Partner API has some blind spots that can affect your reporting accuracy and limit segmentation options.

What’s typically missing:

• Shopify plan (Basic, Shopify, Advanced, Plus)
• Email addresses (shop email and customer support email)
• Shop details (timezone, currency, billing address)
• Contact information (team member details)
• Geographic data (country, address for localization)

How to fill in the gaps:

There are three ways to get this missing data:

1. Use access tokens (recommended): Let Mantle do the heavy lifting by passing your shops’ Shopify access tokens through the /identify endpoint. This lets us use the Shopify Admin API to automatically pull in all the missing details.

2. Provide data manually via API: If you already have this information in your system, you can pass it directly through the /identify endpoint without an access token.

3. Manual entry in Mantle: For quick fixes or smaller customer bases, you can:

   • Go to individual customer profiles and edit their details directly
   • Import a CSV file with customer data

For step-by-step instructions on the API approaches, check out our guide on identifying customers. For CSV imports, visit our customer import guide.

What exactly does the access token get you?

When you provide an access token, Mantle automatically pulls:

Shop Information:

• Shopify plan (Basic, Shopify, Advanced, Plus)
• Primary shop email and customer support email
• Shop name, description, and public URL
• Timezone and default currency
• Full billing address and country

Subscription Details:

• Active subscription status and trial information
• Discount amounts, percentages, and duration
• Usage limits and current usage for usage-based billing
• Subscription intervals and pricing

Additional Context:

• Access scopes (what permissions your app has)
• Whether it’s a development store
• Shopify Plus status

For the simplest solution, we recommend setting up a daily cron job that identifies all your customers to Mantle. This keeps your data fresh as merchants upgrade plans or change details.

Customer contacts and emails

Want to collect contact information for individual team members at each merchant’s store? This is super useful for email marketing, better customer support, and more targeted communication.

Here’s how to get customer contact details into Mantle:

1. Contact capture (recommended): Set up Mantle contact capture to automatically collect information about team members who use your app.

2. API integration: Send contact details via the /identify endpoint with the optional contacts parameter.

3. CSV import: Include contact columns in your customer CSV import.

4. Manual addition: Add contacts directly to customer profiles through the Mantle UI.

For more details on setting up contacts for email purposes, check out our email guide.

Plan cadence

The Partner API doesn’t tell us if plans are monthly or annual. This gets especially tricky with annual plans that haven’t processed their first charge yet, which can mess up your MRR calculations.

Here’s how to fix it:

1. Head to your plans settings
2. Review the cadence applied to each plan
3. If you spot any issues, edit the plan
4. Set the correct billing interval:

5. Save your changes

Trials

The Partner API keeps us guessing about trial details like:

• Who’s currently on a trial
• How much trial time remains
• Which plans include trials and for how long
• Whether trials start on install or subscription

We’ve got some clever detection methods, but nothing beats proper configuration.

Global trial settings

To configure your app’s default trial behavior:

1. Go to your App settings (Your app → Settings)
2. Find the Trial Configuration section
3. Set when trials start – on install or subscription activation:

4. Define your default trial duration
5. Save your changes

Remember to do this for each app – they might handle trials differently!

Plan-specific settings

For plans that don’t follow your global trial rules:

1. Navigate to the plans section of your app
2. Find the plan you need to customize
3. Click edit on that plan
4. Adjust the trial length:

5. Save your changes
6. Repeat for any other plans that need custom trial settings

Discounts

Another Partner API blind spot – we can’t see:

• Who has active discounts
• Discount amounts and percentages
• How long discounts have been active
• When discounts expire

Apply discount for reporting

When you need to mark a customer’s discount for accurate reporting:

1. Create a discount code in Mantle first
2. Navigate to the customer’s detail page
3. Look for ‘Actions’ in the customer profile
4. Click ‘Manage Reporting’ under the Actions menu
5. Find the discount configuration section:

6. Enter the discount amount for their active subscription
7. Save your changes

Getting to perfect accuracy

Worked through everything above but don’t see changes in your reporting? Send us a message – we might need to resync your settings.

There are also complex scenarios that need special attention:

• Extended trials
• Plan changes with new trials
• Custom trial setups
• Expiring or newly introduced discounts

The integration advantage

Want your customer data, trial status, and discount information to be spot-on automatically? The best-kept secret is integrating with Mantle. When you’re integrated, we can:

• Pull shop plan and contact details automatically
• Get exact trial data directly from each shop’s Admin API
• Track discount details with precision
• Keep everything synced as merchants make changes

Ready to integrate? Check out the integration docs – it’s easier than you think and unlocks even more powerful features.

Still have questions? Give us a shout – we’re here to help!