Pricing, VAT, Balances, and Invoices

This part of the platform answers two different questions:

1. What should the member receive or be charged for? Pricing, extra services, VAT, and balances provide the answer.
2. Was the money request created, paid, or cancelled? Invoices, subscriptions, and Stripe provide the answer.

Keeping these questions separate is important. A correct price calculation does not prove that payment succeeded, and a Stripe payment does not explain why the amount was correct.

What makes up a member charge

Depending on the action, a charge can use:

• the member's company and account;
• region and currency;
• boat or boat type;
• booking dates and duration;
• extra services;
• fuel or other measured use;
• the VAT rule for that company and region;
• the member's existing allowance or balance.

The final amount should be understandable from those inputs. If an operator cannot explain the amount, do not repeat or manually replace the charge before the source values have been checked.

Extra services

Extra services describe optional items that can be attached to a booking, such as an additional service offered with a trip. The settings screen manages their name, icon, and active state.

Deactivating an extra service removes it from normal new choices but should not erase it from old bookings. Historical trips must still explain what the member received and paid for.

VAT

A VAT record connects a company and region to the rates used for general items, fuel, and other supported cases. The reason for this separation is legal and financial: different operating companies or locations can require different tax treatment.

Changing VAT is a forward-looking configuration change. It must not rewrite the tax already recorded on historical invoices.

Before changing it, confirm:

• the legal company and region;
• which kind of charge the rate applies to;
• whether the stored value is a percentage or an external Stripe tax-rate ID;
• that a test invoice uses the expected currency, rate, and Stripe account.

Member balances

Balances track allowances or value held for a member. The current system has separate operations for fuel, engine hours, and cash points; club days and booking tokens are separate concepts.

These values use different units and must not be combined into one “credit.” A balance correction should always record what was changed, in which unit, for which company or region, and why.

Invoices and subscriptions

An invoice is a request for a specific amount. A subscription is an agreement for recurring membership charges.

The system can create and send general or fuel invoices, cancel an invoice, create or cancel a subscription, list supported currencies, and accept payment provider updates. These are separate actions because their business effects are different.

flowchart LR
    A[Booking, fuel use, or membership decision] --> B[Calculate amount and VAT]
    B --> C[Choose the operating company]
    C --> D[Create invoice or subscription in Stripe]
    D --> E[Store provider identifiers locally]
    E --> F[Receive later payment updates]
    F --> G[Show final state to staff and member]

Cancelling an invoice does not end a subscription. Cancelling a subscription does not necessarily remove invoices that already exist.

Fuel invoices

A fuel invoice is created after the caller has supplied the fuel quantity and final price information. The payment service sends those values to the correct company's Stripe account.

This means an incorrect fuel invoice can begin earlier than Stripe: the check-in or check-out values, fuel price, VAT choice, or company context may be wrong. Investigate the full chain before blaming the payment provider.

Why company context is required

Each operating company can use different Stripe credentials and tax settings. The system selects the Stripe client from the company ID so that money is not sent through another legal entity's account.

If a company's configuration is missing, the operation should fail clearly. It must never silently fall back to another company's payment account.

Reconciliation: when two systems disagree

Stripe and the local database are updated by separate requests and later event messages. A network or processing failure can therefore leave them temporarily out of sync.

When this happens:

1. find the local invoice/subscription and its Stripe identifier;
2. check the object in the correct company's Stripe account;
3. compare amount, currency, tax, customer, and status;
4. check whether a provider update failed or has not arrived;
5. use a supported cancel/update/replay procedure.

Do not delete financial records or provider IDs to make the screen look clean. That removes the evidence needed to recover safely.

Technical reference

Admin settings cover extra services and VAT. Member screens cover balances, invoices, and subscriptions. Symfony payment operations are grouped under /api/v1/payments; company-specific Stripe behavior is implemented by Shared\Service\Payment\StripeService.