Overview

This document outlines the flow to amend bookings via API, eliminating the need for manual customer service intervention.

Allowed Amendments

• Guest Name change
• Date Change
• Add Special Requests

Amendment via the Affiliate API is a two-step process which requires calling the APIs in the order below.

1. Amendment API (Review)

Allows users to request amendments. This API sets up the requested amendment, validates feasibility, and provides details of the refund amount or additional charges for date changes.

Note: This API doesn't modify the booking.

2. Confirm Amendment API (Execute)

Call this API using the details returned from the Amendment API response. The Confirm Amendment API processes the requested amendment

Note: Booking gets modified in this API.

Best Practices

• The list of permitted amendments for a booking can be found in the Booking Details API, under the amendmentFeatures field. Partners should always check this field before attempting any booking amendments through the Amendment API.
• Only one amendment can be processed at a time. For example, a partner cannot amend both the date and guest information simultaneously.
• Some fields, such as Guest Name, may be amendable even if others, like check-in or check-out dates, are not. The ability to amend is determined by individual field flags.

Note: 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.

1. Guest Name Change - Amendment flow

For guest name changes, there is no validation on the nationality / age of new guests. Partners must ensure the modified guests follow same suite as the original guest.

flowchart TD
    Start([Start]) -->|Check Booking Details - amendmentFeatures| CheckFeature{Is GuestInfoAmendment available?}
    
    CheckFeature -->|No| NotAllowed([Guest Name Amendment - Not Allowed])
    NotAllowed --> End([End])
    
    CheckFeature -->|Yes| Allowed[Guest Name Amendment - Allowed]
    Allowed --> CallAmendAPI[Call Amendment API with updated guest name details]
    
    CallAmendAPI --> AmendSuccess{Is Successful?}
    
    AmendSuccess -->|Yes| GetAmendId[Returns Amendment Identifier]
    GetAmendId --> CallConfirmAPI[Call Confirm Amendment API]
    
    CallConfirmAPI --> CheckStatus{Check Status in Response}
    CheckStatus -->|Confirmed| AmendComplete[Name Change Amendment Completed]
    AmendComplete --> CallBookingAPI[Call Booking Details API]
    
    CallBookingAPI --> VerifyStatus{Is amendmentStatus Confirmed?}
    VerifyStatus -->|Yes| UpdateBooking[Update booking with amended info]
    UpdateBooking --> End
    VerifyStatus -->|No| RetryBooking[Retry Booking Details up to 30 mins]
    RetryBooking --> CallBookingAPI
    RetryBooking -->|Status not updated after 30 mins| ContactCS([Contact CS to check on amendment])
    ContactCS --> End
    
    CheckStatus -->|Pending| CallBookingAPI
    
    AmendSuccess -->|No| CheckError[Check Amendment Response]
    CheckError --> IsActionable{Is error response retryable?}
    IsActionable -->|Yes| RetryAmend[Retry Amendment]
    RetryAmend --> CallAmendAPI
    IsActionable -->|No or Retry Exhausted| AmendFailed([Amendment Failed - Log & Escalate via Ticketing])
    AmendFailed --> End

    style Start fill:#e3f2fd,stroke:#1565c0
    style End fill:#c8e6c9,stroke:#2e7d32
    style UpdateBooking fill:#c8e6c9,stroke:#2e7d32
    style NotAllowed fill:#ffcdd2,stroke:#c62828
    style AmendFailed fill:#ffcdd2,stroke:#c62828
    style ContactCS fill:#fff9c4,stroke:#f57f17

2. Special Request - Amendment flow

Special Request Amendment - doesn't modify the earlier requested special requests. It simply provides an option to add further special requests to the hotels.

Success of this call doesn't guarantee requested special request. It's subject to property.

Note: Special Request changes won't be reflected under the amendments node in Booking Details. Successful special request changes would be reflected under specialRequest node in Booking Details

