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

# Migrate to BookHub Publisher API v2

> Update your code to use BookHub Publisher API v2’s new features.

This guide walks you through migrating your code from BookHub Publisher API v1 to v2. It covers the two breaking changes in v2: the `hitCount` field addition and the removal of title sorting. For the complete list of changes, see [Breaking changes](/reference/reference-breaking-changes). For a complete overview, see [Release notes](/reference/reference-release-notes).

## Prerequisites

Before you begin, ensure you meet the following prerequisites:

* Familiarity with BookHub Publisher API v1.
* Access to your codebase that integrates with the BookHub Publisher API.
* A valid JWT for authentication.

## Step 1: Update base URLs

Start by updating all API URLs in your code from v1 to v2. For example:

### Before (v1)

```http theme={null}
https://api.bookhub.com/api/v1/books
```

### After (v2)

```http theme={null}
https://api.bookhub.com/api/v2/books
```

## Step 2: Handle the `hitCount` field

Use the `hitCount` field on individual books to track views. Replace separate analytics API calls with this field in your existing code for retrieving book details. For details on `hitCount` data type, range, and availability, see [Get a specific book](/reference/reference-api-endpoints#get-a-specific-book).

### Before (v1)

```python theme={null}
response = requests.get(f"{BASE_URL}/v1/books/{book_id}")
book = response.json()['data']
# book has no hitCount field
```

### After (v2)

```python theme={null}
response = requests.get(f"{BASE_URL}/v2/books/{book_id}")
book = response.json()['data']
hit_count = book.get('hitCount', 0)  # New field available
print(f"This book has been viewed {hit_count} times")
```

## Step 3: Replace title sorting

v2 removes the `sort=title` parameter. Replace it with `sort=createdDate`:

### Before (v1)

```python theme={null}
# Sort by title in ascending order
response = requests.get(f"{BASE_URL}/v1/books?sort=title&order=asc")
```

### After (v2)

```python theme={null}
# Sort by creation date in descending order
response = requests.get(f"{BASE_URL}/v2/books?sort=createdDate&order=desc")
```

If your code still passes `sort=title`, v2 returns a `400` error. Handle it by falling back to `sort=createdDate`. See [Migrate away from title sorting](/how-to-guides/how-to-guides-migrate-away-from-title-sorting#step-3-verify-your-changes) for the full error response and a retry pattern.

## Step 4: Test your migration

After making these changes, test your code to ensure it works correctly with BookHub Publisher API v2. Verify that the `hitCount` field is accessible and that sorting behaves as expected. You should see `201`, `200`, and an integer `hitCount`.

1. Send a Create book request and verify:

   * The responsereturns `201 Created` with a `bookId`.
   * The Finalize book request returns `200 OK` and updates the book status to `ACTIVE`.
   * The `hitCount` field is included and updates correctly for each retrieved book.
   * The date sorting functions as expected.

For example:

```python theme={null}
import requests

BASE_URL = "https://api.bookhub.com/api"
TOKEN = "YOUR_JWT_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Step 1. Create a book
create_response = requests.post(
    f"{BASE_URL}/v2/books",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "title": "My New Book",
        "author": "John Doe",
        "description": "A new biography from a well-known author",
        "language": "en-US",
        "publisher": "My Publishing House",
        "publishedDate": "2026-03-15",
        "isbn": "978-3-16-148410-0",
        "price": 24.99,
        "coverImages": ["https://example.com/cover.jpg"],
        "genres": ["Fiction", "Adventure"],
        "bookFormat": "Hardcover"
    }
)
print(f"Create: {create_response.status_code}")
book_id = create_response.json()['data']['bookId']

# Step 2. Finalize the book
finalize_response = requests.patch(
    f"{BASE_URL}/v2/books/{book_id}/finalize",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"notes": "Migration test"}
)
print(f"Finalize: {finalize_response.status_code}")

# Step 3. Retrieve the book and verify hitCount
get_response = requests.get(
    f"{BASE_URL}/v2/books/{book_id}",
    headers=HEADERS
)
book = get_response.json()['data']
print(f"Status: {book['status']}")
print(f"hitCount: {book.get('hitCount', 'field not found')}")

# Step 4. Verify date sorting works
list_response = requests.get(
    f"{BASE_URL}/v2/books",
    headers=HEADERS,
    params={"sort": "createdDate", "order": "desc"}
)
print(f"List books: {list_response.status_code}")
```

## Next steps

Explore related topics:

### Quickstart guide

* [Quickstart guide](/quickstart/quickstart) — Get up and running with the BookHub Publisher API v2 in minutes.

### Conceptual guides

* [Using the `hitCount` field for analytics](/conceptual-guides/conceptual-guides-hitcount-analytics) — Understand the `hitCount` field in the BookHub Publisher API v2.

### How-to guides

* [Migrate away from title sorting](/how-to-guides/how-to-guides-migrate-away-from-title-sorting) — Update your code to remove title sorting in BookHub Publisher API v2.
* [Rank books by hitCount to find top performers](/how-to-guides/how-to-guides-use-hitcount-to-track-book-performance) — Use the `hitCount` field to rank books by buyer interest and flag your top performers.
* [Monitor rate limits](/how-to-guides/how-to-guides-monitor-rate-limits) — Implement best practices for handling API rate limits.

### Reference

* [Release notes](/reference/reference-release-notes) — Explore all changes in BookHub Publisher API v2.
* [Breaking changes in v2](/reference/reference-breaking-changes) — Highlights important information about breaking changes in the BookHub Publisher API.
* [Track high-performing books with `hitCount`](/reference/reference-code-examples#track-high-performing-books-with-hitcount) — Learn how to use the `hitCount` field in PHP.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.