Skip to main content

Versioning

CAFE24 API is managed using date-based versions (yyyy-mm-dd). A new date-based version is released whenever a backward-incompatible change (Breaking Change) is introduced, and you can explicitly specify which version to use when calling the API.

📌 Version Format​

Version yyyy-mm-dd

Examples: 2021-03-01, 2024-09-01

Whenever a backward-incompatible change is introduced, a new version is released with the date of that release.

🔧 How to Specify a Version​

You can specify the version to use by sending the X-Cafe24-Api-Version custom header with each request.

curl -X GET \
  'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Cafe24-Api-Version: yyyy-mm-dd'

Behavior When the Header Is Omitted​

When the X-Cafe24-Api-Version header is not specified, the request behaves according to the app version configured under Developer Center > Development Info.

⚙️ App Version Configuration Path​

You can review and change the app version directly in the Developer Center.

Developer Center (login) > Apps > Development Info > Auth Info > Version Management
StepLocation
1Log in to the Developer Center
2Open the Apps menu
3Select the Development Info of the target app
4Change the version under Auth Info > Version Management

⏳ Version Expiration Policy​

ItemPolicy
LifetimeUp to 1 year from the release date of the latest version
Behavior after expirationAutomatically replaced with the oldest non-expired version

⚠️ When a version you were using expires, behavior may change. When a new version is released, review compatibility and explicitly upgrade.

🌐 Scope of Application​

The X-Cafe24-Api-Version header applies uniformly to the following APIs:

  • Admin API — REST API for administrators
  • Front API — REST API for the storefront
  • Cafe24 Analytics API — Analytics API

All three APIs share the same date-based versioning scheme and the same 1-year expiration policy.

💡 Best Practices​

1. Explicitly Pin the Version in Production​

# ✅ Recommended: pin the version to guarantee predictable behavior
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'X-Cafe24-Api-Version: 2024-09-01'

When you pin the version explicitly, your calls are not affected by changes to the app version setting in the Developer Center.

2. Review Compatibility When a New Version Is Released​

  • When a new date-based version is released, review the breaking changes.
  • Validate the new version in a staging environment before promoting it to production.

3. Monitor Versions Near Expiration​

  • When the version you use approaches the 1-year expiration, upgrade ahead of time.
  • Expired versions are automatically replaced with another version, which may cause unintended behavior.

📚 References​