> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craveup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Guide

> Migration instructions for breaking changes between SDK and API versions.

This page documents breaking changes and migration steps when upgrading the Crave Storefront SDK or API.

***

## SDK v1.x (Current)

The current stable release. No breaking changes since initial release.

### Installation

```bash theme={null}
pnpm add @craveup/storefront-sdk@latest
```

### Changelog highlights

| Version | Change                                                              |
| ------- | ------------------------------------------------------------------- |
| `1.3.0` | Added `storefront.locations.getDistance()` for delivery zone checks |
| `1.2.0` | Added `storefront.analyticsEvents` namespace for funnel tracking    |
| `1.1.0` | Added `storefront.cart.getRecommendations()` for upsell suggestions |
| `1.0.0` | Initial release — 8 namespaces, 30+ methods                         |

***

## API versioning

The API is versioned via the URL path:

```
https://api.craveup.com/api/v1/...
```

When a new API version is released, the previous version will remain available for at least **12 months** with security patches. New features are only added to the latest version.

### Checking your API version

The response includes a `X-API-Version` header:

```
X-API-Version: 2025-01-01
```

***

## General upgrade checklist

When upgrading the SDK:

1. Read the changelog for the versions you're skipping
2. Update the package: `pnpm add @craveup/storefront-sdk@latest`
3. Run `pnpm typecheck` — TypeScript will catch removed or renamed methods
4. Test the full ordering flow in test mode (session → cart → checkout → payment)
5. Verify webhook handlers still work with current payload formats

***

## Future breaking changes

When breaking changes are planned, they will be:

1. Announced in the [Changelog](/changelog) at least 30 days in advance
2. Documented on this page with migration instructions
3. Released under a new API version (`v2`)
4. The old version (`v1`) will continue working for 12 months

Subscribe to the [Changelog RSS feed](/changelog) to get notified of updates.

<Snippet file="need-help.mdx" />