API Change Management

In order to continue adding functionality, we regularly make improvements and changes to our API. The majority of changes are backwards compatible and should not affect your applications. When we need to release a breaking change, we will do so in a new API version that you can manually upgrade to. All changes will be detailed in the Changelog.

Backwards Compatible Changes

We consider the following types of changes to be backwards compatible. You should ensure your code is robust enough to gracefully handle the following changes:

• Adding new API resources.
• Adding new optional request parameters to existing API methods, using sensible defaults if not present in requests.
• Adding new fields to existing API responses.
• Changing the order of fields in existing API responses.
• Changing the length or format of opaque strings, such as object IDs, error messages, and human-readable strings.
• Adding new values to an existing enum.

Versioned Changes

When we make backwards-incompatible changes to the API we will release a new dated version, e.g. 2023-04-18. You can toggle between versions in the top-left corner of our documentation. You must send a Pinwheel-Version header with each request to specify which version that request should be using. To upgrade your API version, use the relevant version date for the Pinwheel-Version header of your request. See Version Headers on the API page for more information.

Sunsetting Versions

Pinwheel will occasionally sunset old API versions, which means they will no longer be available for use. Before we sunset a version, we will mark it as deprecated no fewer than six months before it is removed from our system. Plans to deprecate or sunset a version will be communicated to you by our customer success team. They will also be detailed in the Changelog.

Making a request to a sunsetted version will result in a 400 Bad Request error.

Webhook Versions

We will also release a new dated version when we make backwards-incompatible changes to our webhook events. You can access webhook event docs for each API version via the dropdown in the top bar (e.g., "v2022-03-02"). For more information on creating webhooks with a specified version, see the Webhooks guide.

Terminology

Sunsetted: Discontinued and no longer available for usage.

Deprecated: Functional, but usage is discouraged. It is scheduled to be sunsetted.

Please contact [email protected] for access to our Developer Dashboard.