メッセージ機能導入に伴うAPIへの影響

1. はじめに

メルカリShopsでは、お客さまから届く問い合わせを受け付け、お客さまと連絡を取り合うための「メッセージ機能」を提供しています。商品購入前の問い合わせ（商品・ショップへの質問）と、購入後の注文に関する連絡のどちらも本機能で対応でき、ショップ管理画面では「メッセージ管理」から利用できます（参考: メルカリShopsガイド「メッセージ機能」）。

メッセージ機能は2026年6月22日にリリース済みで、従来の取引メッセージ機能・商品への質問機能はメッセージ機能に統合されています。取引メッセージ関連の Public API は後方互換が保たれており、現在も既存のインターフェースのまま、内部的にはメッセージ機能を利用する形で動作しています。

本ドキュメントでご案内する新API群は、このメッセージ機能をAPIから利用できるようにするものです。本ドキュメントでは、この新API群を「Inquiry API」と表記します。

※ GraphQL レスポンスの extensions に含まれる inquiry.id（例: "extensions": { "inquiry": { "id": "..." } }）は、API のエラーに関する調査をご依頼いただく際にお伝えいただくことで、調査を効率的に行うための ID です。本ドキュメントの Inquiry API とは無関係です。

1.1 メッセージ機能のAPI提供により可能になること

• メッセージの一元管理: ショップ・商品・注文の3種のメッセージを、同一のAPIで一覧・返信・ステータス管理
• 商品購入前の問い合わせへの対応: 従来の取引メッセージAPIでは扱えなかった、商品・ショップへの購入前問い合わせにAPIで対応可能に
• 柔軟な検索: ショップ管理画面の絞り込みと同等の条件（注文ID・商品名・商品管理コード・購入者名など）でのメッセージ検索
• 画像添付（今後対応予定）: メッセージへの画像添付（現在のメッセージ機能では画像添付はできません）

1.2 APIへの影響

現在提供中の取引メッセージAPI（OrderTransaction.messages / addOrderTransactionMessage など）は、1つの注文につき1スレッドでメッセージをやり取りする前提の機能であり、複数スレッド対応後は互換性を保てなくなります。また、今後 Inquiry API に追加される画像添付機能は、取引メッセージAPIではご利用いただけません。そのため、メッセージ機能に対応した Inquiry API の提供を開始した後、取引メッセージAPIを廃止いたします。

Inquiry API の提供と取引メッセージAPIの廃止は、以下の3つのフェーズに分けて実施します。取引メッセージAPIをご利用中の場合は Inquiry API への移行が必要となるため、移行期間として、フェーズ1の Inquiry API 提供開始（2026年8月上旬）からフェーズ2の取引メッセージAPIの廃止（2027年1月中旬）までを設けています。この期間中に Inquiry API への移行をお願いいたします。

※ 上記の予定時期は開発状況により変更される可能性があります。正確な提供開始時期については、別途アナウンスいたします。

2. 変更点概要

2.1 問い合わせを表すリソースの追加

問い合わせスレッドを表す Inquiry と、スレッド内の各メッセージを表す InquiryMessage リソースが追加されます。従来の取引メッセージは「注文（OrderTransaction）を対象とした Inquiry」として表現されます。

なお、既存の取引メッセージはすべて Inquiry / InquiryMessage として取り込み済みです。Inquiry API への移行後も、過去にやり取りした取引メッセージを含めて取得できます。

2.2 取引メッセージAPIの廃止

2.3 問い合わせ関連Webhookの追加

お客さまからのメッセージ受信などを検知するための新しい webhook トピック（inquiry_message_created / inquiry_message_admin_deleted / inquiry_resolved）が追加されます。

2.4 画像添付（今後追加予定）

フェーズ3において、メッセージへの画像添付に対応予定です。

2.5 注文問い合わせの複数スレッド対応（今後追加予定）

現在、注文 target の問い合わせは1つの注文につき1スレッドですが、フェーズ3において、同一の注文に対して複数の問い合わせスレッドを作成できるようになります。画像添付への対応と同じタイミングでの提供を予定しています。なお、商品・ショップへの問い合わせでは、現時点から同一の対象に対して複数のスレッドが存在することがあります。

2.6 デバッグ用問い合わせ作成API（今後追加予定）

お客さまからの問い合わせ受信をテストできるよう、お客さま起点の問い合わせをデバッグ用に作成できるAPIを追加予定です（2026年9月末目処）。これにより、商品・ショップ target を含む問い合わせの受信・返信フローを、実際のお客さまを介さずにテストできるようになります。詳細な仕様は提供開始時に改めてアナウンスいたします。

3. 影響範囲一覧

以下の表は、各APIがいつ、どのような影響を受けるかをまとめたものです。ご利用中のAPIをご確認ください。

なお、「カート機能導入に伴うAPIへの影響」では、mutation addTransactionMessage の移行先として addOrderTransactionMessage をご案内していますが、Inquiry API（createInquiry / addInquiryMessage）へ移行する場合は、addOrderTransactionMessage を経由する必要はありません。

4. 追加されるType

