Customer

The Mantle 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-Idstring

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

X-Mantle-Customer-Api-Tokenstring

The API token you receive from your POST request to the /identify endpoint.

Attributes

idstring

Unique identifier for the customer.

testboolean

Whether the customer is a test customer. Test customers will automatically

installedAtdate

The date the customer was installed.

plans[object]

An array of plans available to the customer.

subscriptionobject

The customer's current subscription, if any.

trialStartsAtdate

The date the customer's trial started.

trialExpiresAtdate

The date the customer's trial will or did end.

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.

Plan attributes

idstring

Unique identifier for the plan.

namestring

Public name of the plan.

descriptionstring

A human-readable description of the plan.

typeenum

The type of the plan. One of base or add_on. Add on plans can only be added to a subscription with a base plan.

subtotaldecimal

The base cost of the plan, before any discounts are applied.

totaldecimal

The total cost of the plan, after any discounts are applied.

eligibleboolean

Whether the plan is eligible for this customer.

currencyCodestring

Currency code of the plan.

availabilityenum

The availability of the plan. One of public, customerTag, shopifyPlan, customer or hidden.

publicboolean

Whether the plan is public and available to all customers.

trialDaysnumber

The default number of days in the trial period.

intervalenum

The 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.

usageChargeCappedAmountdecimal

The 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.

autoAppliedDiscountobject

The discount that will be automatically applied to the plan.

createdAtdate

The date the plan was created.

updatedAtdate

The date the plan was last updated.

Features attributes

idstring

Unique identifier for the feature.

namestring

Public name of the feature.

typeenum

The type of the feature. One of boolean, limit or limit_with_overage.

descriptionstring

A human-readable description of the feature.

valueany

The 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

idstring

Unique identifier for the usage metric.

namestring

Public name of the usage metric.

eventNamestring

The event name (a key) used to track the usage metric, which was provided in the Mantle admin.

currentValuenumber

The current value of the usage metric.

monthToDateValuenumber

The value of the usage metric month-to-date.

allTimeValuenumber

The 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",
    "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": []
  }
}

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-Idstring

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

X-Mantle-Customer-Api-Tokenstring

The 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.

Customer

The Customer object

Header parameters

Attributes

Plan attributes

Features attributes

Usage attributes

GET /v1/customer

Header parameters

GET `/v1/customer`