> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.shipbob.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_mcp/server.

# Versioning Policy

This guide outlines our approach to **versioning** and **deprecation**, helping developers\
build stable and future-proof integrations.

### **API Versioning**

Starting **July 2025**, ShipBob is adopting a **date-based versioning scheme**\
using the format:

> YYYY-MM

### **Current Version**

* **Latest Version**: `2026-07`
* **Base URL Format**: `https://api.shipbob.com/2026-07/`

### **Release Schedule**

* A new version will be released **every 6 months** (January and July).
* Each version will be **supported for 24 months** from its release date.

### **Version Lifecycle**

| **Version** | **Release Date** | **End of Support** | **Upgrade Guide**                                          |
| :---------- | :--------------- | :----------------- | :--------------------------------------------------------- |
| 2025-07     | Jul 31, 2025     | Jul 31, 2027       | [Upgrade to 2025-07](/versioning/2025-07) (from `2.0`)     |
| 2026-01     | Jan 31, 2026     | Jan 31, 2028       | [Upgrade to 2026-01](/versioning/2026-01) (from `2025-07`) |
| 2026-07     | Jul 31, 2026     | Jul 31, 2028       | [Upgrade to 2026-07](/versioning/2026-07) (from `2026-01`) |

### **Legacy Version Deprecation**

ShipBob previously used semantic versioning (`1.0` and`2.0`).\
These versions are now **deprecated**.

### **Deprecation Timeline**

| **Legacy Version** | **Status** | **End of Support** |
| :----------------- | :--------- | :----------------- |
| 1.0 / 2.0          | Deprecated | Jul 31, 2026       |

After the end-of-support date, legacy versions will no longer be accessible.

### **1.0 Deprecation Rollout**

To give integrations time to migrate, access to API `1.0` is phased out gradually rather than cut off all at once. Starting the week after end-of-support, an increasing share of `1.0` requests is blocked (per merchant account) until `1.0` is fully retired:

| **Period**            | **% of `1.0` Requests Blocked**             |
| :-------------------- | :------------------------------------------ |
| Aug 1 – Aug 7, 2026   | 0% (grace period, no blocking)              |
| Aug 8 – Aug 14, 2026  | 25%                                         |
| Aug 15 – Aug 21, 2026 | 50%                                         |
| Aug 22 – Aug 28, 2026 | 75%                                         |
| Aug 29, 2026 onward   | 100% — all `1.0` requests return `410 Gone` |

This blocking is scoped to `1.0` traffic only; dated versions (e.g. `2026-07`) are unaffected. See [Errors](/errors) for details on the `410` response returned once a request is blocked.

### **Experimental Features**

ShipBob may release **experimental endpoints** to gather feedback and test new functionality.

* Experimental endpoints are prefixed with `/experimental`.
* These endpoints are **subject to change or removal without notice**.

### **Migration Assistance**

For migration assistance or questions:

* **Upgrade guides**: [Upgrade to 2025-07](/versioning/2025-07), [Upgrade to 2026-01](/versioning/2026-01), [Upgrade to 2026-07](/versioning/2026-07)\
  Each guide lists the changes for a single version step. Apply them in order if you are more than one version behind.
* **Changelog**: [View API Changelog](/release-notes)
* **Email**: [<u>support@shipbob.com</u>](mailto:support@shipbob.com)