Overview

This document provides guidance on how to cancel an Agoda booking using the Affiliate APIs. It consists of three main steps.

Steps:

1. Booking Status - get current status of the booking to confirm it is not canceled (Please refer to the Booking Details call for more information)
2. Cancel Booking (Preview) - submit a booking ID to retrieve the cancellation policy summary and estimated refund amount (if any).
3. Confirm Cancel Booking (Execute) - submit the booking details (including the reference and refund amount) to confirm and finalize the cancellation.

Notes:

• The Cancel API calls (Preview and Confirm Cancel) have a response SLA of 120 seconds.
• For the Fee waiver option, refer to the Fee Waiver Cancellation section.
• Cancellations are allowed up to 1 day before check-in. On or after check-in date: Cancellation requires manual escalation.
• A "retryable" error is a transient server or network failure that can be retried (after rechecking the booking status), while a "non-retryable" error is a permanent client-side or business error. For more details on the error types and codes, please refer to the Appendix section

You can use the following flowchart as a reference for the cancellation process:

flowchart TD
  Start([Start])
  CheckDate[Check current date vs check-in date]
  ManualEsc[Manual escalation if on or after check-in date]
  GetStatus[<b>Get Booking Status</b>]
  IsCanceled{Is booking already canceled?}
  Preview[<b>Cancel Booking - Preview</b>]
  PreviewWait[Wait for response - SLA: 120s]
  PreviewOK[Preview success - policy & refund]
  PreviewErr{Is it Retryable?}
  PreviewFail[Preview failed - Log & Escalate via Ticketing]
  Confirm[<b>Confirm Cancel - Execute</b>]
  ConfirmWait[Wait for response - SLA: 120s]
  ConfirmOK[Confirm success - cancellation finalized]
  ConfirmErr{Is it Retryable?}
  ConfirmFail[Confirm failed - Log & Escalate via Ticketing]
  FeeWaiver[Fee Waiver Cancellation - see section]
  End([End])

  Start --> CheckDate
  CheckDate -->|On or after check-in| ManualEsc
  CheckDate -->|Before check-in| GetStatus

  GetStatus --> IsCanceled
  IsCanceled -- Yes --> End
  IsCanceled -- No --> Preview
  IsCanceled -- Fee waiver request --> FeeWaiver
  FeeWaiver --> End

  Preview --> PreviewWait
  PreviewWait -->|Success| PreviewOK
  PreviewWait -->|Error| PreviewErr
  PreviewErr -->|Retryable| GetStatus
  PreviewErr -->|Not retryable or retries exhausted| PreviewFail
  PreviewOK --> Confirm
  PreviewFail --> ManualEsc

  Confirm --> ConfirmWait
  ConfirmWait -->|Success| ConfirmOK
  ConfirmWait -->|Error| ConfirmErr
  ConfirmErr -->|Retryable| GetStatus
  ConfirmErr -->|Not retryable or retries exhausted| ConfirmFail
  ConfirmOK --> End
  ConfirmFail --> ManualEsc
 
style Start fill:#e3f2fd,stroke:#1565c0
style End fill:#c8e6c9,stroke:#2e7d32
style ManualEsc fill:#ffcdd2,stroke:#c62828
style PreviewFail fill:#ffcdd2,stroke:#c62828
style ConfirmFail fill:#ffcdd2,stroke:#c62828
style ConfirmOK fill:#c8e6c9,stroke:#2e7d32

Cancel Booking (Preview)

Use this call to preview cancellation details by sending the Agoda booking ID. The API returns a summary of the cancellation policies and any refund amount.

For detailed request and response samples or a full description of the APIs, click here.

Request Example

{
    "bookingId": 80000610
}

Parameters for Cancel Request Schema (* = Require)

Response Example (Success case)

{
  "cancellationSummary": {
    "bookingId": 80000610,
    "reference": 989326276,
    "cancellationPolicy": [
      {
        "language": "en-us",
        "policyText": "Risk-free booking! You can cancel until November 27, 2021 and pay nothing!"
      },
      {
        "language": "en-us",
        "policyText": "Any cancellation received within 3 days prior to the arrival date will be charged for the entire stay."
      },
      {
        "language": "en-us",
        "policyText": "If you fail to arrive or cancel the booking, no refund will be given."
      }
    ],
    "paymentRate": [
      {
        "currency": "USD",
        "inclusive": 551.65
      }
    ],
    "refundRate": [
      {
        "currency": "USD",
        "inclusive": 551.65
      }
    ]
  }
}

Response Schema (Success case)

Response Example (Error case)

{
  "errorMessage": {
    "id": "102",
    "message": "API key 22612E6B-0000-0000-XXXX-XXXXXXXXXXXX is invalid"
  }
}

Response Schema (Error case)

Confirm Cancel Booking (Execute)

Use this step to confirm the cancellation after you have retrieved the reference and refund details from the Cancel (Preview) API.

Request Example

{
  "bookingId": 80000610,
  "reference": 989326276,
  "cancelReason": 0,
  "refundRate": {
        "currency": "USD",
        "inclusive": 551.65
  }
}

Request Schema (* = Require)

(download request schema)

Cancellation Reason Codes

Response Example (Success case)

Response Schema (Success case)

Success response returns status code 200 without body message

Response Example (Error case)

{
    "errorMessage": {
        "id": "914",
        "message": "Invalid data: Refund amount does not match"
    }
}

Response Schema (Error case)