Enhanced identification

Complete Identification provides full access to Mantle's capabilities by using the Shopify access token obtained during the OAuth process. This method, leveraging Mantle's /identify endpoint, enables complete analytics through the enrichment of data from the Admin API as well as billing operations, allowing you to manage subscriptions and track customer behaviour comprehensively.

How Enhanced identification Works

When you identify a customer using this method, you provide Mantle with the customer's Shopify access token. In return, Mantle gives you a customer apiToken - a secure credential that:

• Allows your app to make authenticated requests to Mantle
• Protects your customer's Shopify access token from unnecessary exposure
• Creates a secure communication channel between your app and Mantle's API
• Enables Mantle to perform authorized operations on your behalf

This security architecture means your app never needs to expose the Shopify access token in client-side code, as all sensitive operations are performed through Mantle's secured API using the provided apiToken.

When to use Enhanced identification

This method is ideal when you need to:

1. Create and manage subscriptions through Shopify Billing
2. Implement usage-based billing for metered features
3. Manage Trials and Discounts on App Charges
4. Access enhanced customer data automatically enriched through Shopify APIs
5. Manage feature entitlements based on subscription plans

Implementation

Required parameters

{
  "platform": "shopify",
  "platformId": "shop_id",
  "myshopifyDomain": "example.myshopify.com",
  "accessToken": "shpat_1234567890abcdef",
  "name": "Example Store",
  "email": "[email protected]"
}

Using MantleClient

const mantleClient = new MantleClient({
  appId: process.env.MANTLE_APP_ID,
  apiKey: process.env.MANTLE_API_KEY,
});

const response = await mantleClient.identify({
  platform: "shopify",
  platformId: "123456",
  myshopifyDomain: "example.myshopify.com",
  accessToken: "shpat_1234567890abcdef",
  name: "Example Store",
  email: "[email protected]"
});

// Store this token for future API calls
const customerApiToken = response.apiToken;

Direct API request

const response = await fetch('https://appapi.heymantle.com/v1/identify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mantle-App-Id': process.env.MANTLE_APP_ID,
    'X-Mantle-App-Api-Key': process.env.MANTLE_API_KEY,
  },
  body: JSON.stringify({
    platform: 'shopify',
    platformId: "123456",
    myshopifyDomain: "example.myshopify.com",
    accessToken: "shpat_1234567890abcdef",
    name: "Example Store",
    email: "[email protected]"
  }),
});

const result = await response.json();
const customerApiToken = result.apiToken;

Implementation timing

The best times to implement Complete Identification include:

1. During OAuth flow completion - Immediately after a merchant installs your app and you receive their access token
2. In your afterAuth handler - Include identification as part of your post-authentication flow
3. After access token rotation - When a merchant's access token changes or is refreshed
4. Via periodic synchronization - Run a scheduled job to ensure all customer data remains current

Storing the apiToken

You should securely store the returned apiToken in your database alongside other merchant information:

// Example with a database model
await Shop.update({
  mantleApiToken: result.apiToken
}, {
  where: { id: shop.id }
});

This token will be used for all subsequent requests to Mantle's API for this specific customer.

Capabilities enabled

Complete Identification unlocks Mantle's full feature set:

• Subscription management - Create, update, and cancel subscriptions via the Subscriptions API
• Billing operations - Implement usage-based billing, one-time charges, and plan changes
• Rich customer data - Access comprehensive customer information including Shopify plan, country, and other metadata
• Usage tracking - Send and analyze events via the Usage Events API
• Feature entitlements - Control feature access based on subscription plans
• Customer analytics - Get detailed insights into merchant behaviour and value