【AirHost API】予約・料金・支払い情報のレスポンスサンプル

AirHost API（社内システム用API）では、予約情報に加えて、予約元、料金・税金の内訳、支払い状況、支払い・返金履歴などの情報を取得できます。

以下は、実際の予約データをもとに、個人情報および予約を特定できる情報を匿名化・加工したレスポンスサンプルです。

`GET /stays/{id}`

GET /stays/{id} では、予約情報や予約元、料金・税金の内訳、支払い状況などを取得できます。

主な取得項目は以下のとおりです。

内容	APIフィールド
予約元・チャネル	`reservation_source_code` / `reservation_source_name`
宿泊料金	`accommodation_fee`
清掃料金	`cleaning_fee`
OTA手数料	`channel_fee`
キャンセル料	`cancellation_fee`
料金・税金などの内訳	`fee_breakdown`
OTA事前決済額	`prepaid_amount`
合計請求額	`total_charge_amount`
支払い済み金額	`total_payment_amount`
未払い残高	`outstanding_balance`

レスポンス例

以下は、Booking.com 予約の一例です。

{
  "reservation_source_name": "Booking.com",
  "accommodation_fee": 64800.0,
  "channel_fee": 9266.0,
  "prepaid_amount": 64800.0,
  "total_charge_amount": 66600.0,
  "total_payment_amount": 64800.0,
  "outstanding_balance": 1800.0,
  "fee_breakdown": [
    {
      "type": "per_day",
      "name": "Standard Rate",
      "amount": 64800.0
    },
    {
      "type": "channel_fee",
      "name": "OTA手数料・決済手数料",
      "amount": 9266.0
    },
    {
      "type": "other_fee",
      "name": "市税",
      "amount": 1800.0
    }
  ]
}

この例では、宿泊料金64,800円がOTA側で回収され、合計請求額66,600円に対して64,800円が支払われているため、未払い残高は1,800円となります。

`GET /folios/{id}`

GET /folios/{id} では、予約に紐づく個別の請求項目や、支払い・返金履歴を取得できます。

主な取得項目は以下のとおりです。

内容	APIフィールド
請求項目	`charges`
支払い・返金履歴	`payments`
支払い金額	`amount`
返金金額	`refund_amount`
支払い状態	`state`
支払日	`date`
合計請求額	`total_charge_amount`
支払い済み金額	`total_payment_amount`
未払い残高	`outstanding_balance`

支払い・返金履歴の例

{
  "payments": [
    {
      "payment_source_type": "ota_collect",
      "amount": 64800.0,
      "refund_amount": 0.0,
      "state": "completed",
      "date": "2026-06-20"
    }
  ],
  "total_charge_amount": 66600.0,
  "total_payment_amount": 64800.0,
  "outstanding_balance": 1800.0
}

`partial_paid` / `over_paid` について

APIには、partial_paid や over_paid という専用のステータス項目はありません。

支払い状況は、total_payment_amount と total_charge_amount を比較することで判断できます。

total_payment_amount < total_charge_amount
→ 一部未払い

total_payment_amount = total_charge_amount
→ 全額支払い済み

total_payment_amount > total_charge_amount
→ 過払い

個別の請求内容や支払い・返金履歴については、charges および payments から確認できます。

注意: 実際に取得できる項目や fee_breakdown の内容は、予約元、支払い方法、施設設定、予約に付加されている料金・税金などによって異なる場合があります。