Subscriptions API

Retrieve prices for your currently selected organization. Prices will be returned in the currency of your currently selected organization. Prices are used to create subscriptions and invoice items.

This API is only available to authenticated users, and it takes discounts, commercial agreements, and user locality into account when returning prices.

The Subscription Object

Name
id
Type
string
Description
Unique identifier for the subscription.
Name
automatic_tax
Type
boolean
Description
Whether MikroCloud automatically computes tax on this subscription.
Name
cancel_at_period_end
Type
boolean
Description
If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period.
Name
collection_method
Type
enum
Description
Either charge_automatically, or send_invoice. When charging automatically, MikroCloud will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, MikroCloud will email the account an invoice with payment instructions and mark the subscription as active.
Name
current_period_end
Type
datetime
Description
End of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.
Name
current_period_start
Type
datetime
Description
Start of the current period that the subscription has been invoiced for.
Name
cancel_at
Type
datetime
Description
A date in the future at which the subscription will automatically get canceled
Name
ended_at
Type
datetime
Description
If the subscription has ended, the date the subscription ended.
Name
canceled_at
Type
datetime
Description
If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with cancel_at_period_end, canceled_at will reflect the time of the most recent update request, not the end of the subscription period when the subscription is automatically moved to a canceled state.
Name
days_until_due
Type
integer
Description
Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where collection_method=charge_automatically.
Name
description
Type
string
Description
The subscription’s description, meant to be displayable to the customer.
Name
items
Type
array
Description
A collection of subscription items.
Name
created_at
Type
datetime
Description
Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Subscription Object

{
    "id": "sub_1NsfQVCVnXOZCtu9bmuaIp9t",
    "automatic_tax": true,
    "cancel_at_period_end": false,
    "collection_method": "charge_automatically",
    "current_period_end": "21 Oct 2023",
    "current_period_start": "21 Sep 2023",
    "cancel_at": null,
    "ended_at": null,
    "canceled_at": null,
    "days_until_due": null,
    "description": null,
    "items": [
        //...
    ],
    "created_at": "2023-09-21 05:27:47"
}

The Subscription Item Object

Name
id
Type
string
Description
Unique identifier for the subscription item.
Name
quantity
Type
integer
Description
The quantity of the plan to which the customer should be subscribed.
Name
price
Type
object
Description
An instance of the price object that is associated with this subscription item.
Name
product
Type
object
Description
An instance of the product object that is associated with this subscription item.
Name
created_at
Type
datetime
Description
Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Subscription Item Object

{
    "id": "sub_1NsfQVCVnXOZCtu9bmuaIp9t",
    "quantity": 3,
    "price": {
        //...
    },
    "product": {
        //..
    },
    "created_at": "2023-09-21 05:27:47"
}

The Price Object

Name
id
Type
string
Description
Unique identifier for the price.
Name
amount
Type
float
Description
The unit amount of the product, represented as a float with at most 12 decimal places.
Name
currency
Type
string
Description
Three-letter ISO currency code, in uppercase. Must be a supported currency.
Name
currency_symbol
Type
string
Description
The UTF-8 symbol of the currency.
Name
type
Type
enum
Description
One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
Name
interval
Type
enum
Description
The frequency at which a subscription is billed. One of day, week, month or year. Will be null if type is one_time.

The Price Object

{
    "id": "price_1NZPv8CVnXOZCtu9dHCOcbvH",
    "amount": 0,
    "currency": "USD",
    "currency_symbol": "$",
    "type": "recurring",
    "interval": "month"
}

The Product Object

Name
id
Type
string
Description
Unique identifier for the product.
Name
name
Type
string
Description
The product's name, meant to be displayable to the customer.
Name
slug
Type
string
Description
The product slug is a human-readable unique identifier for the product which should be used when creating subscriptions.
Name
features
Type
array
Description
A list of features included in the product.
Name
unit_label
Type
string
Description
A label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal.

The Product Object

{
    "id": "prod_OM6pdT1wGbccUl",
    "name": "SDWAN Enablement",
    "slug": "sdwan-enablement",
    "features": [
        "Simplified remote management of devices",
        "Router health monitoring and alerts",
        "Daily backups with 12 month retention",
        "Includes DynDNS name",
        "Uptime SLA reporting"
    ],
    "unit_label": "site"
}

