Managing Usage Credits
Managing credits in Moesif is easy to do and can be done through the Moesif UI, via a Company Profile, or through Moesif’s API. Unlike many billing providers, which manage an available balance at the customer level, Moesif can segregate available funds based on subscription.
For instance, a company may be subscribed to two pay-as-you-go plans. They would like to add $100 to plan A and $1000 to plan B. Traditionally, when managed at the billing provider level, this would just be shown as an available balance of $1100 at the customer level that could be freely spent between subscriptions. This makes it hard to control spending for a specific subscription if you have multiple. With Moesif, you can add the balance to each specific subscription to ensure that spending is controlled at the subscription (or service) level.
Usage Credit Fields
When managing your customer’s balances in Moesif, there are three fields and values that a company’s profile contains to be aware of.
Current Balance
This value is the current balance without factoring in any pending activity/transactions that have not been processed yet.
Pending Activity
This is the activity/transactions (credits or debits) that have not yet been posted. This value is mutable and the value can change up until the transaction is posted. Once posted, this will be reflected in the updated Current Balance field and removed from the amount under Pending Activity.
For example, if there is API usage or credits that have been added to an account, you will see the corresponding amount here until it has been posted.
Available Balance
From a usage perspective, this amount is the most important as it dictates what credits a user has left to spend, in a pre-paid scenario. This value is the amount of credits/$ that are left for the user to consume. This amount is equal to (Current Balance + (plus) Pending Activity).
For example, if my current balance is $1000 and I have a $250 debit transaction pending, my available balance will be $750. Below is a table to demonstrate this:
| Field | Value |
|---|---|
| Current Balance | $1000 |
| Pending Activity | $250 |
| Available Balance | $750 |
Adding a Transaction
There are four types of records that can be added to the Moesif credit ledger: Debits, Credits, Promotions, and Adjustments.
Debit records are usually associated with usage. These records will draw down the available balance.
Credit records are usually associated with top-ups where users have added funds to the system. These records will increase the available balance.
Records can be added either through the Moesif UI (through the Company Profile page) or the Moesif Management API. The UI gives users a way to manually add in credits while the API can help with those who are looking for automation, such as automatically adding credits to the Moesif ledger when a transaction happens on the billing provider side. For instance, if $10 in credits is added via Stripe, you could detect this, likely using Stripe’s webhook, and use the Moesif API to automatically add the $10 to Moesif’s ledger.
Adding a Transaction Record
To add a Credit record for a subscription, navigate to the Company’s profile. This can be done by clicking on the Company ID throughout various reports or by looking the company up through the Company Lookup and going to their profile.
In the company’s profile beside the Current Balance field, click on the pencil/edit icon.
This will bring up the Add Transaction modal.
This modal contains fields for the following information:
- Subscription Id
- The subscription you would like to apply the transaction towards. This dropdown will contain all of the subscriptions that the company is subscribed to.
- Type
- The type of transaction you want to post to the account. This value, selected from the dropdown, can be either Credit, Debit, Promotion, or Adjustment.
- Transaction ID
- A unique ID that Moesif will use to deduplicate any transactions. You can either use the value provided or enter your own. An example of a custom ID here may be using the Stripe Payment Intend ID of the transaction that you handled in Stripe.
- Active at (Optional)
- An optional field that for a credit transaction. Moesif applies the credits to the subscription balance after the time you specify here. Note that the subscription balance itself does not automatically update after the activation time. It updates when Moesifi sends more usage or after you create another balance transaction.
- Expire at (Optional)
- An optional field for a credit transaction. It specifies when the credits expire. Any remaining credits become unusuable.
Based on your usage amount, Moesif creates a new balance transaction to subtract the remaining credits from the subscription balance. If no usage occurs before the expiration date, Moesif subtracts the full credit amount. Otherwise, Moesif subtracts the remaining credits.
For example, assume that you’ve created a balance transaction of $100 credits that expire sometime in the future. Before the expiration date, Moesif tracks and meters a usage of $4. When the credits expire, Moesif subtracts the remaining $96 credits from the balance.
- Amount
- The amount of the transaction in major currency units (e.g. dollars instead of cents). The amount can be positive or negative depending on the Type:
| Type | Allowed Amount |
|---|---|
| credit | positive (+) |
| debit | negative (-) |
| promotion | positive (+) |
| adjustment | positive (+) or negative (-) |
If you are creating a transaction via the Moesif UI, the +/- value will be handled based on the Type selected.
- Description (Optional)
- An optional field where you can add a description for the transaction. This will only be stored internally but can be useful for audit purposes.
-
Once you have added this info, you will see how the transaction will affect the company’s balance in the Balance Preview. Here you will be able to see the results of the transaction on the company’s Available Balance.
-
To add this transaction, click the Add Transaction button.
Via API
Transactions can also be added via API. This can be done using the Moesif Management API’s /billing/reports/balance_transactions endpoint. More details on the API can be found within the API Docs for the endpoint.
A Moesif Management API token is required for this action that includes the following scopes:
create:billing_meterscreate:billing_reports
Below is an example of how the API could be used within a Node application.
const body = {
company_id: "cus_1234abc", // The Company ID within Moesif
amount: 100, // amount in dollars (i.e. major currency unit)
type: "credit", // transaction type (credit, debit, promotion, etc.)
subscription_id: "sub_456def", // Subscription ID within Moesif
transaction_id: uuidv4().toString(), // random transaction ID or external/custom one
description: "top up from API, post Stripe top-up event", // optional, description of the transaction
};
try {
const response = await fetch(
"https://api.moesif.com/~/billing/reports/balance_transactions", // API URL
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "bearer ey13aDfgT567...", // Moesif Management API Token, including scope for create:billing_meters, create:billing_reports
},
body: JSON.stringify(body),
}
);
if (response.ok) {
console.log("Balance transaction created successfully");
} else {
console.error(
"Failed to create balance transaction!",
response.status,
response.statusText,
await response.json()
);
}
} catch (error) {
console.error("An error occurred while creating balance transaction:", error);
}
This API call will create the same transaction as the UI will but can be used in automated processes that leverage the Moesif credit ledger.
For debit notes, an example body is shown below:
const body = {
company_id: "cus_1234abc", // The Company ID within Moesif
amount: -100, // amount in dollars (i.e. major currency unit)
type: "debit", // transaction type (credit, debit, promotion, etc.)
subscription_id: "sub_456def", // Subscription ID within Moesif
transaction_id: uuidv4().toString(), // random transaction ID or external/custom one
description: "monthly fee", // optional, description of the transaction
};
Credit Balance Behavior
Stripe doesn’t support prepaid subscriptions. To help you implement prepaid credits-based systems easily with Stripe, Moesif supports automatic application of credits to Stripe invoices. It builds on top of Moesif’s real-time credits consumption and usage tracking system.
Key Features
- Automatically apply credits to Stripe invoices.
- Customize behavior for zero credit balance.
Limitations
- Only supported for Stripe.
- Only supported for per-unit and package pricing.
How It Works
This feature automatically applies credits to Stripe invoices. When creating a Billing Meter, you can choose between these options to control how Moesif applies credits:
Bill Customer (Default)
This option creates Stripe credits for the customer if a positive subscription balance exists in Moesif. Specifically, the Available Balance must have a positive amount.
Stripe credits the customer’s credit balance by the specific usage amount it receives from Moesif. The credit adjustment amount can go up to the amount of subscription balance you have. After the adjustment, Stripe then applies the remaining balance to the finalized invoice.
Here’s an example that walks you through how this option works:
- You have $20 as Available Balance in Moesif. You also have an active subscripiton that expires at a certain time.
- While your subscription is active, Moesif tracks a $12 usage for your subscription. It meters the usage and sends the usage details to Stripe.
- Stripe creates an invoice for the usage.
- Assume that the positive $20 Available Balance still exists at the time Moesif sends the usage.
- Stripe performs a credit adjustment of $12 against the credit balance. Your remaining balance comes down to ($20-$12) = $8.
- Stripe finalizes the invoice for $0.
- If the subscription balance goes to $0, or below $0, or no balance exists, Stripe doesn’t apply any credits. Rather, it invoices the customer for the full usage amount $12.
- Assume that the positive $20 Available Balance still exists at the time Moesif sends the usage.
The following table shows some more example scenarios with different amounts:
| Available Balance | Usage | Stripe credits | Invoice |
|---|---|---|---|
| $20 | $5 | $5 | $0 |
| $20 | $20 | $20 | $0 |
| $20 | $27 | $20 | $7 |
| $0 | $27 | $0 | $27 |
| -$5 | $27 | $0 | $27 |
Zero Out Invoices
This option always creates Stripe credits to balance usage. Moesif sends the usage amounts as usual, but invoices will be zeroed out with credits. This option allows you to invoice customers manually or through another system. Choose this option if you want to use Stripe for usage monitoring only and use an alternative method for billing or invoicing.
This option works the same way as Bill Customer, except that the amount of credits always equals the usage amount. Here’s a table showing some example scenarios:
| Available Balance | Usage | Stripe credits | Invoice |
|---|---|---|---|
| $20 | $5 | $5 | $0 |
| $20 | $20 | $20 | $0 |
| $20 | $27 | $27 | $0 |
| $0 | $27 | $27 | $0 |
| -$5 | $27 | $27 | $0 |