Basic identification

The Basic Identification method allows you to identify customers to Mantle without requiring a Shopify access token, through the /identify endpoint of the App API. This approach is ideal when you want to track customer data and usage without implementing Mantle's billing functionality.

Basic Identification use cases

Use Basic Identification when you:

• Only need to track customer behaviour and analytics
• Don't require Shopify Billing integration
• Want minimal integration with customer data enrichment
• Are focused on insights rather than subscription management

When to identify customers

There are several key moments where you should identify customers:

1. After installation: Identify customers immediately after they install your app to begin tracking their journey right away.

2. During reauthorization: If a customer reinstalls your app or goes through the OAuth process again, re-identify them to maintain continuity in their data.

3. For existing customers: When adding Mantle to an existing app, run a bulk identify operation on your existing customer base to backfill data.

4. On a regular schedule: Consider setting up a periodic cron job to identify all customers, ensuring any data changes are kept in sync.

5. When customer data changes: If significant information about a customer changes (like email or name), re-identify them to update their profile.

Implementation

Required parameters

{
  "platform": "shopify",
  "platformId": "shop_id",
  "myshopifyDomain": "example.myshopify.com",
  "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",  // shop's ID
  myshopifyDomain: "example.myshopify.com",
  name: "Example Store",
  email: "[email protected]"
});

// Store the customer API token for future requests
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",
    name: "Example Store",
    email: "[email protected]"
  }),
});

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

Capabilities with Basic Identification

With Basic Identification, you can:

• Send usage events to track merchant activity via the Usage Events API
• Retrieve customer information including plans, features, and customFields via the Customer API
• Access usage metrics and reports via the Usage Report API
• Set and update custom fields on customer profiles
• Analyze customer behaviour through Mantle's reporting tools
• Track feature usage and adoption across your merchant base

The Basic Identification method provides all analytics capabilities but excludes billing operations that require a Shopify access token.

Limitations

Basic Identification does not provide access to:

• Subscription creation or management via Shopify Billing
• Usage-based billing implementation
• Automatic customer data enrichment through Shopify's Admin API