Versioning

The dated path segment pins each request to an API version.

https://api.pengine.io/store-api/2026-08/stores/:storeId/products

The API does not use a version header, account setting, or moving default. Multiple versions can be available at once, and each version preserves its original contract.

What can change inside a version

A version can receive backward-compatible additions at any time, including:

• A new field on a response.
• A new optional field on a request body.
• A new value in an existing set, such as an order status or a decoration method.
• A whole new endpoint.
• Different wording in an error message.
• Bug fixes that align behavior with the documentation.

What requires a new version

Anything that could break a working integration:

• Removing or renaming a field, or changing its type.
• Removing an endpoint, or changing what one already does.
• Tightening validation so a request that used to work no longer does.
• Changing a status code, a default, or the order rows come back in.
• Changing the meaning of an existing value.

These changes require a new dated version and path. Existing versions keep their original behavior.

Support policy

• A new version appears only when a breaking change makes one necessary. We aim for at most one a year.
• When one appears, the version before it keeps serving for at least 12 months.
• We give at least 3 months notice before a version stops serving, by email to the store owner and in the changelog.
• Once a version is retired, its paths return 404.
• Documentation for a retired version stays available through the version picker.

Moving to a new version

First, read the changelog for the new version. It lists every breaking change.

Then update the version segment in your base URL and test your integration. Both versions accept the same key, so you can test the new version in staging before updating production.

If you send a version that does not exist, or one that has been retired, you get a plain 404:

{
  "message": "Cannot GET /store-api/2025-01/stores/ovy3u54frpsl4sd963aja0h1/products",
  "error": "Not Found",
  "statusCode": 404
}