# Bump a vendor API version and adapt to the payload changes

A vendor API version bump, adapted with recorded fixtures replayed against the new version.

Category: Vendor and third-party migrations
Source: https://letsship.ai/use-cases/bump-a-vendor-api-version
Published: 2026-08-25

## Goal

Move to a newer vendor API version and adapt to its payload changes.

## Acceptance criteria

- Recorded fixtures are replayed against the new version
- Removed and renamed fields are handled explicitly
- The version is pinned in one place
- Behaviour differences are listed in the description

## What lands as proof

Fixtures replayed against the new version, which surfaces the field changes the changelog forgot to mention.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Move to {vendor} API {version}

Description: Move to a newer vendor API version and adapt to its payload changes.

Acceptance criteria:
- Recorded fixtures are replayed against the new version
- Removed and renamed fields are handled explicitly
- The version is pinned in one place
- Behaviour differences are listed in the description

Before you create the issue, check which vendor API versions this repository pins and which are deprecated, then replace {vendor} and {version}.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: move to a newer vendor API version and adapt to its payload changes. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means recorded fixtures replayed against the new version, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.