Identify

Identify your customers to Mantle so it can automatically enrich customer data and perform actions via third party platforms such as Shopify or Stripe. This is done by providing Mantle with details of the merchant from your app’s hosted platform to the /identify endpoint.

When building a typical Shopify app and interacting with the Shopify API, you will create an access_token for each merchant who installs your app. This access_token can be acquired after the Shopify OAuth process has completed. More details can be found in the documentation of Shopify’s GraphQL Authentication.

POST https://appapi.heymantle.com/v1/identify

Options for identifying customers

Mantle offers two options when identifying your customers:

  1. Using the access token: provide the accessToken to Mantle to automatically enrich your customer data (eg. shop plan and shop email).

  2. Providing customer information directly: Alternatively, you can pass your own customer information directly to Mantle using the API, without the need for an access token. Simply omit the access token and include your customer’s details as parameters (e.g., Email: [email protected]).


POST /v1/identify

Identify your customer to Mantle.


Header parameters

X-Mantle-App-Idstring

The App Id when you create an API key in your Mantle dashboard.

X-Mantle-App-Api-Keystring

The API key found in the Mantle dashboard. This is used to identify your users to Mantle and should be kept secret, and used only in server-side code.

Body parameters

platformstring

(Required) Platform name, such as “shopify” or “stripe”

platformIdstring

Customer ID on the platform, this is the Shopify Shop ID or Stripe customer ID

myshopifyDomainstring

(Required if platform is shopify) This is the unique myshopify.com domain for the shop

namestring

(Optional) Customer name

emailstring

(Optional) Customer email

platformPlanNamestring

(Optional) The name of the plan on the platform, only applicable for Shopify. This field will be populated automatically if an access_token is provided.

accessTokenstring

(Optional) Customer access token for the platform API - The access token obtained from authenticating with your customer.

customFields<string,object>

(Optional) Key-value pairs of custom fields to store on the customer.

contacts[object]

(Optional) An array of contacts to store on the customer.

features<string,any>

(Optional) Key-value pairs of features to override on the customer. Normally features are automatically set based on the customer's subscription, but this allows you to override them.

curl --request POST \
  --url https://appapi.heymantle.com/v1/identify \
  --header 'X-Mantle-App-Api-Key: string' \
  --header 'X-Mantle-App-Id: string' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platform": "shopify",
  "platformId": "123456",
  "myshopifyDomain": "testshop.myshopify.com",
  "name": "testshop",
  "email": "[email protected]",
  "accessToken": "shpat_1234567890"
}
'

While setting custom fields for your customer:

curl --request POST \
  --url https://appapi.heymantle.com/v1/identify \
  --header 'X-Mantle-App-Api-Key: string' \
  --header 'X-Mantle-App-Id: string' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platform": "shopify",
  "platformId": "123456",
  "myshopifyDomain": "testshop.myshopify.com",
  "name": "testshop",
  "email": "[email protected]",
  "accessToken": "shpat_1234567890",
  "customFields": {
    "custom1": "value1",
    "custom2": "value2"
  },
  "contacts": [
    {
      "label": "primary",
      "name": "Bruce Wayne",
      "email": "[email protected]",
      "phone": "1234567890"
    },
    {
      "label": "secondary",
      "name": "Dick Grayson",
      "email": "[email protected]",
      "phone": "1234567890"
    },
    {
      "label": "technical",
      "name": "Alfred Pennyworth",
      "email": "[email protected]",
      "phone": "1234567890"
    }
  ]
}
'

Example response

{
  "apiToken": "e7cb87da-37db-4466-ada0-a67babdf45da"
}

On a successful response, you’ll receive an apiToken. This token is necessary for making queries to other Mantle endpoints. Store it in the database of the app’s shop model alongside the Shopify access token (if applicable), as this will be used by future requests to the Mantle API.