Inquiry API では、メッセージを表す以下のTypeが追加されます。各Typeは、ショップ管理画面のメッセージ機能で使われている概念に対応しています。

各Typeの関係

※ 1つの注文につき Inquiry は現在1つです。複数スレッド対応（§2.5、フェーズ3）以降は 1 : N になります。対象の種類に応じて、Inquiry.target からは InquiryShopTarget / InquiryProductTarget / InquiryOrderTransactionTarget のいずれかが返ります。スレッド内のメッセージは inquiryMessages で取得します。

4.1 Inquiry と InquiryMessage

Inquiry は1つの問い合わせスレッドを表し、InquiryMessage はスレッド内の個々のメッセージを表します。1つの Inquiry には複数の InquiryMessage が紐づきます（1:N）。ただし、注文 target については、現在は1つの注文につき Inquiry は1つ（注文 : Inquiry = 1:1）です。

作成できる Inquiry（スレッド）の数は、target によって異なります。

4.2 問い合わせの対象（InquiryTarget）

Inquiry は以下の3種類の対象（target）のいずれかを持ちます。Inquiry.target は union 型で、対象の種類ごとに異なる型が返されます。

ショップ側から createInquiry で問い合わせを開始できるのは注文 target のみです。ショップ・商品への問い合わせはお客さま起点で作成され、ショップは一覧取得と返信（addInquiryMessage）で対応します。いずれの target の Inquiry にも返信は可能です。

また、商品・ショップへの購入前問い合わせは、ショップ管理画面の設定「ショップへの購入前問い合わせ」で「受け取る」を選択している場合にのみ受け付けられます。「受け取らない」設定の場合、お客さまは商品詳細／ショッププロフィールから問い合わせできないため、商品・ショップ target の Inquiry は届きません。

4.3 InquiryStatus（問い合わせのステータス）

初期ステータス

メッセージ送信による自動遷移

メッセージが送信されると、ステータスは自動的に遷移します。

updateInquiryStatus による手動遷移

ショップが updateInquiryStatus で指定できるステータスは HANDLING_BY_SELLER と RESOLVED の2つのみです。

ステータス遷移図

※ 図中の「解決」は、ショップによる「解決済み」への変更（updateInquiryStatus）・お客さまによる解決・2週間の自動解決のいずれかを指します。

解決済み後の再オープン

RESOLVED の問い合わせには、お客さま・ショップのどちらもメッセージを送信できます。お客さまが送信すると AWAITING_SELLER に、ショップが送信すると AWAITING_BUYER に遷移します（再オープン）。また、問い合わせの解決は、いずれの target もお客さま・ショップの双方から行えます（お客さま側で解決されるケースがあります）。RESOLVED は終端状態ではない点にご注意ください。

自動解決

ショップからの最後のメッセージ送信後、お客さまから2週間返信がない場合、問い合わせは自動的に RESOLVED になります。ショップの操作なしにステータスが変化するケースがある点にご注意ください。

4.4 その他のフィールド

5. インターフェース仕様

inquiries / inquiry の取得結果に最新の更新が反映されるまでには数秒かかることがあります。createInquiry や addInquiryMessage などでデータを更新した直後に取得する場合は、2〜3秒ほど間隔を空けてから取得してください。

5.1 query inquiries

ショップに届いた問い合わせの一覧を取得します。ステータス・対象によるフィルタと、ソートを指定できます。

query {
  inquiries(first: Int = 50, after: String,
            filter: ListInquiriesFilterInput,
            sort: ListInquiriesSortInput): InquiryConnection!
}

ListInquiriesFilterInput

targetFilter で指定できる検索条件と一致方式

ListInquiriesSortInput

リクエスト例（未対応の注文問い合わせを新着順に取得）

query {
  inquiries(
    first: 50
    filter: {
      statuses: [AWAITING_SELLER, OPENED_BY_BUYER]
      targetFilter: { orderTransactionTarget: {} }
    }
    sort: { field: LAST_ACTIVITY_AT, order: DESC }
  ) {
    edges {
      node {
        id
        status
        lastActivityAt
        userInfo { nickname }
        target {
          __typename
          ... on InquiryOrderTransactionTarget { orderTransaction { id } }
          ... on InquiryProductTarget { productId productVariantId }
          ... on InquiryShopTarget { shopId }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

5.2 query inquiry

問い合わせIDを指定して単一の問い合わせを取得します。

query { inquiry(id: ID!): Inquiry! }

5.3 query inquiryMessages

問い合わせIDを指定して、スレッド内のメッセージ一覧を取得します。

query {
  inquiryMessages(inquiryId: ID!, first: Int = 100, after: String): InquiryMessageConnection!
}

InquiryMessage

5.4 mutation createInquiry

ショップ側から注文に関する問い合わせスレッドを新規に開始します。従来 addOrderTransactionMessage でショップから最初のメッセージを送っていたケースに相当します。

mutation { createInquiry(input: CreateInquiryInput!): CreateInquiryPayload! }

CreateInquiryInput

リクエスト例

mutation {
  createInquiry(
    input: {
      idempotencyKey: "b4f2e0a1-8c3d-4e5f-9a6b-7c8d9e0f1a2b"
      messageBody: "ご注文の商品について確認させてください。"
      target: { orderTransaction: { orderTransactionId: "order_transaction_1" } }
    }
  ) {
    inquiry { id status }
  }
}

5.5 mutation addInquiryMessage

既存の問い合わせスレッドにメッセージを追加（返信）します。target の種類を問わず利用できます。

mutation { addInquiryMessage(input: AddInquiryMessageInput!): AddInquiryMessagePayload! }

AddInquiryMessageInput

5.6 mutation updateInquiryStatus

問い合わせのステータスを更新します（例: 対応開始時に HANDLING_BY_SELLER、対応完了時に RESOLVED へ変更）。

mutation { updateInquiryStatus(input: UpdateInquiryStatusInput!): UpdateInquiryStatusPayload! }

UpdateInquiryStatusInput

遷移条件（現在のステータスによる制限）は §4.3「updateInquiryStatus による手動遷移」を参照してください。条件を満たさない場合はエラーが返されます。AWAITING_BUYER / AWAITING_SELLER への遷移はメッセージ送信に伴って自動的に行われるため、本 mutation では指定できません。

5.7 idempotencyKey

createInquiry と addInquiryMessage では、重複処理を防止するために idempotencyKey の指定が必要です。ネットワークの問題やタイムアウトによって API レスポンスが失われた場合にも、同じ処理が重複実行されることを防ぐためのものです。

使用例

問い合わせへの返信を送信する場合の例です。

1. addInquiryMessage を実行（idempotencyKey: "reply-001"）
2. メッセージの作成は成功したが、レスポンスがネットワーク問題で失われる
3. 同じ idempotencyKey: "reply-001" でリトライを実行
4. メッセージは既に作成済みのため、重複作成は行われずエラーが返される

リトライに対してエラーが返された場合は、元のリクエストが成功している可能性があります。inquiries / inquiryMessages で対象が作成済みかをご確認ください。

仕様

6. Webhook

問い合わせ関連のイベントを検知するため、以下の webhook トピックが追加されます。

各トピックの Payload は以下のとおりです。

inquiry_message_created

Payload にはメッセージ本文が含まれません。本文は inquiry_message_id をもとに inquiryMessages で取得してください。

inquiry_message_admin_deleted

inquiry_resolved

7. 画像添付（今後追加予定）

メッセージへの画像添付に、フェーズ3（2027年2月上旬予定）で対応予定です。

7.1 画像の添付（送信）

createInquiry（最初のメッセージ）および addInquiryMessage の入力に attachments フィールドを指定します。

InquiryMessageAttachmentInput

制約事項

リクエスト例（既存スレッドへの画像つき返信）

mutation {
  addInquiryMessage(
    input: {
      idempotencyKey: "3f8a1c2d-6b4e-4f7a-8d9c-0e1f2a3b4c5d"
      inquiryId: "inq_1"
      body: "商品の状態を撮影した画像をお送りします。"
      attachments: [{ url: "https://example.com/images/item-condition.jpg" }]
    }
  ) {
    inquiryMessage {
      id
      attachments { url }
    }
  }
}

7.2 添付画像の取得

添付画像は InquiryMessage.attachments から取得できます。

InquiryMessageAttachment

7.3 廃止スケジュールとの関係

既存の取引メッセージAPI群（§3 影響範囲一覧）は、画像添付・複数スレッド対応（フェーズ3）の提供を待たず、フェーズ2（2027年1月中旬予定）で廃止されます。それまでに Inquiry API への移行実装を完了していただくようお願いいたします。

8. 移行手順の例

8.1 メッセージの取得

query {
  orderTransaction(id: "ot_1") {
    messages {
      body
      sender
      createdAt
    }
  }
}

# 1. 注文に紐づく問い合わせを特定
query {
  inquiries(filter: {
    targetFilter: {
      orderTransactionTarget: {
        orderTransactionId: "ot_1"
      }
    }
  }) {
    edges { node { id } }
  }
}

# 2. inquiry の id でメッセージを取得
query {
  inquiryMessages(inquiryId: "inq_1", first: 100) {
    edges { node { body from sentAt } }
  }
}

複数スレッド対応（フェーズ3）以降は、1つの注文に複数の問い合わせが紐づく場合があります。上記手順1で取得した edges は全件を処理するように実装してください。

8.2 メッセージの送信

mutation {
  addOrderTransactionMessage(input: {
    orderTransactionId: "ot_1"
    message: "発送しました"
  }) { ... }
}

# 既存の問い合わせに返信
mutation {
  addInquiryMessage(input: {
    idempotencyKey: "reply-001"
    inquiryId: "inq_1"
    body: "発送しました"
  }) { inquiryMessage { id sentAt } }
}

# 注文への問い合わせをショップから開始
mutation {
  createInquiry(input: {
    idempotencyKey: "create-ot_1-001"
    messageBody: "発送しました"
    target: { orderTransaction: {
      orderTransactionId: "ot_1" } }
  }) { inquiry { id } }
}

8.3 新着メッセージの検知

webhook order_transaction_message_created を利用していた場合は inquiry_message_created へ移行してください。新着メッセージの検知には webhook のご利用を推奨します。