FX

Endpointhttps://api.kontorion.eu/v1

Foreign-exchange reference data: ECB snapshots, sync status, and rate overrides.

List FX rate overrides

GET

https://api.kontorion.eu/v1

/fx/overrides

Returns paginated FX overrides for the active organization.

List FX rate overrides › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List FX rate overrides › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List FX rate overrides › Responses

array | null · required

object · required

GET/fx/overrides

curl --request GET \
  --url https://api.kontorion.eu/v1/fx/overrides

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "deleted_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "rate": "rate",
      "reason": "reason",
      "snapshot_date": "2026-07-01",
      "source_currency": "source_currency",
      "target_currency": "target_currency",
      "updated_at": "2024-08-25T15:00:00Z",
      "valid_from": "2024-08-25T15:00:00Z",
      "valid_to": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create an FX rate override

POST

https://api.kontorion.eu/v1

/fx/overrides

Creates an override that takes precedence over policy-selected ECB rates for a currency pair inside an activation window. Two mutually exclusive modes: rate (a manual conversion rate, 1 source = rate target) or snapshot_date (pin the pair to the ECB snapshot of that day). Both currencies must be on the workspace allowlist; overlapping windows for the same pair are rejected with 409.

Create an FX rate override › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create an FX rate override › Request Body

rate

string

Manual conversion rate (decimal string, 1 source = rate target). Mutually exclusive with snapshot_date.

reason

string · maxLength: 2000

Optional free-text note explaining the override.

snapshot_date

string · date

Pin the pair to the ECB snapshot of this calendar day. Mutually exclusive with rate.

Example: 2026-07-01

source_currency

string

ISO 4217 currency being converted from (normalized to uppercase).

target_currency

string

ISO 4217 currency being converted to; must differ from source_currency.

valid_from

string · date-time

Instant the override begins applying; null means now.

valid_to

string · date-time

Instant the override stops applying; null means open-ended.

Create an FX rate override › Responses

Created

object · required

POST/fx/overrides

curl --request POST \
  --url https://api.kontorion.eu/v1/fx/overrides \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "source_currency": "source_currency",
  "target_currency": "target_currency",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}
'

shell

Example Request Body

{
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "source_currency": "source_currency",
  "target_currency": "target_currency",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "rate": "rate",
    "reason": "reason",
    "snapshot_date": "2026-07-01",
    "source_currency": "source_currency",
    "target_currency": "target_currency",
    "updated_at": "2024-08-25T15:00:00Z",
    "valid_from": "2024-08-25T15:00:00Z",
    "valid_to": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get an FX rate override

GET

https://api.kontorion.eu/v1

/fx/overrides/{id}

Returns a single FX override by ID.

Get an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Get an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an FX rate override › Responses

object · required

Delete an FX rate override

DELETE

https://api.kontorion.eu/v1

/fx/overrides/{id}

Soft-deletes an FX override. The policy-selected ECB rate becomes effective again for the affected window.

Delete an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Delete an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete an FX rate override › Responses

No Content

No data returned

Update an FX rate override

PATCH

https://api.kontorion.eu/v1

/fx/overrides/{id}

Patches an override. Supplying rate switches it to manual-rate mode (clearing snapshot_date) and vice versa; omitted fields are unchanged. valid_to and reason are cleared only via clear_valid_to / clear_reason - omitting them never nulls the stored value.

Update an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Update an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update an FX rate override › Request Body

clear_reason

boolean

Set true to remove the stored reason.

clear_valid_to

boolean

Set true to make the override open-ended (clears valid_to).

rate

string

Switch to manual-rate mode with this rate (clears snapshot_date).

reason

string · maxLength: 2000

New free-text note; omitted leaves it unchanged. Use clear_reason to remove it.

snapshot_date

string · date

Switch to snapshot-pin mode with this date (clears rate).

Example: 2026-07-01

valid_from

string · date-time

New activation start; omitted leaves it unchanged.

valid_to

string · date-time

New activation end; omitted leaves it unchanged. Use clear_valid_to to make it open-ended.

Update an FX rate override › Responses

object · required

PATCH/fx/overrides/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/fx/overrides/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "clear_reason": true,
  "clear_valid_to": true,
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}
'

shell

Example Request Body

