Get started
Integrating with Mantle allows you to leverage powerful platform features such as to managing subscriptions, feature gating, and usage billing directly within your application. Follow these key steps to ensure a smooth integration process with Mantle.
Step 1: Identifying your customers
When to use: Immediately after a merchant installs your app.
Purpose: The /identify endpoint is crucial for initiating your app’s integration with Mantle. It should be called within the post-authentication callback after a Shopify install. This call associates the merchant’s shop with a unique customer token in Mantle’s system.
Implementation: Make a request to Mantle’s /identify endpoint, passing in necessary authentication details provided by Shopify. Store the returned Mantle customer token in your shop database table, as this token is essential for future API calls and interactions with Mantle.
Resources
Step 2: Utilizing customer data on the front-end
When to use: In the front-end part of your app, ideally within an app-wide React context (see example app).
Purpose: The /customer endpoint is used to retrieve current customer-specific details, such as the features available to them, their plans, available discounts, and more. Having this information accessible on any page enhances user experience and personalizes the merchant’s interaction with your app.
Implementation: Ensure that calls to the /customer endpoint are made where necessary to keep the context updated with the latest customer data. This data can influence feature availability, UI elements, and more based on the merchant’s current status and entitlements.
Resources
Step 3: Feature gating and subscription checks
When to use: For backend operations that require subscription validation or feature gating.
Options
Direct checks: Use the /customer endpoint to verify a customer’s subscription status or feature access rights in real-time. This approach is suitable for operations that can tolerate the latency of a network request.
Webhooks and caching: Utilize Mantle’s webhooks to listen for changes in customer status, plan updates, or feature entitlements. Cache these details locally to minimize latency and ensure efficient access during backend operations, especially for blocking web requests or background jobs.
Resources
Step 4: Handling usage billing
When to use: If your app implements usage-based billing.
Purpose: The /usage_events endpoint is designed to record usage events associated with your app. These events are then used by Mantle to calculate usage-based charges that are applied to the merchant’s Shopify bill.
Implementation: Send each usage event to the /usage_events endpoint as they occur. Mantle’s infrastructure is designed to handle high throughput, so there’s no need to batch these events before sending them.