Skip to main content
Custom pricing allows you to price features using your own unit (such as credits) instead of only standard currencies like USD or EUR.

​
What is custom currency?

Custom currency is pricing in your own unit (such as credits) instead of a standard money currency like USD or EUR. You set and show prices in that unit-for example, “10 credits per month”-and Flexprice converts those amounts to your base currency (e.g. USD) for billing, This ensures a consistent currency for accounting, even though the feature is shown in credits.

​
How it works internally

All billing calculations are performed using the pricing unit’s base currency (for example, USD). Amounts are defined and displayed in the pricing unit (e.g. credits), Conversion happens only at price or wallet creation; Flexprice uses the base currency for all calculations. In other words: input and display use the pricing unit; computation, persistence, and invoicing use base currency. Conversion uses the formula amount in your unit × conversion_rate = amount in base currency. Rounding and precision (e.g. two decimals for USD, zero for JPY) are applied only when invoice charges are computed, not at conversion or when creating prices or price units. Wallet balance is always shown in base currency and credits, whether the wallet was created with fiat or a custom price unit. Flexprice stores and bills everything in the base currency (e.g. USD).

​
Using custom currency

  1. Create a Price Unit (dashboard or API, below).
  2. Use in plans — add charges or create prices in your unit; see Use cases.
  3. Use in wallets — create a wallet in your unit; see Use cases.

​
Use cases

  • Credits or tokens - Sell in credits or tokens; show balance and charges in that unit while billing and storing in base currency (e.g. USD).
  • Multi-currency display, single-currency billing - Present prices in a custom unit per region or product while retaining one base currency for accounting and payouts.

​
Concepts and terminology

Custom currency / Price Unit - Your own pricing unit (e.g. credits) used instead of fiat currency. Defined once as a Price Unit and reused across plans, prices, and wallets, with automatic conversion to the base currency for billing.
FieldDescription
code3-character identifier (e.g. CRD, TOK, fpc) used when referencing the unit in a price or wallet. Must be unique per environment when Active.
symbolDisplay symbol shown in the UI and on invoices (e.g. ¢, ==).
base_currencyThe standard currency the unit is pegged to (e.g. usd). All billing and storage use this currency.
conversion_rateMultiplier from the custom unit to base currency.
Conversion formula 
amount in your unit × conversion_rate = amount in base currency
Example: If 1 credit = 0.01 USD, set conversion_rate = "0.01". Then 100 credits = 1.00 USD. Price unit types: FIAT vs CUSTOM
  • FIAT - Amounts are in a standard currency (USD, EUR, etc.). No conversion is applied.
  • CUSTOM - Amounts are in a Price Unit. Flexprice converts to base currency for billing; you configure and display values in the custom unit.

​
Create a Price Unit (dashboard)

1

Open Price Units

Go to Product Catalog → Price Units → Add (or Create Price Unit).
2

Fill in the details

Enter Name, Code, Symbol, Base currency, and Conversion rate.
Example: 100 units = 1 USD → use conversion rate 0.01.
Create Price Unit

​
Create a Price Unit (API)

1

Call the create endpoint

Send POST /v1/prices/units with a JSON body (you can see example below).
2

Send the required fields

Include name, code, symbol, base_currency, and conversion_rate. Optionally metadata.
Example request 
{
  "name": "Credits",
  "code": "CRD",
  "symbol": "¢",
  "base_currency": "usd",
  "conversion_rate": "0.01",
  "metadata": {}
}
Conversion, 100 CRD = 1.00 USD. Base URL options: https://us.api.flexprice.io/v1 or https://api.cloud.flexprice.io/v1 (check out the Create price unit).

​
Use custom currency in plans and prices

You can add charges or create prices in your custom unit from the dashboard or via the API. In both cases you choose your Price Unit and enter amounts in that unit; Flexprice converts to base currency for billing.

​
Dashboard

1

Open the plan

Go to Product Catalog → Plans → open the plan you want to edit.
2

Add charges in custom currency

In Charges, click + Add (or Edit then add). In the Currency dropdown choose Custom and select your Price Unit. Add recurring or usage-based charges and enter amounts in your unit (e.g. 15 credits/month). Click Save.
For more detail and screenshots, see Use cases: add charges and wallet.

​
API

1

Set the price to use your unit

In the create-price request (POST /v1/prices), set price_unit_type to CUSTOM and include price_unit_config.
2

Set price_unit and amount or tiers

In price_unit_config set price_unit (your unit’s code, e.g. CRD). For a fixed amount use amount; for tiered pricing use price_unit_tiers only (not the top-level tiers field).
Example: fixed monthly price in credits The request must also include type (e.g. FIXED), billing_cadence (e.g. RECURRING), and invoice_cadence (e.g. ADVANCE or ARREAR). Below shows the custom-pricing–relevant fields: 
{
  "currency": "usd",
  "price_unit_type": "CUSTOM",
  "type": "FIXED",
  "billing_model": "FLAT_FEE",
  "billing_period": "MONTHLY",
  "billing_cadence": "RECURRING",
  "invoice_cadence": "ADVANCE",
  "entity_type": "PLAN",
  "entity_id": "your-plan-id",
  "price_unit_config": {
    "price_unit": "CRD",
    "amount": "100.00"
  }
}
With conversion_rate = "0.01", 100 CRD = 1.00 USD. Flexprice stores both the custom amount and the base-currency amount and uses base currency for billing. Billing models
ModelIn price_unit_configNotes
FLAT_FEEprice_unit, amountFixed price in your unit.
PACKAGEprice_unit, amounttransform_quantity is required; for usage add meter_id.
TIEREDprice_unit, price_unit_tiersUse price_unit_tiers only, not top-level tiers. For usage add meter_id.
Refer to the API Reference and Price Unit documentation. check out the API Reference and the Price Unit.