API Versioning Guide
Overview
API versioning allows us to introduce improvements to the Zepto API while ensuring existing integrations continue to operate without disruption.
As the Zepto platform evolves, new API versions may introduce:
- New features
- Improved request and response formats
- Performance improvements
- Security enhancements
- Deprecation of legacy functionality
Versioning ensures that changes do not break existing merchant integrations. Merchants can continue using their current API version or upgrade to newer versions when it suits their development roadmap.
Available Versions:
- v20250101 (alias of v1.0)
- v20260101
Why API Versioning Matters
API versioning provides several key benefits for developers and merchants integrating with Zepto.
Stability for existing integrations
Existing integrations continue to function without interruption when new API versions are released, reducing risk for live merchant implementations.
Predictable changes
Breaking changes are introduced only in new API versions, allowing developers to upgrade on their own timeline.
Access to new features
Merchants can upgrade to newer versions to access additional capabilities, improved endpoints, and enhanced functionality.
Better documentation
Each API version includes its own documentation so developers can clearly see the correct request formats, parameters, and responses.
How to Find Version-Specific Documentation
When browsing the documentation you will notice a version selector in the developer portal.
By default, the developer portal will display guides and API references for the latest available version.
Using the version selector you can:
- Choose the API version you are currently integrating with.
- View guides and API reference documentation specific to that version.
- Access request examples, schemas, and responses relevant to the selected version.
All documentation pages, API endpoints, and code examples will automatically update based on the version selected in the portal.
This makes it easy to review the differences between versions and safely upgrade your integration when needed.
What this means for our merchants
Merchants Already Live with Zepto
If your integration is already live, no action is required.
Your existing integration will continue to function exactly as it does today. Introducing API versioning does not change or interrupt any currently active integrations.
API calls are defaulted to 20250101 version which is an alias of v1.0 and that there is no need to pass the version header.
Merchants can continue using their existing API version.
However, merchants may choose to upgrade to a newer API version to access:
- New functionality
- Improved API design
- Additional features
If you notice that you are viewing guides or API references for a newer version, you can switch back to the version your current integration uses from the version selector dropdown in the top navigation menu.
Merchants Currently Integrating in Sandbox
If you are currently testing or integrating in the Zepto sandbox environment, the introduction of API versioning will not impact your current integration work.
You can continue integrating with the API version you started with and proceed to production as planned.
Your testing and go-live timeline remain unchanged. You may also choose to migrate to the latest version during development if that better suits your rollout plan.
If you notice that you are viewing guides or API references for a newer version, you can switch back to the version your current integration uses from the version selector dropdown in the top navigation menu.
New Integration with Zepto
For new integrations, the developer portal will generally display guides and API references for the latest available version by default.
This allows you to start building against the most current documentation, examples, and API specifications available in the portal.
To target a specific API version, include the version in the request header for each API call.
Example request header:
FAQ
How do I request and integrate with a specific version?
To target a specific API version, include the version in the request header for each API call.
Example request header:
How do I find documentation for a specific API version?
Use the version selector in the developer portal.
Once you select a version, the guides, API references, and examples shown in the portal will update to match that version.
Will API versioning break my existing integration?
No.
Existing integrations will continue to operate as they do today. Versioning ensures that breaking changes are introduced in newer API versions rather than disrupting merchants already live on an earlier version.
Do I need to upgrade to the latest version?
No.
Upgrading is optional. Merchants can move to a newer API version when they are ready or when they want to access the latest features and improvements.
What happens if I am currently integrating in sandbox?
If you are currently testing or integrating in sandbox, your work will not be affected.
You can continue using the API version you started with and proceed to go-live as planned.
Upgrading to a New API Version
When a new API version is released, merchants who wish to upgrade should:
- Review the version-specific documentation in the developer portal.
- Check for any changes in request or response structures.
- Update their integration in a sandbox environment.
- Deploy the upgrade to production once testing is complete.