{
  "clear_reason": true,
  "clear_valid_to": true,
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "rate": "rate",
    "reason": "reason",
    "snapshot_date": "2026-07-01",
    "source_currency": "source_currency",
    "target_currency": "target_currency",
    "updated_at": "2024-08-25T15:00:00Z",
    "valid_from": "2024-08-25T15:00:00Z",
    "valid_to": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List FX snapshots for a date

GET

https://api.kontorion.eu/v1

/fx/snapshots

Returns all currency-pair snapshots for the supplied date (defaults to today, UTC).

List FX snapshots for a date › query Parameters

date

string

Date in YYYY-MM-DD format (default today UTC)

List FX snapshots for a date › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List FX snapshots for a date › Responses

array | null · required

object · required

Get the latest FX snapshot for a currency pair

GET

https://api.kontorion.eu/v1

/fx/snapshots/latest

Returns the most recent FX snapshot at or before "now" for the given from→to pair. Used for ad-hoc conversion lookups.

Get the latest FX snapshot for a currency pair › query Parameters

from

string · required

Source ISO 4217 currency code

to

string · required

Target ISO 4217 currency code

Get the latest FX snapshot for a currency pair › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the latest FX snapshot for a currency pair › Responses

object · required

FX sync status

GET

https://api.kontorion.eu/v1

/fx/sync-status

Reports the most recent snapshot date and the number of distinct snapshot dates over the last year. Useful for monitoring the FX-sync job.

FX sync status › Headers

X-Workspace-Id

string

Workspace UUID or slug.

FX sync status › Responses

object · required

Currencies Tags

Kontorion Billing API

FX

Endpointhttps://api.kontorion.eu/v1

Foreign-exchange reference data: ECB snapshots, sync status, and rate overrides.

List FX rate overrides

GET

https://api.kontorion.eu/v1

/fx/overrides

Returns paginated FX overrides for the active organization.

List FX rate overrides › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List FX rate overrides › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List FX rate overrides › Responses

array | null · required

object · required

GET/fx/overrides

curl --request GET \
  --url https://api.kontorion.eu/v1/fx/overrides

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "deleted_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "rate": "rate",
      "reason": "reason",
      "snapshot_date": "2026-07-01",
      "source_currency": "source_currency",
      "target_currency": "target_currency",
      "updated_at": "2024-08-25T15:00:00Z",
      "valid_from": "2024-08-25T15:00:00Z",
      "valid_to": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create an FX rate override

POST

https://api.kontorion.eu/v1

/fx/overrides

Create an FX rate override › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create an FX rate override › Request Body

rate

string

Manual conversion rate (decimal string, 1 source = rate target). Mutually exclusive with snapshot_date.

reason

string · maxLength: 2000

Optional free-text note explaining the override.

snapshot_date

string · date

Pin the pair to the ECB snapshot of this calendar day. Mutually exclusive with rate.

Example: 2026-07-01

source_currency

string

ISO 4217 currency being converted from (normalized to uppercase).

target_currency

string

ISO 4217 currency being converted to; must differ from source_currency.

valid_from

string · date-time

Instant the override begins applying; null means now.

valid_to

string · date-time

Instant the override stops applying; null means open-ended.

Create an FX rate override › Responses

Created

object · required

POST/fx/overrides

curl --request POST \
  --url https://api.kontorion.eu/v1/fx/overrides \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "source_currency": "source_currency",
  "target_currency": "target_currency",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}
'

shell

Example Request Body

{
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "source_currency": "source_currency",
  "target_currency": "target_currency",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "rate": "rate",
    "reason": "reason",
    "snapshot_date": "2026-07-01",
    "source_currency": "source_currency",
    "target_currency": "target_currency",
    "updated_at": "2024-08-25T15:00:00Z",
    "valid_from": "2024-08-25T15:00:00Z",
    "valid_to": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get an FX rate override

GET

https://api.kontorion.eu/v1

/fx/overrides/{id}

Returns a single FX override by ID.

Get an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Get an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an FX rate override › Responses

object · required

Delete an FX rate override

DELETE

https://api.kontorion.eu/v1

/fx/overrides/{id}

Soft-deletes an FX override. The policy-selected ECB rate becomes effective again for the affected window.

Delete an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Delete an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete an FX rate override › Responses

No Content

No data returned

Update an FX rate override

PATCH

https://api.kontorion.eu/v1

/fx/overrides/{id}

Update an FX rate override › path Parameters

id

string · uuid · required

Override ID (UUID)

Update an FX rate override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update an FX rate override › Request Body

clear_reason

boolean

Set true to remove the stored reason.

clear_valid_to

boolean

Set true to make the override open-ended (clears valid_to).

rate

string

Switch to manual-rate mode with this rate (clears snapshot_date).

reason

string · maxLength: 2000

New free-text note; omitted leaves it unchanged. Use clear_reason to remove it.

snapshot_date

string · date

Switch to snapshot-pin mode with this date (clears rate).

Example: 2026-07-01

valid_from

string · date-time

New activation start; omitted leaves it unchanged.

valid_to

string · date-time

New activation end; omitted leaves it unchanged. Use clear_valid_to to make it open-ended.

Update an FX rate override › Responses

object · required

PATCH/fx/overrides/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/fx/overrides/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "clear_reason": true,
  "clear_valid_to": true,
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}
'

shell

Example Request Body

{
  "clear_reason": true,
  "clear_valid_to": true,
  "rate": "rate",
  "reason": "reason",
  "snapshot_date": "2026-07-01",
  "valid_from": "2024-08-25T15:00:00Z",
  "valid_to": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "rate": "rate",
    "reason": "reason",
    "snapshot_date": "2026-07-01",
    "source_currency": "source_currency",
    "target_currency": "target_currency",
    "updated_at": "2024-08-25T15:00:00Z",
    "valid_from": "2024-08-25T15:00:00Z",
    "valid_to": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List FX snapshots for a date

GET

https://api.kontorion.eu/v1

/fx/snapshots

Returns all currency-pair snapshots for the supplied date (defaults to today, UTC).

List FX snapshots for a date › query Parameters

date

string

Date in YYYY-MM-DD format (default today UTC)

List FX snapshots for a date › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List FX snapshots for a date › Responses

array | null · required

object · required

Get the latest FX snapshot for a currency pair

GET

https://api.kontorion.eu/v1

/fx/snapshots/latest

Returns the most recent FX snapshot at or before "now" for the given from→to pair. Used for ad-hoc conversion lookups.

Get the latest FX snapshot for a currency pair › query Parameters

from

string · required

Source ISO 4217 currency code

to

string · required

Target ISO 4217 currency code

Get the latest FX snapshot for a currency pair › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the latest FX snapshot for a currency pair › Responses

object · required

FX sync status

GET

https://api.kontorion.eu/v1

/fx/sync-status

Reports the most recent snapshot date and the number of distinct snapshot dates over the last year. Useful for monitoring the FX-sync job.

FX sync status › Headers

X-Workspace-Id

string

Workspace UUID or slug.

FX sync status › Responses

object · required

Currencies Tags