API versioning

To adapt to evolving business demands, SHOPLINE regularly releases new API versions. This ensures you can build feature-rich apps tailored to merchants' actual needs and provides a clear and predictable transition mechanism for API upgrades and deprecations.

Versioned and unversioned APIs​

Based on stability and update strategies, SHOPLINE APIs are categorized into two types: versioned and unversioned.

Versioned APIs​

Versioned APIs feature a defined lifecycle and a predictable release cadence. This applies to:

• REST Admin API
• GraphQL Admin API
• Storefront API
• Webhooks

Calling a specific API version

When calling a versioned API, you must specify the API version in the request URL:

• REST Admin API path: /admin/openapi/{version}/{endpoint}.json
• GraphQL Admin API path: /admin/graph/{version}/graphql.json
• Storefront API path: /storefront/graph/{version}/graphql.json

The following examples demonstrate request paths for version v20260901:

• REST Admin API (Get orders): /admin/openapi/v20260901/orders.json
• GraphQL Admin API: /admin/graph/v20260901/graphql.json
• Storefront API: /storefront/graph/v20260901/graphql.json

To switch API versions, simply replace the version string in the request URL.

Unversioned APIs​

Unversioned APIs do not have fixed version numbers and may change at any time. This applies to:

• Ajax API
• Sline

Release types​

Typically, SHOPLINE releases a new API version every three months. These releases are categorized into three types: stable, release candidate, and unstable.

Stable​

• You can safely use stable API versions without worrying about breaking changes.
• Once a version becomes stable, it typically remains active for 12 months.
• Two consecutive stable versions overlap for 9 months. This means you have a 9-month window to update and migrate whenever a new stable version introduces changes that affect your app.

Release candidate​

• A release candidate serves as a preview of the next stable release, containing all changes planned for that version.
• Typically, when a version becomes stable, the next version becomes a release candidate. For example, when v20260901 transitions to a stable version, v20261201 is published as a release candidate.
• A release candidate includes all backward-compatible and breaking changes, allowing you to test and adapt your app early. However, using a release candidate in production is not recommended.

Unstable​

• Unstable versions contain API endpoints and updates that are still under active development and iteration, and may introduce both backward-compatible and breaking changes at any time.
• A feature added to an unstable version may still be removed.
• You can use unstable versions to test new API endpoints and functionality early, but using them in production is not recommended.

Deprecation​

If certain SHOPLINE API functionality is no longer applicable, poses security risks, or becomes obsolete, SHOPLINE may deprecate it. Affected endpoints or resources move through three retirement stages:

1. Marked as deprecated: The specific endpoints or resources are first marked as deprecated in the current version. While their functionality remains fully operational, you are strongly encouraged to migrate as soon as possible.
2. Officially removed: Next, the endpoints or resources are officially removed in a specific new version. If you request a removed endpoint or resource using this version, the system will return an HTTP 405 error. However, the functionality remains available in older versions that have not yet expired.
3. Fully retired: According to the SHOPLINE API version management plan, the functionality becomes completely unavailable only when the final legacy version containing those endpoints or resources is officially shut down.

Release schedule​

The lifecycle milestones for SHOPLINE API versions are outlined below.