Skip to navigation
Products & pricingPricing 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
curl https://test.api.solvimon.com/v1/pricing-plan-schedules/ppsc_jwDeeN0tYSY3F7BkeN1v/on-demand-pricing-items \
     -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
{
  "pricing_plan_subscription_id": "ppsu_ZwDeeN0vcSMXaMAFhN19",
  "pricing_plan_schedule_id": "ppsc_jwDeeN0tYSY3F7BkeN1v",
  "pricing_plan_version_id": "ppve_pwDeeN0vcYJaBLAc0C1U",
  "pricing_categories": [
    {
      "object_type": "PRICING_CATEGORY",
      "id": "prct_gwDeeN0vcYJaBLAc0C1V",
      "pricings": [
        {
          "object_type": "PRICING",
          "id": "pric_hwDeeN0vcYJaBLAc0C1W",
          "name": "Setup fee",
          "product_type": "ADDON",
          "items": [
            {
              "object_type": "PRICING_ITEM",
              "id": "prii_ewDeeN0vcZ0ioTAmib1d",
              "configs": [
                {
                  "object_type": "PRICING_ITEM_CONFIG",
                  "id": "pico_iwDeeN0vcYJaBLAc0C1X",
                  "on_demand": true,
                  "type": "FLAT"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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
curl -X POST http://localhost:10004/v1/invoices/charge-on-demand-pricing-items \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "pricing_plan_schedule_id": "ppsc_jwDeeN0tYSY3F7BkeN1v",
  "pricing_items": [
    {
      "pricing_item_id": "prii_ewDeeN0vcZ0ioTAmib1d"
    }
  ],
  "start_at": "2026-07-01T00:00:00Z",
  "finalize_immediately": true,
  "payment_method_id": "pmet_fwDeeN0vhphnhMAcBp1G",
  "preview": false
}'
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.
pricing_items[].unitsyes (for FLAT items)The number of units to charge for a one-off item priced FLAT. Must be positive.
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.

pricing_items accepts the same pricing_item_id more than once. Each occurrence charges its own line and carries its own invoice date, and both lines land in the same invoice group. For example, an item priced at 100 USD granting a fixed 500 credits, listed twice, charges 200 USD and grants 1000 credits.

A one-off item priced FLAT bills a unit price times a count, so the request states the count in units. It is required for such an item and must be positive. There is no fallback to the item’s default_units: that value prefills your ordering screen, while the request states what the customer actually ordered. Ordering zero units is rejected. See One-off pricing.

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

Response
{
  "object_type": "INVOICE",
  "id": "invo_kwDeeN0vhq0hnMAcBq2H",
  "invoice_number": "INV-2026-07-00042",
  "customer_id": "cust_AbD3DqausjOYiMNDZY11F",
  "status": "FINAL",
  "type": "ONE_OFF",
  "created_at": "2026-07-01T00:00:00Z",
  "updated_at": "2026-07-01T00:00:00Z",
  "invoice_date": "2026-07-01T00:00:00Z",
  "billing_currency": "EUR",
  "invoice_amount_including_tax": {
    "quantity": "250.00",
    "currency": "EUR"
  },
  "pricing_plan_subscription_ids": [
    "ppsu_ZwDeeN0vcSMXaMAFhN19"
  ],
  "payment_status": "UNPAID",
  "paid": false
}

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: Wallet top-ups, which uses on-demand items to sell credits, One-off pricing, Add-ons, Invoices and One-off invoices.