• Projects
  • Service
  • About
  • branding.bz
  • Podcast
  • Tips
  • FAQ
  • Recruit
  • Download
  • Contact
  • branding.bz（ブランド構築SaaS）
  • DESIGN NOW（デザインメディア）
  • X
  • LinkedIn
  • Spotify
  • Facebook

213-0011 神奈川県川崎市高津区久本3-6-7-303

© 2026 ID INC. All rights reserved

claude-skills/スキル
SKILLOfficialproductivity

upgrade-shippo

プラグイン
shippo
ソース
GitHub で見る ↗
説明

Shippo API のバージョン変更、ウェブフック（自動通知）のペイロード（データ形式）のバージョン管理、およびホスト型 MCP サーバーが更新を処理する方法に関するガイドです。 次のような場合に使用: - 後方互換性（過去のバージョンとの互換性）について検討する - ウェブフックのペイロードや API レスポンス（応答）に新しいフィールドが追加された場合に対応する - ホスト型 MCP に対する OAuth 認証やバージョン不一致のエラーをトラブルシューティングする - Shippo 統合の変更前に既存の実装を監査（確認・検査）する

原文を表示

Guide for Shippo API version changes, webhook payload versioning, and how the hosted MCP server handles updates. Use when reasoning about backward compatibility, handling new fields in webhook payloads or API responses, troubleshooting OAuth/version-mismatch errors against the hosted MCP, or auditing an existing Shippo integration before a change.

ユースケース
  • APIバージョン変更時の対応
  • ウェブフックペイロードの新規フィールド追加に対応する
  • バージョン不一致のエラーをトラブルシューティング
  • Shippo統合の変更前に既存実装を監査する
本文（日本語訳）

<!-- ⚠️ 編集しないでください。skills/upgrade-shippo/SKILL.md から scripts/sync.js により自動生成されています。 ここでの編集は次回の同期時に上書きされます。 このコンテンツを変更するには、原本を編集してから同期スクリプトを再実行してください。 -->

Shippo MCP は https://mcp.shippo.com でホストされています。OAuth認証のみを使用し、サーバー側で自動更新されるため、お客様側でのインストールまたはアップグレードは不要です。本スキルでは、お客様の責任として次の項目をカバーしています：API バージョン管理、ウェブフック（イベント通知）のペイロード（データ）バージョン管理、およびホストされたセッションのトラブルシューティング。

API バージョン管理

現在の Shippo API バージョンは 2018-02-08 です。Shippo は単一の長期対応 API バージョンを使用し、ホストされたサーバーがサーバー側で管理するため、お客様が Shippo-API-Version ヘッダーを自分で設定する必要はありません。

実際の後方互換性の意味：

  • ほとんどの変更は後方互換です：新しいオプショナルフィールド、新しいリソース、追加のウェブフックイベント。既存の呼び出しは引き続き機能します。
  • 重大な変更はまれであり、リリースノートで告知されます。
  • サーバーがバージョンを選択するため、お客様側ではバージョンを固定する必要がありません。お客様の役割は、バージョン管理を行うのではなく、新しいフィールドに適切に対応することです（下記のウェブフック バージョン管理を参照）。

Shippo API の変更はAPI 変更ログで追跡できます。2026年6月時点で、本スキルセットでカバーされるワークフローに影響を与える重大な変更はありません。

ウェブフック イベント バージョン管理

ウェブフック イベントは API バージョンを変更することなく新しいフィールドを含めることができます。これに適切に対応するには：

  • ウェブフック ハンドラーで不明なフィールドを無視するのがデフォルトとし、認識しないフィールドで失敗しないようにします。
  • 必要な特定のイベント タイプのみをサブスクライブします（track_updated、transaction_created、transaction_updated など）。
  • ウェブフック ドキュメントに従い、Shippo-Signature ヘッダーを使用してウェブフック署名を検証します。

ホストされた MCP のトラブルシューティング

401 または 403 エラー

OAuth セッションの有効期限が切れているか、認可されていません。Shippo OAuth セッションを再度認可してください：Claude Code で /mcp を実行し、再度ログインします。

サーバー更新後にツールが変更または消失

ホストされたサーバーは自動更新されるため、お客様側の操作がなくてもツール カタログが変わることがあります。shippo_list_tools 経由で現在利用可能なツールを再度リストして確認してください。

存在するはずのオブジェクトで「見つかりません」エラーが表示される

オブジェクトが認可されたアカウントに存在しない、または別のアカウントに属している可能性が高いです。オブジェクトを所有するアカウントにログインしていることを確認してください（必要に応じて /mcp 経由で再度認可します）。

既存の統合をレビューする

本番環境の統合に変更を加える前に：

  1. お客様側ではバージョンを固定しないでください。ホストされたサーバーが API バージョンを管理するため、固定するものはありません。
  2. ウェブフック ハンドラーが不明なフィールドを無視することを確認します。
  3. API 変更ログで重大な変更がないか確認します。
  4. 更新後に shippo_list_tools 経由でツールを再度リストして、名前変更または追加されたオペレーションをキャッチします。
原文（English）を表示

<!-- ⚠️ DO NOT EDIT. Auto-generated from skills/upgrade-shippo/SKILL.md by scripts/sync.js Edits here will be overwritten on the next sync. To change this content, edit the canonical source and re-run the sync script. -->

The Shippo MCP is hosted at https://mcp.shippo.com. It is OAuth-only and auto-updates server-side, so there is nothing to install or upgrade on your side. This skill covers what stays your responsibility: API version awareness, webhook payload versioning, and troubleshooting the hosted session.

API version handling

The current Shippo API version is 2018-02-08. Shippo uses a single long-lived API version, and the hosted server manages it for you server-side. You do not set the Shippo-API-Version header yourself when going through the hosted MCP.

What backward-compatibility means in practice:

  • Most changes are backward-compatible: new optional fields, new resources, additional webhook events. Existing calls keep working.
  • Breaking changes are rare and announced via release notes.
  • Because the server picks the version, you don't pin anything client-side. Your job is to handle new fields gracefully (see webhook versioning below) rather than to manage versions.

Shippo API changes are tracked in the API changelog. As of 2026-06, no recent breaking changes affect the workflows covered by this skill set.

Webhook event versioning

Webhook events can include new fields without bumping the API version. To handle them gracefully:

  • Default to ignoring unknown fields in your webhook handler, never fail-closed on a field you don't recognize.
  • Subscribe only to the specific event types you need (track_updated, transaction_created, transaction_updated, etc.).
  • Verify webhook signatures using the Shippo-Signature header per webhook docs.

Troubleshooting the hosted MCP

401 or 403 errors

The OAuth session has expired or is not authorized. Re-authorize the Shippo OAuth session: in Claude Code, run /mcp and sign in again.

Tools changed or missing after a server update

The hosted server auto-updates, so the tool catalog can shift without any action on your side. Re-list the current tools via shippo_list_tools to see what is available now.

"Not found" errors for objects you expect to exist

Most likely the object does not exist on the authorized account, or it belongs to a different account. Confirm you are signed in to the account that owns the object (re-authorize via /mcp if needed).

Auditing an existing integration

Before making a change to a production integration:

  1. Don't pin anything client-side. The hosted server manages the API version, so there's nothing to pin.
  2. Verify webhook handlers ignore unknown fields.
  3. Review the API changelog for any breaking changes.
  4. Re-list tools via shippo_list_tools after an update to catch renamed or added operations.

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。