Products & plansPricing Plans

On-demand charges

Charge selected one-off product items on top of an existing subscription whenever you need to: a one-time setup fee, an extra package, or an add-on bought at the click of a button.

Why this matters

Some product items aren’t billed on a recurring schedule; they’re charged when the customer asks for them. Flagging a one-off product item pricing as on-demand (the on_demand flag on its pricing item config) lets you retrieve the on-demand items available for a subscription and charge one or more of them on a separate invoice, with an optional preview first.

Listing the available on-demand items

To know which on-demand items can be charged for a subscription, fetch them per pricing plan schedule with GET /v1/pricing-plan-schedules/{id}/on-demand-pricing-items. Pass the optional timestamp query parameter to evaluate the schedule’s pricing at a specific point in time; it defaults to now.

GET
/v:version/pricing-plan-schedules/:resourceId/on-demand-pricing-items
1curl https://test.api.solvimon.com/v1/pricing-plan-schedules/ppsc_jwDeeN0tYSY3F7BkeN1v/on-demand-pricing-items \
2     -H "X-API-KEY: <apiKey>"
Try it

The response mirrors a pricing plan version, filtered to the product item pricings that are ONE_OFF and flagged on-demand:

Response
1{
2  "pricing_plan_subscription_id": "ppsu_ZwDeeN0vcSMXaMAFhN19",
3  "pricing_plan_schedule_id": "ppsc_jwDeeN0tYSY3F7BkeN1v",
4  "pricing_plan_version_id": "ppve_pwDeeN0vcYJaBLAc0C1U",
5  "pricing_categories": [
6    {
7      "object_type": "PRICING_CATEGORY",
8      "id": "prct_gwDeeN0vcYJaBLAc0C1V",
9      "pricings": [
10        {
11          "object_type": "PRICING",
12          "id": "pric_hwDeeN0vcYJaBLAc0C1W",
13          "name": "Setup fee",
14          "product_type": "ADDON",
15          "items": [
16            {
17              "object_type": "PRICING_ITEM",
18              "id": "prii_ewDeeN0vcZ0ioTAmib1d",
19              "configs": [
20                {
21                  "object_type": "PRICING_ITEM_CONFIG",
22                  "id": "pico_iwDeeN0vcYJaBLAc0C1X",
23                  "on_demand": true,
24                  "type": "FLAT"
25                }
26              ]
27            }
28          ]
29        }
30      ]
31    }
32  ]
33}

The same endpoint is available in the Customer Portal API, so you can present on-demand items to your customers and let them buy directly from the portal.

Charging an on-demand item

Charge one or more on-demand items with POST /v1/invoices/charge-on-demand-pricing-items:

POST
/v:version/invoices/charge-on-demand-pricing-items
1curl -X POST https://api.solvimon.com/v1/invoices/charge-on-demand-pricing-items \
2     -H "X-API-KEY: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "pricing_plan_schedule_id": "ppsc_jwDeeN0tYSY3F7BkeN1v",
6  "pricing_items": [
7    {
8      "pricing_item_id": "prii_ewDeeN0vcZ0ioTAmib1d"
9    }
10  ],
11  "start_at": "2026-07-01T00:00:00Z",
12  "finalize_immediately": true,
13  "payment_method_id": "pmet_fwDeeN0vhphnhMAcBp1G",
14  "preview": false
15}'
Try it
FieldRequiredDescription
pricing_plan_schedule_idyesThe schedule the on-demand items belong to.
pricing_itemsyesThe on-demand items to charge, each referenced by pricing_item_id.
start_atnoWhen the charge applies. Must be in the future; defaults to now.
finalize_immediatelynoWhen true, the invoice moves straight from OPEN → DRAFT → FINAL in one call.
payment_method_idnoThe payment method to use. Defaults to the subscription’s payment method.
previewnoWhen true, returns the resulting invoice without persisting it, so you can show the customer what they’ll be charged.

The response is an invoice containing the charged on-demand lines:

Response
1{
2  "object_type": "INVOICE",
3  "id": "invo_kwDeeN0vhq0hnMAcBq2H",
4  "invoice_number": "INV-2026-07-00042",
5  "customer_id": "cust_123e4567-e89b-12d3-a456-426614174000",
6  "status": "FINAL",
7  "type": "ONE_OFF",
8  "created_at": "2026-07-01T00:00:00Z",
9  "updated_at": "2026-07-01T00:00:00Z",
10  "invoice_date": "2026-07-01T00:00:00Z",
11  "billing_currency": "EUR",
12  "invoice_amount_including_tax": {
13    "quantity": "250.00",
14    "currency": "EUR"
15  },
16  "pricing_plan_subscription_ids": [
17    "ppsu_ZwDeeN0vcSMXaMAFhN19"
18  ],
19  "payment_status": "UNPAID",
20  "paid": false
21}

Use preview: true to show the customer what the charge will look like before they confirm. A preview is never persisted and never finalized, regardless of finalize_immediately.

Typical flow

1

List the available items

Call GET /v1/pricing-plan-schedules/{id}/on-demand-pricing-items and show the available items to the customer.

2

Let the customer pick

The customer selects one or more items to buy.

3

Preview the charge (optional)

Call the charge endpoint with preview: true to show the expected invoice before the customer confirms.

4

Create the invoice

Call the charge endpoint with preview: false to create the invoice, optionally with finalize_immediately: true to finalize it in the same call.

See also: One-off pricing, Add-ons, Invoices and One-off invoices.