# Get fee collections

Returns the list of fee collections.
Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching fee collections. Narrow the result set with the `account_id` and `account_group_id` query parameters.
See the Fee collection guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_collection) / [BYOL](https://docs.upvest.co/products/byol/guides/fees/fees_collection)) for the collection lifecycle and webhook events.

Endpoint: GET /fees/collections
Version: 1.159.0
Security: oauth-client-credentials

## Security:

  - `oauth-client-credentials` (unknown)
    oauth2 scopes: fees:read, fees:admin

## Query parameters:

  - `account_id` (string)
    Filters the list to show only fees associated with a specific account ID.

  - `account_group_id` (string)
    Filters the list to show only fees associated with a specific account group ID.

  - `sort` (string)
    Field of resource to sort by.

  - `order` (string)
    Sort order of the result list if the `sort` parameter is specified. Use `ASC` for ascending or `DESC` for descending sort order.

  - `offset` (integer)
    Use the `offset` argument to specify where in the list of results to start when returning items for a particular query.

  - `limit` (integer)
    Use the `limit` argument to specify the maximum number of items returned.

## Header parameters:

  - `upvest-client-id` (string, required)
    Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).

  - `Authorization` (string, required)
    Bearer (access) token from the OAuth flow with correct scopes.
https://datatracker.ietf.org/doc/html/rfc6750

  - `signature` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

  - `signature-input` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

  - `upvest-api-version` (string)
    Upvest API version (Note: Do not include quotation marks)

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `meta` (object, required)
    Offset/limit pagination metadata for a list response. Contains the `offset` and `limit` applied to the request, the `count` of resources returned in this page, and the `total_count` of matching resources.

  - `meta.offset` (integer, required)
    Amount of resource to offset in the response.

  - `meta.limit` (integer, required)
    Total limit of the response.

  - `meta.count` (integer, required)
    Count of the resources returned in the response.

  - `meta.total_count` (integer, required)
    Total count of all the resources.

  - `meta.sort` (string)
    The field that the list is sorted by.

  - `meta.order` (string)
    The ordering applied to the list.
* ASC — Ascending order.
* DESC — Descending order.
    Enum: "ASC", "DESC"

  - `data` (array, required)
    The fee collections in this page of results.

  - `data.id` (string, required)
    The unique identifier of the fee collection, as a UUID.

  - `data.created_at` (string, required)
    Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `data.updated_at` (string, required)
    Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `data.account_id` (string, required)
    Universally Unique Identifier (UUID) of the account.

  - `data.account_group_id` (string, required)
    Universally Unique Identifier (UUID) of the account group.

  - `data.type` (string, required)
    Type of the fee collection.
* SERVICE_FEE — Service fee intake in a pre-defined cadence, for example monthly.
* SERVICE_FEE_LIQUIDATION — Service fee intake resulting from a portfolio liquidation.
    Enum: "SERVICE_FEE", "SERVICE_FEE_LIQUIDATION"

  - `data.collection_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.processed_amount` (object, required)
    How much of the fee amount has been covered so far, split by the source of the cash, together with any amount still outstanding.

  - `data.processed_amount.cash_balance` (string)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.processed_amount.sell_to_cover` (string)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.processed_amount.total_residual_amount` (string)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.sell_to_cover_orders` (array)
    The sell-to-cover orders placed to raise cash for this fee collection.

  - `data.sell_to_cover_orders.id` (string, required)
    The unique identifier of the sell-to-cover order placed to raise cash for a fee amount, as a UUID.

  - `data.sell_to_cover_orders.residual_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* EUR — Euro.
* GBP — Pound Sterling.
    Enum: "EUR", "GBP"

  - `data.status` (string, required)
    Status of the fee collection.
* PROCESSING — The fee collection is in progress.
* FINALISED — The fees have been collected from the account and the funds transferred to the client.
* CANCELLED — The fee collection was cancelled.
    Enum: "PROCESSING", "FINALISED", "CANCELLED"

  - `data.period_start` (string, required)
    The start date of the fee collection period, as a [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) full date in `YYYY-MM-DD` format.

  - `data.period_end` (string, required)
    The end date of the fee collection period, as a [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) full date in `YYYY-MM-DD` format.

  - `data.calculation_breakdown` (array)
    Breakdown of the fee collection by fee model and subperiod. Populated only for fee collections created from daily fee model calculations.

  - `data.calculation_breakdown.fee_model_id` (string, required)
    The unique identifier of the fee model, as a UUID. Upvest provides this value when a fee model is set up.

  - `data.calculation_breakdown.subperiod_start` (string, required)
    The start date of the fee subperiod, as a [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) full date in `YYYY-MM-DD` format.

  - `data.calculation_breakdown.subperiod_end` (string, required)
    The end date of the fee subperiod, as a [RFC 3339, section 5.6](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) full date in `YYYY-MM-DD` format.

  - `data.calculation_breakdown.subtotal_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.calculation_breakdown.components` (array, required)
    Individual fee components contributing to the subtotal.

  - `data.calculation_breakdown.components.type` (string, required)
    The kind of fee this component represents.
* TRANSACTION_LUMP_SUM — Lump sum transaction fee.
* PLATFORM — Platform fee.
* SERVICE — Service fee for a client portfolio.
* VAT — Value-added tax.
    Enum: "TRANSACTION_LUMP_SUM", "PLATFORM", "SERVICE", "VAT"

  - `data.calculation_breakdown.components.amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `data.replaced_collection_id` (string)
    The unique identifier of the fee collection, as a UUID.

## Response 200 headers (application/json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 400:

  - `400` (unknown)
    Bad Request. The incoming request had a malformed parameter/object.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 400 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 401:

  - `401` (unknown)
    Unauthorized. The caller has not been authenticated.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 401 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 403:

  - `403` (unknown)
    Forbidden. The caller has been authenticated but is not allowed to take the requested action.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 403 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 406:

  - `406` (unknown)
    Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 406 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 429:

  - `429` (unknown)
    Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 429 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 500:

  - `500` (unknown)
    Internal Server Error. The service encountered an unexpected error.

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 500 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 503:

  - `503` (unknown)
    Service Unavailable. The service handling for this request cannot be reached at this time.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 503 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 504:

  - `504` (unknown)
    Gateway Timeout. The service gateway has reached its internal timeout.

## Response 504 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 504 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7