Subscriptions

Mantle’s subscription API provides endpoints for creating, updating, and canceling customer subscriptions. When a customer selects a plan, a POST request to the subscriptions endpoint easily initiates the creation of a RecurringApplicationCharge, with Mantle automatically triggering this process for Shopify users.

POST   https://appapi.heymantle.com/v1/subscriptions
PUT    https://appapi.heymantle.com/v1/subscriptions
DELETE https://appapi.heymantle.com/v1/subscriptions

The Subscription object

Subscriptions allow you to create, update, and cancel recurring charges for your customers using their preferred billing method.

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

activatedAtdate

The date the subscription was activated.

trialStartsAtdate

The date the subscription's trial started.

trialExpiresAtdate

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

canceledAtdate

The date the subscription was canceled, if applicable.

frozenAtdate

The date the subscription was frozen by Shopify, if applicable.

activeboolean

Whether the subscription is currently active.

subtotaldecimal

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

totaldecimal

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

planobject

The plan of the subscription.

lineItems[object]

An array of subscription line items for the subscription.

currentPeriodStartdate

The start date of the current billing period.

currentPeriodEnddate

The end date of the current billing period.

billingCycleAnchordate

The anchor date for when the subscription is billed.

confirmationUrlstring

The URL to confirm the subscription.

features<string,object>

Key-value pairs of features available to the subscription. 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.

appliedDiscountobject

The discount, if any, that was applied to the subscription.

usageCharges[object]

An array of usage charges applicable to the subscription.

shopifySubscriptionobject

Details about the Shopify subscription, if applicable. Contains only the id.

createdAtdate

The date the subscription was created.

updatedAtdate

The date the subscription was last updated.

{
  "subscription": {
    "id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "plan": {
      "id": "b1c2d3e4-f5g6-h7i8-j9k0l1m2n3o4",
      "name": "Pro",
      "type": "base",
      "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": "d1e2f3g4-h5i6-j7k8-l9m0n1o2p3",
          "name": "Custom icons",
          "type": "boolean",
          "description": "",
          "value": true,
          "displayOrder": 2
        },
        "product_limit": {
          "id": "f1g2h3i4-j5k6-l7m8-n9o0p1q2r3",
          "name": "Product limit",
          "type": "limit",
          "description": "",
          "value": -1,
          "displayOrder": 4
        },
        "tabs": {
          "id": "i1j2k3l4-m5n6-o7p8-q9r0s1t2u3",
          "name": "Unlimited shared tabs",
          "type": "boolean",
          "description": "",
          "value": true,
          "displayOrder": 7
        },
      },
      "featuresOrder": [
        "custom_icons",
        "product_limit",
        "tabs",
      ],
      "usageCharges": [],
      "usageChargeCappedAmount": null,
      "customFields": {},
      "total": 10,
      "subtotal": 10,
      "amount": 10
    },
    "lineItems": [
      {
        "id": "d1e2f3g4-h5i6-1234-l9m0n1o2p3",
        "type": "subscription",
        "amount": 10,
        "currencyCode": "USD",
        "plan": {
          // same plan as above
        }
      }
    ],
    "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": "d1e2f3g4-h5i6-j7k8-l9m0n1o2p3",
        "name": "Custom icons",
        "type": "boolean",
        "description": "",
        "value": true,
        "displayOrder": 2
      },
      "product_limit": {
        "id": "f1g2h3i4-j5k6-l7m8-n9o0p1q2r3",
        "name": "Product limit",
        "type": "limit",
        "description": "",
        "value": -1,
        "displayOrder": 4
      },
      "tabs": {
        "id": "i1j2k3l4-m5n6-o7p8-q9r0s1t2u3",
        "name": "Unlimited shared tabs",
        "type": "boolean",
        "description": "",
        "value": true,
        "displayOrder": 7
      },
    },
    "featuresOrder": [
      "custom_icons",
      "product_limit",
      "tabs",
    ],
    "usageCharges": [],
    "createdAt": "2024-02-29 21:37:20",
    "confirmationUrl": "...",
    "shopifySubscription": {
      "id": "gid://shopify/AppSubscription/678901234"
    },
    "appliedDiscount": null,
    "subtotal": 10,
    "total": 10
  }
}

POST `/v1/subscriptions`

Create a subscription for your customers.

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.

Body parameters

planIdstring

The ID of the plan to subscribe the customer to.

planIds[string]

An array of plan IDs to subscribe the customer to. Use planIds when your customer is subscribing to a base plan with add-ons.

discountIdstring

The ID of the discount to apply to the subscription.

billingProviderenum

The billing provider for the subscription. One of shopify, stripe or test. If omitted, defaults to the platform billing API (ex. shopify). Required field for web-based (non-platform) apps.

returnUrlstring

The URL to redirect the customer to after subscription is complete. If not provided, defaults to the app root in the customer's Shopify Admin. Required field for web-based (non-platform) apps.

curl --request POST \
  --url https://appapi.heymantle.com/v1/subscriptions \
  --header 'X-Mantle-App-Id: string' \
  --header 'X-Mantle-Customer-Api-Token: string' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planId": "",
  "returnUrl": ""
}
'

Returns a subscription object for the newly created subscription.

DELETE `/v1/subscriptions`

Cancel a customer’s subscription.

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 DELETE \
  --url https://appapi.heymantle.com/v1/subscriptions \
  --header 'X-Mantle-App-Id: string' \
  --header 'X-Mantle-Customer-Api-Token: string'

Returns the canceled subscription object.

Subscriptions

The Subscription object

Header parameters

Attributes

POST /v1/subscriptions

Header parameters

Body parameters

DELETE /v1/subscriptions

Header parameters

POST `/v1/subscriptions`

DELETE `/v1/subscriptions`