Credits in pricing plans

This page covers how to configure credits inside a pricing plan: granting credits to customers, pricing usage-based products in credits instead of currency, and handling overage when a wallet runs out.

Granting credits

A wallet grant attaches to a revenue item in a pricing plan. When a subscription is activated, Solvimon deposits the configured credits into the customer’s wallet.

To add a wallet grant, click the three dots menu on a revenue item and select Add wallet grant. You can attach a wallet grant to both recurring and one-off revenue items. On a recurring item, credits are deposited at subscription activation and renewed at the start of each billing period. On a one-off item, credits are deposited once at activation.

Select the Wallet to fund, set the Balance topup amount, and configure the Expiry period if you want unused credits to expire at the end of each period.

When the grant is created

A recurring grant is created at the start of the pricing period it belongs to, not when the invoice covering that period is issued and not when it is paid. The customer can spend the credits from the first day of the period, whether you bill in advance or in arrears, and whether or not the invoice has been settled.

Each pricing period produces its own wallet grant with its own start_at and expire_at, rather than adding to an existing one. That is why a customer can hold several grants in one wallet at the same time, and why consumption follows the earliest expiry first rule.

Where the pricing period is shorter than the billing period, one invoice carries several periods and therefore several grants. A monthly item billed twice a year is charged for six months on one invoice and deposits six monthly grants, each valid for its own month, rather than one grant for the whole invoice. A monthly expiry_policy then behaves as configured: the customer gets a fresh monthly allowance that expires unused, not half a year of credits at once.

Grant fields in the API

A grant configured on a pricing item produces a WalletGrant on the subscription. The fields you will read back:

On the pricing item, a credits grant can convert an amount into credits using a conversion rate against a credit type, so the same plan can express the grant in currency and deposit credits. See Credit revenue & breakage for how paid_amount drives revenue recognition.

curl -X POST https://api.solvimon.com/v1/wallet-grants \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "customer_id": "string",
  "billing_entity_id": "string",
  "wallet_id": "string"
}'

{
  "object_type": "string",
  "id": "string",
  "customer_id": "string",
  "billing_entity_id": "string",
  "wallet_id": "string",
  "type": "DEFAULT",
  "source": "FIXED",
  "seat": {
    "customer_id": "string",
    "product_item_id": "string"
  },
  "over_granted": {
    "credits": {
      "quantity": "string",
      "credit_type_id": "string",
      "credit_type": {
        "object_type": "string",
        "id": "string",
        "reference": "string",
        "status": "DRAFT",
        "name": "string",
        "description": "string",
        "unit_name": {
          "singular": "string",
          "plural": "string"
        },
        "created_at": "string",
        "updated_at": "string"
      }
    },
    "amount": {
      "quantity": "string",
      "currency": "AED"
    }
  },
  "description": "string",
  "grant_amount": {
    "quantity": "string",
    "currency": "AED"
  },
  "grant_credits": {
    "quantity": "string",
    "credit_type_id": "string",
    "credit_type": {
      "object_type": "string",
      "id": "string",
      "reference": "string",
      "status": "DRAFT",
      "name": "string",
      "description": "string",
      "unit_name": {
        "singular": "string",
        "plural": "string"
      },
      "created_at": "string",
      "updated_at": "string"
    }
  },
  "paid_amount": {
    "quantity": "string",
    "currency": "AED"
  },
  "start_at": "2024-01-15T09:30:00Z",
  "expire_at": "2024-01-15T09:30:00Z",
  "created_at": "string"
}

Create a grant directly through this endpoint to issue credits outside a pricing plan, for example a goodwill grant after an incident. Set type to PROMOTION so the grant is distinguishable in reporting, and set paid_amount to zero so it recognises no revenue when consumed.

Pricing usage in credits

A usage-based revenue item can be configured to consume credits from a wallet instead of charging currency directly. The price is expressed as a number of credits per unit of usage.

When adding a usage-based revenue item to the pricing plan, set the pricing currency to the credit type you want to consume, then define the rate (e.g. 1 credit per 30 seconds, or 1.5 credits per 50 seconds).

You can use meter property filters to set different rates for different conditions, exactly as you would with currency-based usage pricing.

Overage

When a customer’s wallet balance reaches zero, you can charge them for additional usage in currency by adding a Credit-type revenue item to the pricing plan.

Start by creating a revenue item in the product catalog and set its Model type to Credits.

Once the revenue item is created, add it to the pricing plan and set the price per credit in currency (e.g. $0.10 per credit).

Overage is one way to handle an empty wallet. The other is to refill it: see Wallet top-ups.