# API Change Policy

## 🔒 API Stability & Change Policy

At First Resonance, we know that many of our customers build critical integrations on top of our API. Because of this, we take **API stability seriously**. Our philosophy is simple:

* **Avoid breaking changes:** Our first priority is to keep existing APIs stable.
* **Change only to improve:** Any changes we make are designed to **simplify**, **clarify**, or bring **core functionality** to the application.

***

### **How We Handle Changes**

#### **1. Non-Breaking Changes (Preferred)**

* Adding new fields
* Expanding functionality in ways that do not affect existing calls

These changes require **no customer action** and are documented in our release notes.

#### **2. Breaking Changes (Rare & Announced)**

Sometimes, to improve consistency or remove ambiguity, a breaking change is unavoidable.

When this happens, we will:

* **Announce changes in advance** (14 days before production rollout).
* **Explain why** the change is necessary and what value it brings.
* **Schedule** deprecation after monitoring API usage.
* **Provide** before/after API examples.
* **Communicate broadly** through in-app notices, release notes, and updated documentation.

***

### **What This Means for You**

* If you are building or maintaining integrations, you can rely on us to keep your workflows stable.
* When a change is required, you’ll always have **time, guidance, and support** to adjust.
* We encourage all customers to thoroughly pay attention to our **release notes and API change alerts** to stay up to date.

***

### **Example: How We Communicate Breaking Changes**

Here’s what you can expect from us:

> Breaking Change Notice – Effective July 28th \
> We are deprecating the `Approved` and `Requested` PO Line statuses. Going forward, all integrations should reference the `Purchase Order` status instead. \
> **Action Required:** Update any API calls, webhooks, or rules that use these statuses before July 28th. \
> **Why this change?** This simplifies the PO flow and avoids inconsistent status handling. \
> **What’s next?** See our migration guide \[here] for examples and updated API payloads.

Example: [PO lines editability changes](https://manual.firstresonance.io/features/purchasing/purchase-orders/po-lines-editability-changes)

***

### **Our Commitment**

* We avoid breaking changes whenever possible.
* We design changes to **make your integrations easier and more reliable**.
* We give you **advance notice and clear actions** if changes are required.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://manual.firstresonance.io/api/api-change-policy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.