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 set on the pricing item config of a one-off product item. It is always charged through the on-demand 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 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:

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:

1
{
2
  "type": "FLEXIBLE",
3
  "bands": [
4
    {
5
      "minimum_amount": { "quantity": "20.00", "currency": "EUR" },
6
      "maximum_amount": { "quantity": "100.00", "currency": "EUR" }
7
    }
8
  ],
9
  "wallet_grants": [
10
    {
11
      "wallet_type_id": "wtyp_...",
12
      "credits_grant": {
13
        "conversion": {
14
          "credit_type_id": "crty_...",
15
          "rate": "2.5"
16
        }
17
      }
18
    }
19
  ],
20
  "order": 1,
21
  "on_demand": true
22
}

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:

$
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
>
  }'

Set preview to false (or omit it) to create the invoice and grant the credits. See On-demand charges for the full set of charge options such as finalize_immediately and payment_method_id.

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.