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:
-
Using the access token: provide the
accessToken
to Mantle to automatically enrich your customer data (eg.shop plan
andshop email
). -
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-Id
stringThe App Id when you create an API key in your Mantle dashboard.
X-Mantle-App-Api-Key
stringThe 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
platform
string(Required) Platform name, such as “shopify” or “stripe”
platformId
stringCustomer ID on the platform, this is the Shopify Shop ID or Stripe customer ID
myshopifyDomain
string(Required if platform is shopify) This is the unique myshopify.com domain for the shop
name
string(Optional) Customer name
email
string(Optional) Customer email
platformPlanName
string(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.
accessToken
string(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.