Introduction

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

New APIs

• Amendment API: Allows users to request amendments. This API sets up the requested amendment, validates its feasibility, and provides refund or additional charge details for date changes.
• ConfirmAmendment API: Confirms and processes the requested amendment

Changes to Existing API

• Booking Details API: Now includes options for available amendments and displays the amendment history for bookings that have already been modified.

Allowed Amendments

• Date change
• Name change
• Special request

Important Notes

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.
For guest name changes, there is no validation on the nationality of new guests. Partners must ensure the nationality matches the original booking.

Mandatory header fields:

• API Key
• SiteId

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.

Request Field Details (Required = *)

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

Element	Attribute	Description
bookingId* integer		Booking id, number only
amendmentDetails	amendmentType* integer	enum int of the param to be updated. Allowed values: 1 - for Date change amendment 2 - for Guest Info change Amendment 3 - Special Request amendment
Only for Special Request API Amendment
amendmentDetails	specialRequest* string
Only for Guest Info Change API Amendment
amendmentDetails > guestDetails > primaryGuest* object	firstName* string	Guest First Name English characters only. Punctuation is not allowed *The new guests must be of the same nationality as the original booking & only one guest must be mentioned as primary
amendmentDetails > guestDetails > primaryGuest* object	lastName* string	Guest Last Name English characters only. Punctuation is not allowed
amendmentDetails > guestDetails > secondaryGuests (List of objects)	firstName string	Guest First Name English characters only. Punctuation is not allowed
amendmentDetails > guestDetails > secondaryGuests (List of objects)	lastName string	Guest Last Name English characters only. Punctuation is not allowed
Only for Date Change API Amendment
amendmentDetails > bookingPeriod*	checkIn* DateTime	The check-in date in the format YYYY-MM-DD. It should be more than, equal to, or less than one day from today's date to account for property time zone differences.
amendmentDetails > bookingPeriod*	checkOut* DateTime	Should be in format YYYY-MM-DD, Check-out date must be local hotel date.

Success Response Field Details (Required = *)

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

Element	Attribute	Description
status* Integer		Status code
bookingId* Integer		Booking id, number only
amendmentIdentifier* String		Internal affiliate token to encode affiliate specific parameters.
Only for Date Change API Amendment
defaultRoomBasedOnBooking Boolean		Flag to state if the room same as that of booking
paymentDetails > originalBookingValue	amount decimal	Original Booking value
paymentDetails > originalBookingValue	currency String	Three-letter currency code
paymentDetails > newTotal	amount decimal	New booking value
paymentDetails > newTotal	currency String	Three-letter currency code.
paymentDetails > amendmentPayment	originalChargeOption String	Original Charge option. List of options are (None/PayNow/PayLater/PayAtCheckIn)
paymentDetails > amendmentPayment	newChargeOption String	Updated Charge option after amendments. List of options are (None/PayNow/PayLater/PayAtCheckIn)
paymentDetails > amendmentPayment	newPayLaterDate String	Updated pay later date. It is available only if payment option is (BNPL)
paymentDetails > amendmentPayment	originalPayLaterDate String	Original pay later date. It is available only if payment option is (BNPL)
paymentDetails > amendmentPayment	paymentDetailsRequired Boolean	Flag to state if the payment details are required
Responses for Refund scenario
paymentDetails > refundTotal	amount decimal	Amount to be returned after the amendment completion
paymentDetails > refundTotal	currency String	Three-letter currency code.
paymentDetails > refunds arrayOfObjects	description String	details about the refund
paymentDetails > refunds arrayOfObjects	note String	details about the refund
paymentDetails > refunds arrayOfObjects	refundAmount > amount decimal	Amount to be returned after the amendment completion
paymentDetails > refunds arrayOfObjects	refundAmount > currency String	Three-letter currency code.
Responses for additional payment scenario
paymentDetails > additionalAmountToBePaid	amount decimal	Amount to be paid extra to complete the amendment
paymentDetails > additionalAmountToBePaid	currency String	Three-letter currency code.
paymentDetails > additionalCosts arrayOfObjects	description String	details about the additional charges
paymentDetails > additionalCosts arrayOfObjects	note String	details about the additional charges
paymentDetails > additionalCosts arrayOfObjects	costAmount > amount decimal	Amount to be paid extra to complete the amendment
paymentDetails > additionalCosts arrayOfObjects	costAmount > currency String	Three-letter currency code.

Failure Response Field Details (Required = *)

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

Element	Attribute	Description
status* Integer		Status code
errorMessage	id String	Error message ID
errorMessage	subId String	Sub error ID
errorMessage	message String	Error message string

