Identifying customers

Identification is the foundational step for integrating your app with Mantle. This process establishes a secure connection between your app and Mantle's platform, enabling analytics, billing capabilities, and customer insights.

Why identification matters

Identifying your customers to Mantle allows the platform to:

• Create a unified record of each customer's activity and data
• Provide secure access to Mantle's APIs through customer-specific tokens
• Enable advanced analytics and reporting capabilities
• Support billing operations when needed

Identification methods

Mantle offers two approaches to customer identification, each designed for specific use cases and enabling different capabilities. This is a brief overview - for complete details, see our comprehensive Identify documentation:

Basic identification

A streamlined approach that provides analytics capabilities without requiring a Shopify access token. Perfect for apps focused on customer insights and tracking.

What you get:

• Track customer usage and behavior
• Access customer data and insights
• View available plans
• Analytics and reporting features

Enhanced identification

A comprehensive method that leverages the Shopify access token to enable the full spectrum of Mantle capabilities.

What you get:

• Everything from Basic identification, plus:
• Create and manage subscriptions through Shopify Billing
• Automatically enrich customer data through Shopify's Admin API
• Access to advanced billing features
• Complete subscription lifecycle management

Identification as your data gateway

The /identify endpoint is the only endpoint that directly updates customer information in Mantle's App API. It serves two critical functions:

1. Enriching data automatically - When provided with an access token, Mantle automatically pulls this information:

   • Shop plan
   • Email address on file
   • Trial information
   • Discount information

2. Accepting custom data directly - You can manually send, fill in, or update these additional details:

   • Updated email addresses
   • Customer tags
   • Custom fields
   • Country/location data
   • Contact details (name, email, phone)
   • Any other merchant-specific attributes

This endpoint gives you precise control over what information is stored in your customer profiles, whether through automatic enrichment or manual updates.

Quick implementation

Basic identification

Using the MantleClient we set up earlier:

const mantleClient = new MantleClient({
  appId: process.env.MANTLE_APP_ID,
  apiKey: process.env.MANTLE_APP_API_KEY,  // Your API key for backend operations
});

const mantleResponse = await mantleClient.identify({
  platform: "shopify",
  platformId: "123456",  // your customer's Shopify ID
  myshopifyDomain: "mystore.myshopify.com",
  name: "My Store",
  email: "[email protected]"
});

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

Enhanced identification

For full billing capabilities, include the Shopify access token:

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

const mantleResponse = await mantleClient.identify({
  platform: "shopify",
  platformId: "123456",
  myshopifyDomain: "mystore.myshopify.com",
  name: "My Store",
  email: "[email protected]",
  accessToken: "shpat_xxx"  // Shopify access token enables enhanced features
});

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

When successful, Mantle returns an apiToken that you should store in your database alongside other customer data. You'll use this token for future API calls related to this customer.

Choosing the right method

Select your identification method based on your app's requirements:

• For analytics only: Use Basic Identification to track customer activity and gain insights without implementing billing functionality.
• For analytics + billing: Use Enhanced Identification to access all Mantle features, including subscription management and usage-based billing.

Using identification with a proxy

For enhanced security or infrastructure requirements, Mantle supports proxying your identification requests. This allows you to route identify calls through your own services before they reach Mantle.

See our API Proxy for details on implementing this approach.

What happens next

All identification methods return a unique customer API token that you'll use for subsequent requests to Mantle's API, ensuring secure communication while protecting sensitive information.