API versioning guide​

To adapt to constantly evolving business scenarios, SHOPLINE regularly updates OpenAPI versions to ensure that developers can build app capabilities that are closely aligned with merchants' actual needs, while providing predictable paths for feature upgrades and deprecation for developers.

To stay abreast of upcoming API changes, please review all messages and emails sent via the SHOPLINE Developer Center, and ensure that your developer contact information is kept up-to-date.

Versioned and unversioned APIs​

Versioned

• Admin REST API
• Admin GraphQL API
• Storefront API
• Webhook

Unversioned

• Ajax API
• Handlebars

Call API version​

Please specify the API version in the request URL when calling SHOPLINE API:
REST Admin API URL： /admin/openapi/{version}/{endpoint}.json
Storefront API URL：/storefront/graph/{version}/graphql.json

For example, when requesting the v20230301 version of the API, you should make the request like this:
REST Admin API URL： /admin/openapi/v20230301/order.json
Storefront API URL：/storefront/graph/v20230301/graphql.json

You can specify which version to use by replacing the version name in the URL when an API is supported in multiple versions.

Versioning explanation​

SHOPLINE OpenAPI versions are iterated and upgraded approximately every three months.

There are three version types:

1.Stable​

• Stable versions allow you to safely call APIs without worrying about changes to the interface.
• Usually, we will provide service for a stable version for 12 months after it becomes stable. This means there will be a 9 month overlap period between two consecutive versions.
• When a new stable version introduces changes that affect your app, you will have 9 months to migrate iteratively.

2.Candidate​

• Candidate versions are preview versions of the next stable version. In this version, you can see the changes planned for the next stable version to be released.
• Generally, when the previous version becomes stable, the next version will become a candidate version.For example, when version v20230901becomes stable, v20231201 will be released as a candidate version.
• The interfaces in the candidate version will include all backward-compatible or incompatible changes. You should commence updating your app as early as possible based on the changes in this version, but it is not recommended to use the candidate version directly in a production environment.

3.Unstable​

• Unstable versions contain interfaces and updates that are still under development. We may make backward compatible or incompatible changes to them periodically.
• A feature added to an unstable version may still be removed.
• You can use unstable versions to test new APIs and features early, but it is not recommended to use them in a production environment.

Deprecation handling​

If an element of the SHOPLINE API becomes unnecessary, insecure, or obsolete, the platform may deprecate it.

• When an interface or resource is removed from the latest version, it is marked as deprecated; calling the API will fallback to the latest available stable version. When the last available version becomes obsolete, this field will no longer be usable.
• We will notify developers of significant changes in new versions via email and in-site messages when the version is released. You can also keep track of version change logs in the documentation center.

Release Schedule​