GET/v1/account/prices

Retrieve Prices

Requires the account:read scope.

Returns a collection of objects, each containing a price and product object based on your currently selected organization.

Parameters

No parameters are required for this endpoint.

Responses from this endpoint are cached for 6 hours.

Example request

curl -G https://api.mikrocloud.com/v1/account/prices \
-H "Authorization: Bearer {token}"

Example response

[
    {
        "price": {
            "id": "price_1NZPv8CVnXOZCtu9dHCOcbvH",
            "amount": 0,
            "currency": "USD",
            "currency_symbol": "$",
            "type": "recurring",
            "interval": "month"
        },
        "product": {
            "id": "prod_OM6pdT1wGbccUl",
            "name": "SDWAN Enablement",
            "slug": "sdwan-enablement",
            "features": [
                "Simplified remote management of devices",
                "Router health monitoring and alerts",
                "Daily backups with 12 month retention",
                "Includes DynDNS name",
                "Uptime SLA reporting"
            ],
            "unit_label": "sites"
        }
    },
    //...
]

GET/v1/account/subscriptions

Retrieve Subscriptions

Requires the account:read scope.

Parameters

No parameters are required for this endpoint.

Example request

curl -G https://api.mikrocloud.com/v1/account/subscriptions \
-H "Authorization: Bearer {token}"

Example response

[
    {
        "id": "sub_1NsfQVCVnXOZCtu9bmuaIp9t",
        "automatic_tax": true,
        "cancel_at_period_end": false,
        "collection_method": "charge_automatically",
        "current_period_end": "21 Oct 2023",
        "current_period_start": "21 Sep 2023",
        "cancel_at": null,
        "ended_at": null,
        "canceled_at": null,
        "days_until_due": null,
        "description": null,
        "items": [
            {
                "id": "si_OhQNGAlQHvDmFA",
                "quantity": 1,
                "price": {
                    "id": "price_1NZPv8CVnXOZCtu9dHCOcbvH",
                    "amount": 0,
                    "currency": "USD",
                    "currency_symbol": "$",
                    "type": "recurring",
                    "interval": "month"
                },
                "product": {
                    "id": "prod_OM6pdT1wGbccUl",
                    "name": "SDWAN Enablement",
                    "slug": "sdwan-enablement",
                    "features": [
                        "Simplified remote management of devices",
                        "Router health monitoring and alerts",
                        "Daily backups with 12 month retention",
                        "Includes DynDNS name",
                        "Uptime SLA reporting"
                    ],
                    "unit_label": "sites"
                },
                "created_at": "2023-09-24 23:15:35"
            },
            //...
        ],
        "created_at": "2023-09-21 05:27:47"
    }
]

PUT/v1/account/subscriptions/{subscription_id}/items/{id}

Update Item Quantity

Requires the account:read scope.

Name
subscription_id
Type
string
Required
Required
Description
Unique identifier for the subscription.
Name
id
Type
string
Required
Required
Description
Unique identifier for the subscription item.

Parameters

Name
quantity
Type
integer
Required
Required
Description
The quantity of the plan to which the customer should be subscribed.

Example request

curl -G https://api.mikrocloud.com/v1/account/subscriptions/{subscription_id}/items/{id}
-H "Authorization: Bearer {token}"

Example response

{
    "id": "si_OhQNGAlQHvDmFA",
    "quantity": 3,
    "price": {
        "id": "price_1NZPv8CVnXOZCtu9dHCOcbvH",
        "amount": 0,
        "currency": "USD",
        "currency_symbol": "$",
        "type": "recurring",
        "interval": null
    },
    "product": {
        "id": "prod_OM6pdT1wGbccUl",
        "name": "SDWAN Enablement",
        "slug": "sdwan-enablement",
        "features": [
            "Simplified remote management of devices",
            "Router health monitoring and alerts",
            "Daily backups with 12 month retention",
            "Includes DynDNS name",
            "Uptime SLA reporting"
        ],
        "unit_label": "sites"
    },
    "created_at": "2023-09-24 23:15:35"
}