Scenario: Amendment=GuestInfo

Below are the sample json details of various use-cases in case the amended field is GuestInfo

Sample JSON Request:

{
  "bookingId": 66788065,
  "amendmentDetails": {
    "amendmentType": 2,
    "guestDetails": {
      "primaryGuest": {
        "firstName": "Jatin",
        "lastName": "Garg"
      },
      "secondaryGuests": [
        {
          "firstName": "Pranav",
          "lastName": "Sehgal"
        },
        {
          "firstName": "Akshit",
          "lastName": "Gupta"
        }
      ]
    }
  }
}

Sample JSON Success Response

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

Sample JSON Failure Response

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

Scenario: Amendment=SpecialRequest

Below are the sample json details of various use-cases in case the amended field is SpecialRequest

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

Sample JSON Success Response

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

Sample JSON Failure Response

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

Scenario: Amendment=Date

Below are the sample json details of various use-cases in case the amended field is Date change

Sample JSON Request:

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

Sample JSON Success Response for Refund scenario

{
  "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
    }
  }
}

Sample JSON Success Response for Additional Charge scenario

{
  "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
    }
  }
}

Sample JSON Failure Response

{
  "status": "400",
  "errorMessage": {
    "id": "909",
    "subId": "132",
    "message": "There is no available inventory for booking"
  }
}

ConfirmAmendment API

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

Request Field Details (Required = *)

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

Element	Attribute	Description
bookingId* Integer		Booking id, number only
amendmentDetails	amendmentIdentifier* String	Amendment identifier value returned in the Amendment response
amendmentDetails	amendmentType* Integer	enum int of the param to be updated. Allowed values: 1 - for Date change amendment 2 - for Guest Info change Amendment 3 - Special Request amendment
Needed only for Date change Amendment - additional payment required scenario
paymentDetails > creditCardInfo	cardType* String	Possible values for the cardType field are: Visa MasterCard JCB AmericanExpress CarteBleue Discover Note: Discover card is not available for all partners. Please get confirmation from Agoda. Refer to the appendix document for accepted currencies per payment card section. If cardType is Discover, please also see countryOfIssue and issuingBank elements. For CC partners, you should send paymentDetails, including cardType, number, expiryDate, cvc, holderName, and countryOfIssue. For Invoice partners, please keep paymentDetails blank.
paymentDetails > creditCardInfo	number* String	Credit card number will consist of 15 or 16 digits. Each digit can be 0-9
paymentDetails > creditCardInfo	expiryDate* String	Expiry Date in the format MMYYYY. Each character can be 0-9
paymentDetails > creditCardInfo	cvc* String	CVC code consisting of 3-4 digits. Each digit can be 0-9.
paymentDetails > creditCardInfo	holderName* String	Cardholder name
paymentDetails > creditCardInfo	countryOfIssue* String	ISO Code
paymentDetails > creditCardInfo	issuingBank* String	If cardType=Discover, please send Discover in this element

Success Response Field Details (Required = *)

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

Element	Attribute	Description
bookingId Integer		Booking id, number only
status* Integer		Status code
amendmentStatus String		Amendment status (applicable only for Name change / Date change amendment) Possible Values - Confirmed / Rejected / Pending / Cancelled
amendmentId Integer		Reference ID for the amendment (applicable only for Name change / Date change amendment)

Failure Response Field Details (Required = *)

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

Element	Attribute	Description
status* Integer		Status code
errorMessage	id String	Error message ID
	subId String	Error subId to identify the exact sub system error
	message String	Message provided in case of error only

Scenario: Amendment=Guest Info

Below are the sample json details of various use cases in case the amended field is Guest Info.

Sample JSON Request:

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

Sample JSON Success Response

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

Sample JSON Failure Response

{
  "status": "400",
  "errorMessage": {
    "id": "503",
    "subId": "7112",
    "message": "Unable to update the guest name"
  }
}

Scenario: Amendment=SpecialRequest

Below are the sample json details of various use cases in case the amended field is specialRequest.

Sample JSON Request:

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

Sample JSON Success Response

{
  "bookingId": 66788065,
  "status": "200"
}

Sample JSON Failure Response

{
  "status": "400",
  "errorMessage": {
    "id": "909",
    "message": "Site id is not matched. booking id: 80000040 site id: 1888679"
  }
}

Scenario: Amendment=DateChange

Below are the sample json details of various use cases in case the amended field is date change.

Sample JSON Request:

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

Sample JSON Success Response

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

Sample JSON Failure Response

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