# Deprecation

To ensure stability and predictability for consumers, our APIs follow a clear deprecation process. When resources are scheduled for removal, we provide advance notice.

## Deprecation policy

- Advance notice: We announce deprecations at least **12 months** before removal (unless required sooner for security, compliance, or stability reasons).
- Deprecation period: During this time, the deprecated resources will continue to function as expected.
- Removal: After the deprecation period, resources will be removed at our discression and requests may fail.


## Communication channels

You will be notified of deprecations through:

- API documentation (deprecated endpoints and events will be clearly marked).
- Endpoints will return `Deprecated-Date` and `Sunset-Date` headers:


```sh
Deprecation-Date: 2024-10-01
Sunset-Date: 2025-10-01
```

- Webhook events will include deprecation metadata:


```json
{
  "deprecated": true,
  "deprecationfrom": "2025-11-01T00:00:00Z",
  "deprecationsunset": "2026-11-01T00:00:00Z"
}
```

## Best practices

To ensure your integrations remain stable:

- Monitor deprecation headers (`Deprecation-Date`, `Sunset-Date`) in API responses.
- Monitor event payload metadata (`deprecated`, `deprecationfrom`, `deprecationsunset`).
- Plan migrations early — Begin transitioning away from deprecated resources or event types as soon as they are announced.
- Avoid using deprecated functionality in new integrations.