Versioning policy

The SOAMTAR API follows SemVer on the URL prefix.

Model

https://app.so-amtar.com/{vMAJOR}/...
                         v1, v2, v3

Type of change	Bump	Compatibility	Notice
Patch (1.0.x)	1.0.0 → 1.0.1	100% compatible	None
Minor (1.x.0)	1.0.x → 1.1.0	Compatible (additions only)	None
Major (x.0.0)	1.x.x → 2.0.0	Breaking	6 months

Compatibility guarantees (minor)

Within a major version (/v1):

• ✅ New endpoints can appear at any time
• ✅ Optional fields can be added to requests at any time
• ✅ Fields can be added to responses at any time
• ✅ New enum values can be added (always treat enums as open in your code)
• ❌ Existing fields are never removed
• ❌ Field names are never renamed
• ❌ Types never change (string → integer is forbidden)
• ❌ Existing error codes are never removed

Lifecycle of a major version

v1 released ──> v2 announced (T0)
                  │
                  ├─> v2 beta open   (T+3 months)
                  ├─> v2 GA          (T+6 months)
                  ├─> v1 deprecated  (T+6 months)
                  │
                  └─> v1 EOL, end of support (T+18 months)

You have 12 months between deprecation and EOL to migrate.

Announcing a major version

• Email to every merchant in production
• Detailed post in the changelog
• Migration guide (in this section) with the old/new mapping
• Old/new payload comparison tool in the dashboard
• Weekly office hours for Q&A during the beta

Version in your requests

Always hard-code /v1 (or the version you target) in your client. Never rely on an automatic redirect: we do not issue any.

// ✅ Good
const baseUrl = 'https://app.so-amtar.com/v1'

// ❌ Bad: we do not provide /latest
const baseUrl = 'https://app.so-amtar.com/latest'

Detecting a deprecation

Every response from a deprecated endpoint contains:

HTTP/1.1 200 OK
Sunset: Fri, 31 Dec 2027 23:59:59 GMT
Deprecation: true
Link: <https://app.so-amtar.com/docs/v2/migration>; rel="deprecation"

Log these headers and alert your team: you still have time, but start planning.

Deprecated fields (without a major bump)

A field can be deprecated within /v1 (it keeps working but will not be in /v2). It is flagged like this:

{
  "data": {
    "old_field": "value",
    "new_field": "value",
    "_deprecations": {
      "old_field": "Use new_field instead. Removed in /v2."
    }
  }
}