Fees functionality

Fees can be configured and collected from end users via the Investment API. These fees are often considered service fees for asset management services such as portfolio management. In its current scope, the fee functionality allows Clients to collect pre-calculated fee amounts from their end users. In future iterations of the fee functionality, the Investment API will cover the fee model configuration as well as the fee calculation in addition to the fee collection.

How fee collections work

End users can be charged for the services provided by the client. To use fee collections, the client calculates the fee amounts on the client side and uses the Investment API to collect it. This can be done via deductions from available cash balances, via sell-to-cover orders or via a combination of both.

Implementing the fee collection

Prerequisites

To use the fee collection functionality, Upvest has to enable the respective API endpoints for you. To collect fees from a cash balance or via sell-to-cover orders, the user must have an active account group and account.

Fee collections

Fee collections describe the processing of pre-calculated fee amounts. The fee amounts can originate from fee calculations on the Investment API or from client-calculated fees. The fees collections can be created, listed and retrieved.

Creating a fee collection

After you have a pre-calculated fee amount, you can create a fee collection as follows:

POST /fees/collections

Example request

{
    "account_id": "689f7566-2ca3-4007-b99d-e501be8c7783",
    "type": "SERVICE_FEE",
    "collection_amount": "12.41",
    "currency": "EUR",
    "period_start": "2022-11-01",
    "period_end": "2022-11-30"
}
Parameter Description
account_id Required: The ID of the account on which the fees shall be charged.
type Required: Specify the type SERVICE_FEE for normal cadence fee collections or SERVICE_FEE_LIQUIDATION as a result of account liquidations.
collection_amount Required: The pre-calculated amount of fees to be collected.
currency Required: Specify the currency. Currently, only EUR is supported.
period_start Required: Start date of the fees calculated.
period_end Required: End date of the fees calculated.

Please note that initiating a fee collection processs is only possible for accounts that are not in PENDING_APPROVAL or CLOSED statuses. Should the account be in a PENDING_APPROVAL or CLOSED status, a Bad Request response code will be returned. Otherwise you will receive a fee collection object with fee collection ID in the response.

Fee collection status

The following statuses apply to a fee collection:

Status Description
PROCESSING Fee collection is in progress.
FINALISED Fee collection is finalized - fees have been collected from the account and the funds have been transferred to the client.
CANCELLED Fee collection is cancelled.

Listing fee collections

You can retrieve a fee collection with its specific fee_collection_id as follows:

All fee collections can be listed with

COMING SOON

Fee configuration and fee calculation will become available soon.

Reporting on fees collections

Webhooks for potential sell-to-cover orders, cash balance updates and the financial transaction reporting of the type FEE_COLLECTION are available. The transaction reporting webhook and object contains a reference to the fee collection object for additional details.

Next steps

Get familiar with the fee collection reporting using the transaction reporting functionality.

Was this page helpful?

On This Page