# Versioning & changelog

What can change, and how much warning you get.

## API surface

The App API is versioned in the path: `https://api.southbill.com/v1/app`. A `v1` route never changes meaning; incompatible redesigns ship as `v2` and both run in parallel during the migration window.

## Additive by default

These can ship any day without notice — build for them:

- new fields on existing objects
- new enum values (`status`, `reason`, `failure_code`)
- new event types
- new endpoints and new optional query parameters

Rules that keep you safe: ignore unknown fields, never fail on an unknown enum value, ignore unknown event types, never depend on field order or on the exact shape of an id.

## Breaking changes

Removing a field, renaming one, changing a type, tightening a limit or retiring an event type are breaking. They are announced at least **90 days** ahead by email to the developer contact, in the dashboard changelog and with a deprecation note in the affected docs page. During the window, both behaviours are available where technically possible.

## App versions

Your own app is versioned separately: each submission freezes a listing plus a scope set. Published versions stay attached to the installations that consented to them, so adding a scope never silently widens an existing install — the merchant re-consents first.

## Deprecation signals

Deprecated endpoints answer with a header for the whole notice period:

```text
Southbill-Deprecation: true
Southbill-Sunset: 2026-12-01
```

Alert on that header in your logs — it is the earliest automated warning you get.

## Changelog

The dashboard changelog lists every platform change with a date, a type (added / changed / deprecated / removed) and a migration note where one is needed. Subscribe to it from the developer dashboard.