flowchart TD
    Start([Start]) -->|Check Booking Details - amendmentFeatures| CheckFeature{Is SpecialRequest available?}
    
    CheckFeature -->|No| NotAllowed([Special Request Addition - Not Allowed])
    NotAllowed --> End([End])
    
    CheckFeature -->|Yes| Allowed[Special Request Addition - Allowed]
    Allowed --> CallAmendAPI[Call Amendment API with necessary special requests]
    
    CallAmendAPI --> AmendSuccess{Is Successful?}
    
    AmendSuccess -->|Yes| GetAmendId[Returns Amendment Identifier]
    GetAmendId --> CallConfirmAPI[Call Confirm Amendment API]
    
    CallConfirmAPI --> CheckStatus{Check Status in Response}
    CheckStatus -->|Confirmed| AmendComplete[Special Request Sent to Property]
    AmendComplete --> CallBookingAPI[Call Booking Details API]
    
    CallBookingAPI --> VerifyStatus{Special request appears under specialRequest node?}
    VerifyStatus -->|Yes| UpdateBooking[Update booking with special request info]
    UpdateBooking --> End
    VerifyStatus -->|No| RetryBooking[Retry Booking Details up to 30 mins]
    RetryBooking --> CallBookingAPI
    RetryBooking -->|Special request not reflected| ContactCS([Contact CS to check on amendment])
    ContactCS --> End
    
    CheckStatus -->|Pending| CallBookingAPI
    
    AmendSuccess -->|No| CheckError[Check Amendment Response]
    CheckError --> IsActionable{Is error response retryable?}
    IsActionable -->|Yes| RetryAmend[Retry Amendment]
    RetryAmend --> CallAmendAPI
    IsActionable -->|No or retry Exhausted| AmendFailed([Amendment Failed - Log & Escalate via Ticketing])
    AmendFailed --> End

    style Start fill:#e3f2fd,stroke:#1565c0
    style End fill:#c8e6c9,stroke:#2e7d32
    style UpdateBooking fill:#c8e6c9,stroke:#2e7d32
    style NotAllowed fill:#ffcdd2,stroke:#c62828
    style AmendFailed fill:#ffcdd2,stroke:#c62828
    style ContactCS fill:#fff9c4,stroke:#f57f17

3. Date Change - Amendment flow

For Date Change Amendments, the new check-in date must be greater than current date -1 (to account for property time zone differences) & the new check-out date must be greater than the new check-in date.

flowchart TD
    Start([Start]) -->|Check Booking Details - amendmentFeatures| CheckFeature{Is DateAmendment available?}
    
    CheckFeature -->|No| NotAllowed([Date Amendment - Not Allowed])
    NotAllowed --> End([End])
    
    CheckFeature -->|Yes| Allowed[Date Amendment - Allowed]
    Allowed --> CallAmendAPI[Call Amendment API with updated check-in/check-out info]
    
    CallAmendAPI --> AmendSuccess{Is Successful?}
    
    AmendSuccess -->|Yes| GetAmendId[Returns Amendment Identifier]
    GetAmendId --> ShowPrice[Show updated booking price from newTotal node]
    ShowPrice --> CheckCharges{Refund or Additional Charges?}
    CheckCharges -->|Refund Scenario| ShowRefund[Log & show refund amount from refundTotal node]
    CheckCharges -->|Additional Charge Scenario| ShowCharge[Log & show additional charges from additionalCosts node]
    ShowRefund --> CallConfirmAPI[Call Confirm Amendment API]
    ShowCharge --> CallConfirmAPI
    
    CallConfirmAPI --> CheckStatus{Check Status in Response}
    CheckStatus -->|Confirmed| AmendComplete[Date Amendment Completed]
    AmendComplete --> CallBookingAPI[Call Booking Details API]
    CheckStatus -->|Pending| CallBookingAPI
    
    CallBookingAPI --> VerifyStatus{Is amendmentStatus Confirmed?}
    VerifyStatus -->|Yes| UpdateBooking[Update booking with amended info]
    UpdateBooking --> End
    VerifyStatus -->|No| RetryBooking[Retry Booking Details up to 30 mins]
    RetryBooking --> CallBookingAPI
    RetryBooking -->|Status not updated after 30 mins| ContactCS([Contact CS to check on amendment])
    ContactCS --> End
    
    AmendSuccess -->|No| CheckError[Check Amendment Response]
    CheckError --> IsActionable{Is error response retryable?}
    IsActionable -->|Yes| RetryAmend[Retry Amendment with correction]
    RetryAmend --> CallAmendAPI
    IsActionable -->|No or Retry Exhausted| AmendFailed([Amendment Failed - Log & Escalate via Ticketing])
    AmendFailed --> End

    style Start fill:#e3f2fd,stroke:#1565c0
    style End fill:#c8e6c9,stroke:#2e7d32
    style UpdateBooking fill:#c8e6c9,stroke:#2e7d32
    style NotAllowed fill:#ffcdd2,stroke:#c62828
    style AmendFailed fill:#ffcdd2,stroke:#c62828
    style ContactCS fill:#fff9c4,stroke:#f57f17

Amendment API

The Amendment API allows partners to request changes to a booking. This API validates the requested amendment and returns information about any additional charges or refunds that may apply.

Suggested Timeout: 120 seconds

Amendment API - Request

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentType": 2,
    "guestDetails": {
      "primaryGuest": {
        "firstName": "PrimaryFirstName",
        "lastName": "PrimaryLastName"
      },
      "secondaryGuests": [
        {
          "firstName": "SecondaryFirstName",
          "lastName": "SecondaryLastName"
        },
        {
          "firstName": "SecondaryFirstName",
          "lastName": "SecondaryLastName"
        }
      ]
    }
  }
}

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentType": 3,
    "specialRequest": "I need a non-smoking room"
  }
}

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentType": 1,
    "bookingPeriod": {
      "checkIn": "2024-10-11",
      "checkOut": "2024-10-12"
    }
  }
}

