Creating Usage Credits

This document describes how to create credit transactions in Moesif using Moesif Web Portal and Moesif Management API.

Overview

You can add four types of records to the Moesif credit ledger:

  • Debits
  • Credits
  • Promotions
  • Adjustments

Debit records are usually associated with usage. These records draws down the available balance.

Credit records are usually associated with top-ups where users have added funds to the system. These records increases the available balance.

You can add records either from the Company Profile page in Moesif Web Portal 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 audtomation, 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 using 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 using Moesif Web Portal UI

To add a Credit record for a subscription, navigate to the Company’s profile. You can do this by clicking on the Company ID throughout various reports or by looking the company up through Company Lookup and going to their profile.

In the company’s profile beside the Current Balance field, click on the pencil/edit icon. transaction button location


This will bring up the Add Transaction modal. Add transaction Modal

The following table describes the information this modal contains:

Field Name Description
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 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, for example, dollars instead of cents. The amount can be positive or negative depending on the Type:
  • For Credit type, the amount is positive.
  • For Debit type, the amount is negative.
  • For Promotion type, the amount is positive.
  • For Adjustment type, the amount can be either positive or negative.
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.

Add a Transaction Record using 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_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: 100.0, // amount in dollars (i.e. major currency unit)
  expire_at: "2025-01-09T17:18:58.560Z", // credit expiration date
  active_at: "2025-01-09T17:18:58.560Z", // the activation time for the credit transaction 
  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 creates the same transaction as the UI does but you can use the API approach to automate 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
};

Updated: