Return Helper API
Return Helper は、返品リクエストの作成から、配送追跡、ラベル生成、倉庫処理まで、Eコマースの商品返品をエンドツーエンドで管理するAPIスイートを提供しています。このAPIはサーバー間連携専用です。クライアントサイドのコードからこれらのエンドポイントを直接呼び出さないでください。
お知らせ
レート制限：1 秒あたり 1 リクエスト
2026 年 11 月 1 日からAPI が受け付けるリクエストは 1 秒あたり最大 1 件になります。繁忙期までに呼び出し頻度をご確認ください。
Resend Order 作成で Seller Reference Number に対応
resendNumber を設定している場合は対応が必要Resend の検索がすべてのアカウントで利用可能になります。
resendNumber は読み取り専用になります。新しい Webhook イベント：取引追加済み
2026 年 10 月 5 日からすべての課金、返金、トップアップが Webhook エンドポイントに送信されます。
API レート制限：1 秒あたり 1 リクエスト
2026 年 11 月 1 日から、Return Helper は繁忙期におけるすべてのインテグレーションのサービス安定性を高めるため、API に 1 秒あたり 1 リクエストのレート制限を適用します。- 1 秒あたり 1 リクエストを超えないよう、呼び出し間隔を調整してください。
- 一覧エンドポイントをポーリングするのではなく、Webhook で配送・在庫・再送の更新を受け取ってください。
Resend Order 作成での Seller Reference Number 対応
Resend Order を作成（User API）は、SKU で Resend を作成と同様に、任意のsellerReferenceNumber を受け付けるようになります。これにより、Enterprise に限らずすべてのアカウントが Seller Reference Number で Resend を検索を利用できるようになります。
sellerReferenceNumber は任意項目のため、既存のインテグレーションはそのまま動作します。ただし、破壊的変更が 1 点あります：resendNumber は Return Helper が生成する読み取り専用の値になります。
マイルストーン 1 からマイルストーン 2 までの間に、次のとおり移行してください：
- 独自の参照番号は
resendNumberではなくsellerReferenceNumberで送信してください。 - 再送ステータス更新 Webhook や自社の記録を
resendNumberで照合している場合は、sellerReferenceNumberでの照合に切り替えてください。
resendNumber と異なり、sellerReferenceNumber は一意ではありません。Return Helper は重複した値を拒否しません。リトライ時に Resend が重複して作成されるのを防ぐには、x-returnhelper-idempotency-key ヘッダーを送信してください。
マイルストーン 1 の日付は、このページと変更履歴でお知らせします。
新しい Webhook イベント：取引追加済み
2026 年 10 月 5 日から、Return Helper はお客様のアカウントに取引が計上されるたびに、登録済みのすべての Webhook エンドポイントへ取引追加済みイベントを送信します。新たな登録は不要です。2026 年 10 月 5 日より前に計上された取引は送信されません。変更履歴
- 返品ラベルをキャンセルで返品ラベルをキャンセルできるようになりました。シップメントを修正するには、ラベルをキャンセルしてから新しい Return Shipment を作成してください。
- お知らせ： 2026 年 11 月 1 日から適用される、1 秒あたり 1 リクエストの API レート制限。
- お知らせ： Resend Order 作成での
sellerReferenceNumber対応。resendNumberは読み取り専用になります。
- Notification Endpoint を追加、Notification Endpoint を一覧取得、Notification Endpoint を削除で、Webhook 通知エンドポイントをご自身で管理できるようになりました。
利用可能なAPI
User API — 返品リクエスト、配送、ラベル、在庫、アカウント設定を管理するための、マーチャントおよびパートナー向け認証済みエンドポイントです。 Public API — サービスタイプ、倉庫一覧、ステータスコード、対応国などのルックアップ値を公開する参照データエンドポイントです。認証
すべてのAPIリクエストには、リクエストヘッダーとしてAPIキーとトークンが必要です：- Return Helper ユーザーポータルにログインします。
- 設定 → 署名キーとAPIトークン に移動します。
- 既存のキーとトークンのペアが一覧表示されます。新しいペアを生成することもできます。
ユーザーポータルの署名キー、APIトークン、APIキー
ベースURL
サンドボックス
本番環境
冪等性(Idempotency)
以下のエンドポイントはx-returnhelper-idempotency-key ヘッダーを受け付けます。リトライしたリクエストが一度だけ処理されるよう、このヘッダーを送信してください。
その他のエンドポイントはこのヘッダーを無視します。
User-Agentヘッダー
問題を調査する際にReturn Helperサポートがあなたの連携を識別できるよう、User-Agentヘッダーを含めてください：
OpenAPI仕様
完全なAPI仕様はOpenAPI 3.1ドキュメントとして提供されています。PostmanやInsomniaなどのAPIクライアントに直接インポートしたり、OpenAPI Generatorなどのツールを使用してクライアントSDKを生成したりするために使用できます。OpenAPI仕様をダウンロード
openapi.json — OpenAPI 3.1エラーハンドリング
すべてのレスポンス（成功・失敗を問わず）は共通のエンベロープにラップされます：correlationId および meta と同じトップレベルに追加フィールドとして含まれます（例：getAllCountries は { correlationId, meta, countries: [...] } を返します）。ペイロードを読み取る前に必ず meta.errorCode を確認してください。本 API はソフトエラー方式を採用しており、バリデーション失敗時には HTTP 200 が返され、meta.status: 400 と meta.errorCode が設定されます。
失敗パターン
バリデーション失敗の例
correlationId をログに記録してください。Return Helper サポートが問題調査の際にこの ID を用いてリクエストを追跡します。
一般的な注意事項
- すべての
dateTimeパラメーターはISO 8601形式でなければなりません。そうでない場合、APIはパースできません。 - 日付文字列パラメーター（例：
createToStr、createFromStr）もISO 8601形式である必要があります；時刻部分は無視されます。 - APIから返されるすべてのタイムスタンプはUTCです。
Webhook
ラベル結果および倉庫イベント（配送到着、在庫作成、画像アップロードなど）は、Webhook通知を通じて非同期で配信されます。これらのイベントを受信するには、通知エンドポイントを登録する必要があります。 通知イベントタイプとそのペイロードの完全な一覧については、Webhookセクションを参照してください。テクニカルサポートへのお問い合わせ
技術的なご質問や連携に関する問題は、support@returnhelper.com までメールでお問い合わせください。調査のため、以下の情報を記載してください：- レスポンスの
correlationId - 環境（サンドボックスまたは本番環境）と呼び出したエンドポイント
- リクエストの日時（タイムゾーンを含む）
- リクエストボディと受信したレスポンス