Configure for accuracy

As you explore Mantle, you might notice some numbers don’t match your expectations or certain data seems missing. 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 for subscriptions or “free” plans).

Most often though, it’s because the Shopify Partner API needs a little help with five key areas: missing customer data, plan names, 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, their subscription status, pricing, and billing frequency. Let’s fix each one.

Missing customer data

When you first connect Mantle to your Shopify Partner account, you’ll get a lot of data automatically – but not everything. The Partner API has a few blind spots, and key details like shop plan and email addresses aren’t included. This can affect your reporting accuracy and limit segmentation options.

Common missing data points:

• Shop plan (Basic, Shopify, Professional, Shopify Plus)
• Email addresses (for communication and customer identification)

How to fill in this missing data:

There are three ways to fill in these gaps:

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 shop plan, email, and other 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 a quick fix or smaller customer bases, you can:

   • Go to individual customer profiles and edit their details directly
   • Import a CSV file with customer data (including shop plan, email, etc.)

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

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

Customer contacts and emails

Besides the shop’s primary email, you might also want to collect contact information for individual team members at a merchant’s store. This is especially useful for email marketing, better customer support, and more targeted communication.

There are multiple ways to get customer contact details into Mantle:

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

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

3. API provision: Send contact details via the /identify endpoint with the optional contacts parameter.

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

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

Plan cadence

The Partner API doesn’t explicitly tell us if plans are monthly or annual. This can get especially fuzzy with annual plans that haven’t processed their first charge yet, leading to potential misclassification in your metrics.

To straighten this out:

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

5. Save your changes

Trials

The Partner API keeps us guessing about:

• Who’s currently on a trial
• How much trial time remains
• Which plans include trials
• Trial duration per plan
• Whether trials start on install or subscription

We’ve got some clever detection methods and reverse engineering to figure this out, 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. Look for the Trial Configuration section
3. Set when trials start – on install or subscription activation:

4. Define your default trial duration that applies to most plans
5. Save your changes

Remember to repeat this process for each app you have on the App Store – each one 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 directly see:

• Who has active discounts
• How much each discount is worth
• How long discounts have been active
• When discounts are set to expire

Apply discount for reporting

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

1. Create a discount code in Mantle. While discounts are typically used with Mantle Billing, they can be used for reporting purposes.
2. Navigate to the customer’s detail page in Mantle
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

Remember: If you’re not integrated with Mantle, these settings only affect reporting, not your actual customers.

Getting to perfect accuracy

If you worked through the recommendations above but don’t see the changes reflected in your reporting, send us a message. We may need to resync your new settings for changes to take effect.

Beyond that there are plenty of complex cases. Trial and discount data gets trickier when you’re dealing with:

• Extended trials
• Plan changes with new trials
• Custom trial scenarios
• Expiring discounts
• Newly introduced discounts

If you want your customer data, trial status, and discount information to be spot-on automatically, the poorly kept secret is a super lightweight integration with Mantle. When 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 in sync as merchants make changes over time

To learn more about integrating, check out the docs. There are even more reasons to integrate, and the path to integration is easy to get started and simple to complete.

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