---
title: "Retrieve applicable surcharges for a registration period"
method: POST
path: "/public/surcharges/v1/retrieve-surcharges"
tags: ["Surcharges"]
---

# Retrieve applicable surcharges for a registration period

`POST /public/surcharges/v1/retrieve-surcharges`

## Request

- Base URL: `https://api.maqqie.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maqqie.app/public/surcharges/v1/retrieve-surcharges`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://maqqie.app/auth/realms/maqqie/protocol/openid-connect/token`
- TypeScript: <https://skmtc.dev/maqqie/apis/maqqie-public-api/docs/public/surcharges/v1/retrieve-surcharges/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint calculates and returns applicable surcharges, based on the provided CAO number, function type, and registration periods.

Note: In case a CLA has set both a fixed amount and a factor for a surcharge and stacking rule higher, this endpoint will arbitrarily choose the factor-based surcharge.

## Request body

- SurchargeRequestV1
  - `caoNumber` integer, required: The CAO number relevant to the registration.
  - `companyId` string, uuid: The UUID of the company of the registration.
  - `functionType` string: The function type relevant to the registration.
  - `functionSubType` string: The function sub type relevant to the registration.
  - `registration` RegistrationPeriodV1, required: Registration period to calculate surcharges for.
    - `startDateTime` string, date-time, required: Start date and time of the registration period in UTC. Must be before endDateTime.
    - `endDateTime` string, date-time, required: End date and time of the registration period in UTC. Must be after startDateTime.

## Response `200`

Successfully retrieved applicable surcharges

- SurchargeResponseV1
  - `surcharges` SurchargeDetailV1[]: Array of applicable surcharges for the registration period.
    - `type` 'IRREGULARITY_ALLOWANCE' | 'OVERTIME' | 'PUBLIC_HOLIDAY', required: Type of surcharge applied.
    - `surchargeFactor` number, float: Factor to be applied as a surcharge (percentage-based).
    - `fixedSurchargeAmountPerHour` number: Fixed amount per hour to be applied as a surcharge (euro amount).
    - `startDateTime` string, date-time, required: Start date and time for the surcharge period in UTC.
    - `endDateTime` string, date-time, required: End date and time for the surcharge period in UTC.

## Other responses

- `400`: The request could not be processed. This could be due to a number of reasons: * The request does not have all required data. * Data in the request is invalid. * Data in the request is inconsistent. * The operation is not allowed given the current state of the data.
- `401`: The request did not contain valid credentials identifying the caller.
- `403`: The data that the request referred to is inaccessible to the caller.

## Changes

- **2026-09-29** `f9510f3f4b22`: 5 breaking, 4 info
  - added the new required request property `caoNumber`
  - added the new required request property `registration`
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - …5 more
- **2026-09-29** `3352b56bb8fe`: 3 breaking, 6 warning, 4 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the request property `caoNumber`
  - …9 more
- **2026-09-16** `ccf9834e5006`: 5 breaking, 4 info
  - added the new required request property `caoNumber`
  - added the new required request property `registration`
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - …5 more
- **2026-09-15** `8085d4c1ab80`: 3 breaking, 6 warning, 4 info
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - the response's body type changed from `string` to no type for status `400`
  - removed the request property `caoNumber`
  - …9 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/surcharges/v1/retrieve-surcharges/post.md)

---

[API](https://skmtc.dev/maqqie/apis/maqqie-public-api.md) - [All operations](https://skmtc.dev/maqqie/apis/maqqie-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maqqie/apis/maqqie-public-api/revisions/13ed331da2b2?raw)