Field deprecation & removal policy

How we retire a field, and how much notice you get.

Fields are occasionally removed — because they are no longer used, or because they have moved to another entity. This is the process we follow so that it never surprises you.

1. Deprecation notice

Before a field is removed we:

• Mark it deprecated in the OpenAPI specification.

• Write a description saying why, and where the value lives now if it moved.

• Set a planned removal date — normally three months out, sometimes longer or shorter depending on impact.

• Mark it optional in the response schema, so a client that requires it starts failing loudly while there is still time to fix it.

2. Documentation and changelog

Every deprecation is recorded in the deprecation log and in the API changelog under the DEPRECATED tag. When the field is finally removed, the log is updated and a REMOVED entry is added.

3. Telling you about it

We notify registered integration partners and client development teams directly, with the reason and the planned removal date.

If that timeline does not work for your integration, tell us. Adjusting it is usually easier than you think, and much easier than an integration breaking in production.

4. In short

1. Mark deprecated, document why and when, make it optional.

2. Log it under DEPRECATED.

3. Notify integrators, and adjust the date if someone needs longer.

4. Remove it, and log it under REMOVED.

The specification at https://api.flowretail.com/v2/spec always reflects what is actually deployed, so a field still present there is still safe to read today.