# 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](https://manual.firstresonance.io/features/purchasing/purchase-orders/po-lines-editability-changes) for examples and updated API payloads.

***

### **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.