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:
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",
"items": [{
"plan_id": "my_custom_plan_id"
}],
"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",
"items": [{
"plan_id": "my_custom_plan_id"
}],
"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",
"items": [{
"plan_id": "my_custom_plan_id"
}],
"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 a 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.