Request Field Details (Required = *)

Below are the details of the fields present in the request of the affiliate amendment API.

Amendment API - Response (Success)

{
  "status": "200",
  "amendmentIdentifier": "v1_XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5_NSc7PTVUoyVdISixONTPRSy8tKlUEAPCdUNYXAAAAH4sICPsdulsCAHJlYWRtZS50eHQAC0",
  "bookingId": 66788065
}

{
  "status": "200",
  "amendmentIdentifier": "v1_XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5_NSc7PTVUoyVdISixONTPRSy8tKlUEAPCdUNYXAAAAH4sICPsdulsCAHJlYWRtZS50eHQAC0",
  "bookingId": 66788065
}

{
  "status": "200",
  "amendmentIdentifier": "v1_XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5_NSc7PTVUoyVdISixONTPRSy8tKlUEAPCdUNYXAAAAH4sICPsdulsCAHJlYWRtZS50eHQAC0",
  "bookingId": 66788065,
  "defaultRoomBasedOnBooking": true,
  "paymentDetails": {
    "originalBookingValue": {
      "amount": 110.5,
      "currency": "USD"
    },
    "newTotal": {
      "amount": 100,
      "currency": "USD"
    },
    "refundTotal": {
      "amount": 10.5,
      "currency": "USD"
    },
    "refunds": [
      {
        "description": "service charge",
        "note": "service charge",
        "refundAmount": {
          "amount": 10.5,
          "currency": "USD"
        }
      }
    ],
    "amendmentPayment": {
      "originalChargeOption": "PayLater",
      "newChargeOption": "PayNow",
      "newPayLaterDate": "2024-08-22",
      "originalPayLaterDate": "2024-08-28",
      "paymentDetailsRequired": true
    }
  }
}

{
  "status": "200",
  "amendmentIdentifier": "v1_XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5_NSc7PTVUoyVdISixONTPRSy8tKlUEAPCdUNYXAAAAH4sICPsdulsCAHJlYWRtZS50eHQAC0”",
  "defaultRoomBasedOnBooking": true,
  "bookingId": 66788065,
  "paymentDetails": {
    "originalBookingValue": {
      "amount": 100,
      "currency": "USD"
    },
    "additionalAmountToBePaid": {
      "amount": 10.5,
      "currency": "USD"
    },
    "newTotal": {
      "amount": 110.5,
      "currency": "USD"
    },
    "additionalCosts": [
      {
        "description": "service charge",
        "note": "service charge",
        "costAmount": {
          "amount": 10.5,
          "currency": "USD"
        }
      }
    ],
    "amendmentPayment": {
      "originalChargeOption": "PayLater",
      "newChargeOption": "PayNow",
      "newPayLaterDate": "2024-08-22",
      "originalPayLaterDate": "2024-08-28",
      "paymentDetailsRequired": true
    }
  }
}

Success Response Field Details (Required = *)

Below are the details of the fields present in the response of the affiliate amendment API.

Amendment API - Response (Failure)

{
  "status": "400",
  "errorMessage": {
    "id": "401",
    "subId": "7113",
    "message": "GuestName update is not allowed"
  }
}

Failure Response Field Details (Required = *)

Below are the details of the fields present in the response of the affiliate amendment API.

Confirm Amendment API

Below are the details of the fields present in the request of the Confirm Amendment API.

Suggested Timeout: 120 seconds

Confirm Amendment API - Request

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentIdentifier": "XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5",
    "amendmentType": 2
  }
}

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentIdentifier": "XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5",
    "amendmentType": 3
  }
}

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentIdentifier": "XCFxMlYtaypYeCZHdCYgc3kuRCFsbUZYWSAgWkBrTjM7QmcuJj1wew=JkR4flA8NE1XWFhrcTUsbEt7XSFMTi5",
    "amendmentType": 1
  },
  "paymentDetails": {
    "creditCardInfo": {
      "cardType": "Visa",
      "number": "123456789000",
      "expiryDate": "032029",
      "cvc": "543",
      "holderName": "JSONTEST",
      "countryOfIssue": "US",
      "issuingBank": "BankName"
    }
  }
}

Request Field Details (Required = *)

Given below are the details of the fields present in the request of the ConfirmAmendment API

Confirm Amendment API - Response (Success)

{
  "bookingId": 66788065,
  "amendmentId": 1310981,
  "status": "200",
  "amendmentStatus": "Confirmed"
}

Success Response Field Details (Required = *)

Below are the details of the fields present in the response of the ConfirmAmendment API.

Confirm Amendment API - Response (Failure)

{
  "status": "400",
  "errorMessage": {
    "id": "503",
    "subId": "7110",
    "message": "All room rate and allotment are not available"
  }
}

Failure Response Field Details (Required = *)

Below are the details of the fields present in the response of the ConfirmAmendment API.