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 This is 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 This is 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 This is 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.

Amount This is the amount of the transaction. The +/- value will be handled based on the Type selected, so this value should only contain positive numbers (no negation is needed).

For example, for a debit record (that will negate from the balance), you would still add in a value such as “10.99” and not “-10.99”.

Description [OPTIONAL] This is an optional field where you can add a description for the transaction. This will only be stored internally but can be good 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.

Add transaction Modal

To add this transaction, click the Add Transaction button.


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_meters
  • create: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": 10000, // amount in cents
        "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("", // 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 help with automated processes that want to leverage the Moesif credit ledger.