Subscriptions

A Subscription in Moesif represents a single plan a customer has subscribed to and paying for. It corresponds to the Subscriptions entity for billing providers such as Stripe. For more information, see Provider Mapping.

How Subscriptions Relate to Companies

To understand how Subscriptions relate to Companies in Moesif, let’s see how Moesif models its data structure.

Apart from API Calls and Actions event types, Moesif also tracks these entities:

Users
Companies
Subscriptions

The following diagram illustrates how these components relate to one another:

These events and entities constitute Moesif’s data structure for its API analytics, observability, and monetization capabilities.

Subscriptions are how Moesif implements various monetization features in its platform. A subscription describes how a Company makes recurring payments for a specific product under a plan. A Company can have one or more subscriptions.

With a built-in subscriptions model, Moesif natively integrates with different billing providers like Stripe and how they implement subscriptions. This allows you to perform various analytics on your customers based on different subscription and billing criteria.

Subscription Metadata

You can attach subscription demographics or any custom properties that you want to relate to a subscription by storing them in a metadata object.

{
    "subscription_id": "12345",
    "company_id": "67890",
    "current_period_start": "2024-10-21T17:32:28.000Z",
    "current_period_end": "2024-11-21T17:32:28.000Z",
    "status": "active",
    "metadata": {
        "subscription_type": "PAYG",
        "subscription_tier": "Pro",
        "quota": {
            "quota_limit": 1000000,
            "quota_period": "Year"
        }
    }
}

In the preceding Subscriptions object, the metadata field contains information about the specific type and tier of subscription the company has subscribed to. It also contains information about the allowed quota for that specific subscription type and tier.

For more information about the Subscription fields, see the Subscriptions API documentation.

Overview of API Calls

Moesif Subscriptions (/v1/subscriptions) API allows you to manage your subscriptions by creating and updating them one at a time or in a batch.

Prerequisites

To use Moesif Subscriptions API, you must set your Moesif Application ID as the value of a X-Moesif-Application-Id HTTP header when sending requests to the /v1/subscriptions endpoints.

After you log into Moesif Portal, you can get your Moesif Application ID during the onboarding steps. You can always access the Application ID any time by following these steps from Moesif Portal after logging in:

Select the account icon to bring up the settings menu.
Select Installation or API Keys.
Copy your Moesif Application ID from the Collector Application ID field.

Endpoints

POST https://api.moesif.net/v1/subscriptions
POST https://api.moesif.net/v1/subscriptions/batch

Create or Update a Subscription

To create or update a single subscription, send POST request to the endpoint https://api.moesif.net/v1/subscriptions. For example:

curl --location 'https://api.moesif.net/v1/subscriptions' \
--header 'X-Moesif-Application-Id: YOUR_COLLECTOR_APPLICATION_ID' \
--header 'Content-Type: application/json' \
--data '{
    "subscription_id": "12345",
    "company_id": "67890",
    "current_period_start": "2024-10-21T17:32:28.000Z",
    "current_period_end": "2024-11-21T17:32:28.000Z",
    "status": "active",
    "metadata": {
        "subscription_type": "PAYG",
        "subscription_tier": "Pro",
        "quota": {
            "quota_limit": 1000000,
            "quota_period": "YEAR"
        }
    }
}'

Replace YOUR_COLLECTOR_APPLICATION_ID with your Moesif Application ID.

If the subscription doesn’t exist, Moesif creates a new one.

If a subscription exists, Moesif merges the new subscription properties with the existing properties recursively. Therefore, you don’t need to resend the entire Subscription object if you only mean to update a single field.

Create or Update Subscription in Batch

To create or update multiple subscriptions in a batch, send POST request to the endpoint https://api.moesif.net/v1/subscriptions/batch. For example:

# You can also use wget
curl --location 'https://api.moesif.net/v1/subscriptions/batch' \
--header 'X-Moesif-Application-Id: YOUR_COLLECTOR_APPLICATION_ID' \
--header 'Content-Type: application/json' \
--data '[{
    "subscription_id": "12345",
    "company_id": "67890",
    "current_period_start": "2024-10-21T17:32:28.000Z",
    "current_period_end": "2024-11-21T17:32:28.000Z",
    "status": "active",
    "metadata": {
        "subscription_type": "PAYG",
        "subscription_tier": "Pro",
        "quota": {
            "quota_limit": 1000000,
            "quota_period": "YEAR"
        }
    }
}]'