[CHANGE REQUEST] Per-tariff service fees in /operator/pricing-plans for out-of-station/area returns

[stephan233]

API Version

TOMP-API 1.6 (baseline for the proposed extension)

Summary

Introduce an optional per-tariff service fee descriptor in /operator/pricing-plans to allow to expose static fees that apply when a vehicle (e.g., bike) is returned outside a station or outside the operator’s business area. This removes the need for MaaS platforms to hardcode such fees and ensures fees are machine-readable and consistent across implementations.

We implemented the proposed functionality like in the example given in the end for the TOMP API of Call a Bike, the bikesharing system of Deutsche Bahn.

Expected Behavior

• GET /operator/pricing-plans returns pricing plans whose tariffs may include an optional list of service fees.
• Fees are static (non-dynamic) and defined per tariff, not globally.
• Typical fees include charges for “return outside station” and “return outside operation area.”
• Each fee includes amount, type (e.g., FIXED), VAT rate, and currency, aligned with existing tariff components.
• MaaS platforms consume these fields to display and calculate total costs accordingly, without hardcoding.

Current Behavior

• No standardized, per-tariff representation of these service fees in /operator/pricing-plans.
• MaaS platforms often hardcode or infer such fees, leading to inconsistency and potential mismatches.

Possible Solution

Steps to Reproduce

This is no bug.

Context (Environment)

• Use case: Free-floating or station-based micromobility where returns outside a station or outside the operator’s business area incur a fixed fee.
• Stakeholders: MaaS Providers (defining fees per tariff), MaaS platforms (consuming and presenting fees, ensuring price transparency).
• The extension is optional and per-tariff to allow fine-grained control, even if it introduces some redundancy across tariffs.

Detailed Description

• Scope: Operator Information module, specifically GET /operator/pricing-plans.
• Data model change: Introduce an optional field fees within each tariff.
• Semantics:
  • Fees are static and applied when a vehicle is returned outside a station or outside the operation area.
  • Per-tariff configuration allows different fees by tariff/product.
• Field definitions (aligned with existing tariff components):
  • amount: decimal >= 0
  • type: enum, FIXED (initial scope)
  • kind: categorization (e.g., SURGE; consistent usage across tariffs)
  • name: stable technical code (e.g., feeReturnOutsideStation, feeReturnOutsideOperationArea)
  • vatRate: percentage 0–100
  • currencyCode: ISO 4217 code (e.g., EUR)
  • description: optional, localization handled by MaaS platform
• Backward compatibility: Fully backward compatible; absent field or empty array indicates no service fees. No deprecation phase required.
• Validation: Same as existing tariff parts (amount >= 0, vatRate within 0–100, valid currencyCode, recognized type/kind).

Possible Implementation

Illustrative schema snippet for GET /operator/pricing-plans (showing a tariff with time-based components and per-tariff fee components embedded in the existing array):

[
  {
    "planId": "1532788324",
    "name": "RMVplus Starter",
    "fare": {
      "estimated": false,
      "parts": [
        {
          "amount": 0,
          "kind": "DISCOUNT",
          "unitType": "MINUTE",
          "scaleFrom": 0,
          "scaleTo": 0,
          "scaleType": "MINUTE",
          "units": 1,
          "meta": {
            "applicableAssetSubClass": "BIKE"
          },
          "type": "FLEX",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 1.00,
          "kind": "DEFAULT",
          "unitType": "MINUTE",
          "maximumAmount": 12.00,
          "scaleFrom": 0,
          "scaleTo": 1440,
          "scaleType": "MINUTE",
          "units": 15,
          "meta": {
            "applicableAssetSubClass": "BIKE"
          },
          "type": "FLEX",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 12.00,
          "kind": "DEFAULT",
          "unitType": "MINUTE",
          "maximumAmount": 12.00,
          "scaleFrom": 1440,
          "scaleType": "MINUTE",
          "units": 1440,
          "meta": {
            "applicableAssetSubClass": "BIKE"
          },
          "type": "FLEX",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 0.00,
          "kind": "DEFAULT",
          "type": "FIXED",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 0.00,
          "kind": "DISCOUNT",
          "type": "FIXED",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 10.00,
          "kind": "SURGE",
          "name": "feeReturnOutsideStation",
          "type": "FIXED",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        },
        {
          "amount": 25.00,
          "kind": "SURGE",
          "name": "feeReturnOutsideOperationArea",
          "type": "FIXED",
          "vatRate": 19.0,
          "currencyCode": "EUR"
        }
      ]
    },
    "isTaxable": true
  }
]

[bent-lorentzen]

I'm not entirely sure I see the need here. The name field is an optional description of the price. We use this as a description of the elements in the pricing-plan. "Fee for parking outside operational area", "Unlock fee", etc. This gives the operator the ability to give a description in the language specified by the end user. Do you propose to change this field to an enumerator? That would definitely be a breaking change in our code. If we are to limit the field to specific values, how do we define an exhaustive list of values?
Pardon me if I don't understand your scenario. Please enlighten me if I've misunderstood you.

[edwinvandenbelt]

Stephan, could you please respond? Is it also an option to extend the 'FareStructureElement.priceCondition' (v2), to add 'FEE' to this enumeration (DEFAULT, DISCOUNT, SURGE)?
In v1.6 it would impact the FarePart.kind probably we won't release a v1.7, unless we get a lot of new requests. We decided when at the end of this year, there won't be major extension requests, a v1.7 is not developed. In a peer-2-peer solution, you can add 'FEE' to this enum.

[stephan233]

Hello Bent and Edwin, sorry for the late response! We discussed this again internally at Call a Bike after reading your thoughts on the matter. Certainly, the proposed solution can be implemented implicitly - meaning we just choose what's working from our perspective and still be conform to the standard. An exhaustive list of values can certainly not be defined upfront, while - of course - following the idea of an open and evolving standard that list of values could be extended in the future as needed.

It would be great if you could take our request as a hint and if more requests following the same direction should be submitted later on a further consideration would be appreciated. So far our needs are covered in v1 and v2 with the existing SURGE option.