API changelog

What changed,
and when.

Every change to the API and platform lands here, with a date. Breaking changes only ever ship as a new version — what you build on today will not shift under you without warning.

See the API → Platform status
Base path /api/v1 · current version v1
v1Current v2Planned
Release log

Newest first.

Each entry is tagged Added, Changed or Deprecated. The entries below show the format — real releases will land here as the API evolves.

2026-06-24 v1 Added Example

Balances endpoint with per-currency detail

  • GET /balances now returns available and held amounts per currency, as integer minor units.
  • Each balance carries a currency field and a heldMinor field for money still on its way to you.
  • Pure addition — existing integrations keep working untouched.
2026-05-12 v1 Changed Example

Webhook signatures verified on the raw body

  • Clarified: verify the X-Freeconomy-Signature header against the raw request body, before any JSON parsing.
  • Added signature.timestamp against replays — reject deliveries older than the tolerance window.
  • No payload shape changed: existing handlers keep working.
2026-04-03 v1 Deprecated Example

Legacy float amount field on payments

  • The float amount field is retiring in favour of the integer amountMinor. Money is counted in integer minor units end to end.
  • The old field keeps working within v1 and returns alongside amountMinor; new integrations should read amountMinor only.
  • It will not be removed before the next major version — flagged here well in advance.

Dates and details above are worked examples of the format, not a record of shipped releases.

Our promise

Nothing breaks without warning.

A breaking change never lands inside a stable version. It ships as a new version in the path, with notice in advance and time to move at your own pace.

The version lives in the path

Every request targets an explicit version — /api/v1. A breaking change becomes /api/v2; the old version keeps serving traffic until an announced end date.

Additions only within a version

Inside a version we only add fields, endpoints and event types — never remove or rename. Ignore unknown fields and unknown events, and nothing ever breaks your handler.

Notice in advance

Deprecations are posted here and flagged in the dashboard before anything changes. A field or endpoint is marked deprecated long before it disappears.

Time to migrate

When a new version ships, both run in parallel — move at your own pace, with a sandbox for each, before you switch live traffic.

Build without looking over your shoulder.

Pin to /api/v1 and ship. Connected teams hear about every change in the dashboard and by email — before anything moves.

Get sandbox keys → Platform status
Migration questions? security@freeconomy.shop reaches the platform team

Services are provided to onboarded clients after a KYC/KYB check, through licensed partners; availability varies by jurisdiction. This page is informational and not an offer of financial services.