> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Flexible pricing

Let a customer choose how much to pay within a range, and grant wallet credits in proportion to the amount paid. Built for self-service wallet top-ups.

---

## Why this matters

Not every charge has a fixed price. Sometimes the customer decides the amount: topping up a wallet with any value between a minimum and a maximum, and receiving credits in return. `FLEXIBLE` pricing models exactly this: a pay-what-you-choose, one-off charge bounded by a range, that converts the paid amount into wallet credits.

A typical use case is a prepaid wallet: the customer pays anything from \$20 to \$100 and receives a matching number of credits, which they then draw down through usage.

## How it works

`FLEXIBLE` is a [pricing type](/platform-guides/products-and-pricing/pricing-plans) set on the pricing item config of a [one-off](/platform-guides/products-and-pricing/pricing-plans/one-off-pricing) product item. It is always charged through the [on-demand](/platform-guides/products-and-pricing/pricing-plans/on-demand-charges) flow, so the customer triggers it when they want to top up rather than it recurring on a schedule.

You configure:

* **A single band** with a `minimum_amount` and a `maximum_amount` (same currency). The amount the customer pays must fall within this range.
* **One or more `wallet_grants`** that define how the paid amount converts to wallet credits, referencing the [wallet type](/platform-guides/wallets-credits/credit-types-wallets) to grant into.

At charge time you pass the customer's chosen amount as `flexible_amount`, and Solvimon grants the corresponding credits.

`FLEXIBLE` has a few hard constraints, enforced on create and update:

| Rule          | Detail                                                                      |
| ------------- | --------------------------------------------------------------------------- |
| Model type    | `ONE_OFF` only. `FLEXIBLE` is rejected for recurring and usage-based items. |
| On-demand     | `on_demand` must be `true`.                                                 |
| Bands         | Exactly one band, with both `minimum_amount` and `maximum_amount`.          |
| Compatibility | Not compatible with `USAGE_BASED`, top-up, or pass-through pricing types.   |

## Configuring a flexible pricing item

Add the pricing item config to a pricing plan version (or directly to a schedule). The `wallet_grants.credits_grant.conversion.rate` is the number of credits granted per unit of the paid currency:

**`Flexible pricing item config`**

```json Flexible pricing item config
{
  "type": "FLEXIBLE",
  "bands": [
    {
      "minimum_amount": { "quantity": "20.00", "currency": "EUR" },
      "maximum_amount": { "quantity": "100.00", "currency": "EUR" }
    }
  ],
  "wallet_grants": [
    {
      "wallet_type_id": "wtyp_...",
      "credits_grant": {
        "conversion": {
          "credit_type_id": "ctyp_...",
          "rate": "2.5"
        }
      }
    }
  ],
  "order": 1,
  "on_demand": true
}
```

With the config above, a customer who pays \$40 receives `40 × 2.5 = 100` credits of the referenced credit type. Paying the maximum \$100 would grant 250 credits.

## Charging a flexible item

Charge the item through the on-demand endpoint, passing `flexible_amount` for the chosen amount:

**`Charge a flexible on-demand item`**

```bash Charge a flexible on-demand item
curl -X POST https://test.api.solvimon.com/v1/invoices/charge-on-demand-pricing-items \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_plan_schedule_id": "ppsc_...",
    "pricing_items": [
      {
        "pricing_item_id": "proi_...",
        "flexible_amount": { "quantity": "40.00", "currency": "EUR" }
      }
    ],
    "preview": true
  }'
```

| Field                             | Required                 | Description                                                                                                                                             |
| --------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pricing_plan_schedule_id`        | yes                      | The schedule the on-demand item belongs to.                                                                                                             |
| `pricing_items[].pricing_item_id` | yes                      | The flexible on-demand item to charge.                                                                                                                  |
| `pricing_items[].flexible_amount` | yes (for flexible items) | The amount the customer chose to pay. Must fall within the item's band.                                                                                 |
| `preview`                         | no                       | When `true`, returns the resulting invoice without persisting it, so you can show the customer what they'll be charged and the credits they'll receive. |

Set `preview` to `false` (or omit it) to create the invoice and grant the credits. See [On-demand charges](/platform-guides/products-and-pricing/pricing-plans/on-demand-charges) for the full set of charge options such as `finalize_immediately` and `payment_method_id`.

## Via Desk

The pricing editor supports the `FLEXIBLE` pricing type directly: select it on a one-off, on-demand pricing item and configure the minimum and maximum amounts of the band and the credit conversion. Self-service top-up pricing can be set up without code; the editor enforces the same constraints as the API.

## Edge cases

* A `flexible_amount` outside the band's `minimum_amount`–`maximum_amount` range is rejected with a validation error.
* The `flexible_amount` currency must match the band currency.
* Only one-off, on-demand items can be `FLEXIBLE`; the config is rejected on any other model type or when `on_demand` is not `true`.

For the charge calls that use a `FLEXIBLE` item, including automatic top-ups, see [Wallet top-ups](/platform-guides/wallets-credits/wallet-top-ups).

---