> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.redpincompany.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server.

# API versioning

> Understanding how Redpin versions APIs and manages breaking changes

Redpin uses endpoint versioning to evolve our API while maintaining stability for existing integrations. This approach ensures your applications continue working without disruption while allowing you to adopt new features at your own pace.

## Versioning approach

When backwards-incompatible changes are necessary, we create new endpoint versions with updated paths. For example, a breaking change to the payments endpoint results in `/v2/payments` rather than modifying `/v1/payments`.

This approach provides several benefits:

* **Stability**: Existing integrations continue functioning without modification
* **Flexibility**: Migrate to new versions on your timeline
* **Clarity**: Version numbers in the path make it explicit which API version you're using
* **Coexistence**: Use different versions for different endpoints based on your needs

## Breaking changes

We consider the following changes to be backwards-incompatible and will require a new endpoint version:

#### Removing or renaming fields

Removing existing fields from responses or renaming them to different names. This breaks clients that depend on the original field names.

#### Changing field data types

Modifying the data type of existing fields, such as changing a string to an integer or a number to a string. This can cause parsing errors in client applications.

#### Making parameters required

Changing previously optional request parameters to required. This breaks existing API calls that don't include these parameters.

#### Modifying request/response structure

Changing the structure of request or response bodies in ways that affect how data is organized or accessed.

#### Changing authentication requirements

Modifying authentication or authorization requirements, including changes to required scopes or permissions.

#### Modifying error codes

Removing or changing the meaning of existing error codes that clients may be handling programmatically.

#### Altering endpoint behavior

Changing the behavior of existing endpoints in ways that could affect client logic or business processes.

When we introduce breaking changes, we create a new endpoint version and provide:

* Migration documentation in our [Changelog](/changelog)
* Updated examples in the API Reference
* Guidance on adapting your integration

> **Info**
>
> Previous endpoint versions remain available and supported, giving you time to plan and execute migration.

## Backwards-compatible changes

Redpin considers the following changes to be backwards-compatible and applies them across all endpoint versions:

#### New endpoints

Adding new API endpoints or resources that don't affect existing functionality.

#### Optional parameters

Adding new optional request parameters to existing endpoints.

#### New response properties

Adding new properties to existing API responses. Clients should ignore unknown fields.

#### Property ordering

Changing the order of properties in API responses. Clients should not depend on field order.

#### Enum values

Adding new values to existing enums where appropriate and documented.

#### Optional headers

Introducing new optional request or response headers.

We regularly introduce backwards-compatible changes to support new product features. These changes are applied across all endpoint versions, meaning you can access new functionality without upgrading to a newer version.

> **Note**
>
> Your integration should be designed to handle backwards-compatible changes gracefully, such as ignoring unexpected response fields and not depending on field ordering.

## Version migration

When a new endpoint version is released:

#### Review the changelog

Check the [Changelog](/changelog) for details about what changed and why a new version was necessary.

#### Test in sandbox

Use the sandbox environment to test your integration with the new endpoint version before migrating production traffic.

#### Update your integration

Modify your application code to work with the new endpoint version, following the migration guidance provided.

#### Deploy gradually

Consider a phased rollout, migrating a portion of traffic initially to verify everything works as expected.

#### Monitor and validate

After migration, monitor your integration for any unexpected behavior and validate that all workflows function correctly.

## Best practices

**Design for forwards compatibility**

Structure your integration to handle new fields and enum values gracefully:

* Ignore unknown fields in API responses
* Don't rely on specific field ordering in responses
* Handle new enum values appropriately (e.g., with a default case)
* Validate response structures defensively

**Stay informed**

Subscribe to our changelog notifications to stay informed about new endpoint versions and upcoming changes. Major version releases are announced in advance with detailed migration guides.

**Plan migrations proactively**

While we maintain support for previous endpoint versions, plan to migrate to newer versions within a reasonable timeframe to:

* Access new features and capabilities
* Benefit from performance improvements
* Receive the latest security updates
* Ensure long-term supportability

> **Tip**
>
> Contact the Partner Integrations Team if you need assistance with version migration or have questions about specific changes.