Customer
customer
object contains information specific to an authenticated user, such as their available plans, active subscription(s) and feature availability. To query this endpoint and access the desired data, you need to again provide your X-Mantle-App-Id
, along with the X-Mantle-Customer-Api-Token
that you received when you identified your customer to Mantle.GET https://appapi.heymantle.com/v1/customer
The Customer object
Query the customer
object for user details like plans and subscriptions.
Header parameters
X-Mantle-App-Id
stringThe App Id when you create an API key in your Mantle dashboard.
X-Mantle-Customer-Api-Token
stringThe API token you receive from your POST request to the /identify endpoint.
Attributes
id
stringUnique identifier for the customer.
test
booleanWhether the customer is a test customer. Test customers will automatically
installedAt
dateThe date the customer was installed.
plans
[object]An array of plans available to the customer.
subscription
objectThe customer's current subscription, if any.
trialStartsAt
dateThe date the customer's trial started.
trialExpiresAt
dateThe date the customer's trial will or did end.
billingStatus
enumThe billing status of the customer. One of none, active, canceled, frozen, or trialing.
usage
<string,object>Key-value pairs of usage metrics for the customer, where the key is the usage metric key and the value is key-value pairs of properties.
usageCredits
[object]An array of usage credits available to the customer.
reviews
[object]An array of reviews that the customer has left.
Plan attributes
id
stringUnique identifier for the plan.
name
stringPublic name of the plan.
description
stringA human-readable description of the plan.
type
enumThe type of the plan. One of base or add_on. Add on plans can only be added to a subscription with a base plan.
subtotal
decimalThe base cost of the plan, before any discounts are applied.
total
decimalThe total cost of the plan, after any discounts are applied.
eligible
booleanWhether the plan is eligible for this customer.
currencyCode
stringCurrency code of the plan.
availability
enumThe availability of the plan. One of public, customerTag, shopifyPlan, customer or hidden.
public
booleanWhether the plan is public and available to all customers.
trialDays
numberThe default number of days in the trial period.
interval
enumThe billing interval for the plan. One of EVERY_30_DAYS or ANNUAL.
features
<string,object>Key-value pairs of features available to the plan. Where the key is the feature key and the value is the body of the feature.
featuresOrder
[string]An array of feature keys in the order they should be displayed.
usageCharges
[object]An array of usage charges applicable to the plan.
usageChargeCappedAmount
decimalThe maximum amount that can be charged for usage charges.
customFields
<string,object>Key-value pairs that are used to store custom data on the plan.
discounts
[object]An array of discounts available for this plan. Only applicable when fetching a list of plans.
autoAppliedDiscount
objectThe discount that will be automatically applied to the plan.
createdAt
dateThe date the plan was created.
updatedAt
dateThe date the plan was last updated.
Features attributes
id
stringUnique identifier for the feature.
name
stringPublic name of the feature.
type
enumThe type of the feature. One of boolean, limit or limit_with_overage.
description
stringA human-readable description of the feature.
value
anyThe value of the feature. If the type is boolean, this will be a boolean. If the type is limit or limit_with_overage, this will be a number.
Usage attributes
id
stringUnique identifier for the usage metric.
name
stringPublic name of the usage metric.
eventName
stringThe event name (a key) used to track the usage metric, which was provided in the Mantle admin.
currentValue
numberThe current value of the usage metric.
monthToDateValue
numberThe value of the usage metric month-to-date.
allTimeValue
numberThe value of the usage metric all-time.
{
"customer": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"test": true,
"installedAt": "2024-02-26 12:33:19",
"trialStartsAt": "2024-02-29 00:00:00",
"trialExpiresAt": "2024-03-12 00:00:00",
"billingStatus": "active",
"plans": [
{
"id": "96e30ffb-cd18-43ec-8fd7-8b2a21320412",
"name": "Pro",
"description": null,
"currencyCode": "USD",
"public": true,
"trialDays": 14,
"interval": "EVERY_30_DAYS",
"availability": "public",
"createdAt": "2023-09-02 15:53:15",
"updatedAt": "2024-03-01 00:32:16",
"features": {
"custom_icons": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"name": "Custom icons",
"type": "boolean",
"description": "",
"value": true,
"displayOrder": 2
}
},
"featuresOrder": [
"custom_icons"
],
"usageCharges": [],
"usageChargeCappedAmount": null,
"customFields": {},
"discounts": [],
"autoAppliedDiscount": null,
"total": 10,
"subtotal": 10,
"amount": 10,
"eligible": true
}
],
"subscription": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"plan": {
"id": "96e30ffb-cd18-43ec-8fd7-8b2a21320412",
"name": "Pro",
"description": null,
"currencyCode": "USD",
"public": true,
"trialDays": 14,
"interval": "EVERY_30_DAYS",
"availability": "public",
"createdAt": "2023-09-02 15:53:15",
"updatedAt": "2024-03-01 00:32:16",
"features": {
"custom_icons": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"name": "Custom icons",
"type": "boolean",
"description": "",
"value": true,
"displayOrder": 2
}
},
"featuresOrder": [
"custom_icons"
],
"usageCharges": [],
"usageChargeCappedAmount": null,
"customFields": {},
"total": 10,
"subtotal": 10,
"amount": 10
},
"active": true,
"billingCycleAnchor": "2024-04-11 00:00:00",
"currentPeriodStart": "2024-03-12 00:00:00",
"currentPeriodEnd": "2024-04-11 00:00:00",
"trialStartsAt": "2024-02-29 00:00:00",
"trialExpiresAt": "2024-03-12 00:00:00",
"activatedAt": "2024-02-29 21:37:25",
"canceledAt": null,
"frozenAt": null,
"features": {
"custom_icons": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"name": "Custom icons",
"type": "boolean",
"description": "",
"value": true,
"displayOrder": 2
}
},
"featuresOrder": [
"custom_icons"
],
"usageCharges": [],
"createdAt": "2024-02-29 21:37:20",
"confirmationUrl": "...",
"shopifySubscription": {
"id": "gid://shopify/AppSubscription/123456"
},
"appliedDiscount": null,
"subtotal": 10,
"total": 10
},
"features": {
"custom_icons": {
"id": "8fca5ac8-6b79-4411-92cd-46d9560479c9",
"name": "Custom icons",
"type": "boolean",
"description": "",
"value": true,
"usage": null
}
},
"usage": {
"Page view events": {
"id": "new-usage-id",
"name": "Page view events",
"eventName": "page_view",
"currentValue": 4,
"monthToDateValue": 4
}
},
"customFields": {
"Extras": {
"demo": true
},
"traffic_source": "twitter",
"free_plan_product_limit": 5,
"test123": "50"
},
"currentInvoice": {
"periodStart": "2024-02-01 00:00:00",
"periodEnd": "2024-03-02 00:00:00",
"total": 406.13,
"currencyCode": "USD"
},
"usageCredits": [],
"reviews": [
{
"id": "123456",
"rating": 5,
"comment": "Amazing app! I love it!",
"createdAt": "2024-03-01 00:00:00"
}
]
}
}
GET /v1/customer
Send a GET request to retrieve information about the customer and which plans are available to them.
Header parameters
X-Mantle-App-Id
stringThe App Id when you create an API key in your Mantle dashboard.
X-Mantle-Customer-Api-Token
stringThe API token you receive from your POST request to the /identify endpoint.
curl --request GET \
--url https://appapi.heymantle.com/v1/customer \
--header 'X-Mantle-App-Id: string' \
--header 'X-Mantle-Customer-Api-Token: string'
Returns a customer
object with associated plans
, subscription
, features
, and usage
data.