API amendments workflow: a step-by-step guide

1. Booking details (bookingDetails)
   Update travel date / time / product option
2. Passenger mix (updatePaxMix)
   Add/remove travelers
3. Booking questions per traveler (perTravelerQuestions)
   Update questions per traveler (passport, DOB, etc.)
4. Booking questions per booking (perBookingQuestions)
   Amend questions per booking (pickup point, etc.)

1. Lead traveler (the name on the voucher) – unsupported when a product doesn’t have booking questions FULL_NAMES_FIRST and FULL_NAMES_LAST.
2. Language guides
3. Special requirements
4. Bookings confirmed for manual confirmation type products.
5. Bookings confirmed for products with a mix of instant and manual confirmation types when it’s past cutoff time (in the initial booking).
6. Merchant partners only: Supplier-driven amendments that require approval from a merchant partner. When such an amendment is initiated, the merchant partner will receive an email notification requesting approval or rejection. The response must be provided via email.

Check booking amendability

• This endpoint returns information on whether a booking is amendable and lists the elements that can be changed.
• The request must include the Viator booking reference (bookingRef)
• isAmendable field will determine if booking can be amended, based on the eligibility criteria.
                     – Manual confirmation type products cannot be amended (if confirmationType = MANUAL, isAmendable = false).
                     – Products with a mix of instant and manual confirmation types cannot be amended past cutoff time (if INSTANT_THEN_MANUAL, isAmendable = false past cutoff time – you can read about booking cutoff times here).
                     – If isAmendable is returned as false, the ineligibility reason will be returned. Otherwise, it will be absent.
• The paxMixSummary object will match all travellers in the paxMix with a unique identifier and inform which booking questions have been answered for each.
                     – travelerNum field is crucial in the amendment process to identify which traveler is to be amended or removed from the booking.
                     – travelerNum sent by partners during the booking flow will be reused. When travelerNum is not sent by partners (when the product has no booking questions), it’ll be generated automatically.
                     – Only returned if amendmentTypes = UPDATE_PAX_MIX or PER_TRAVELER_QUESTIONS.
                     – paxMixSummary.bookingQuestions will return all answers provided by the partner at the time of the booking and null if the booking question was not answered.
• Only one amendment type per request is allowed
                     – amendmentTypes vary depending on the product. eg: if product has no per-person booking questions, PER_TRAVELER_QUESTIONS won’t be returned.

Check the cost of the amendment

• Provides a detailed quote for the requested amendment, including pricing.
• Only one amendment type per request is allowed: eg. either BOOKING_DETAILS or UPDATE_PAX_MIX.
                     – The amendment type to perform will be inferred from the request information sent
                     – If multiple amendment types are sent in the /quote request, /quote will fail.
• The quote will reflect the intended final state of the booking. The data submitted in /quote will be applied when executing the /amend.
• The /quote does NOT hold availability or pricing.
• quoteRef is the unique identifier of each /quote
                     – It stores all the information to be used for amendment.
                     – It expires every 10 minutes. Partners should rely on the timeStamp field for quoteRef expiry date/time and must request a new quote after that period.
                     – An amendment cannot be made without an existing quoteRef.
                     – Multiple active quoteRef per bookingRef are allowed – if one of them succeeds, the others are deemed as expired.
                     – Do not use outdated quoteRef when executing the /amend (which could result in price mismatches).
                     – The same quoteRef can be reused if rejected in the /amend but still within expiry period.
• All bookingQuestions must be answered when adding new travelers or when editing existing travelers and new questions have been added to the product (partners can verify this at /check step in paxMixSummary)
                     – Relevant API validations apply, i.e. if unit is required, it must be provided. Read more about the implementation of booking questions in this guide: Implementing Booking Questions.
• The price information returned in the response consists of:
  – initialBookingPrice – returns the value paid in the initial booking (before the amendment)
  – quotePriceDifference – the price of the amendment: the price of the requested changes vs the price paid in the initial booking.
  – amendedBookingPrice shows the final view of the booking, if amendment succeeds – it includes lineItem price and totalPrice.

Please note:
                   – The price quotePriceDifference value may be negative (ie, generate a refund).
                   – For markup merchants, quotePriceDifference is purely calculated based on partnerNetPrice.
                   – In case of discounted pricing, price before discount is not returned for amended bookings.
                   – Booking fee is currently not being charged nor refunded when price changes.
                   – You can find more details on how pricing should be handled in this guide: Calculating Product Pricing.

• voucherFormat details will be returned in HTML if not specified in /quote request
• Full + Booking Access Affiliates only: The last four digits of the previously charged card will be returned in the response under paymentMethod to confirm the payment method. The same card will be used to process the amendment and cannot be changed.

Execute the emendment

• This endpoint is used to process the amendment requested in /amendment/quote. This step should be made right after /amendment/quote.
• The quoteRef must be passed in the request – it carries over all information needed for the amendment.
• voucherInfo details will be returned in HTML if not sent in /quote request.
• In case of discounted pricing, price before discount is not returned for amended bookings.
• Amendment status is returned in the response to this endpoint. Possible amendmentStatus values:
             – AMENDED
            – REJECTED
            – PENDING
• Amendment will be rejected if:
            – Price/availability at the time of the /amend is different from the /quote
            – Product becomes ineligible for amendment
• When the amendment is rejected, a relevant rejectionReasonCodes will be returned.
            – All possible rejectionReasonCodes values can be found in the documentation.
• In case of a PENDING amendment status, status updates should be polled using the /bookings/status endpoint – following the recommended frequency of updates from the nextPollAt timestamp.
• Full + Booking Access Affiliates only: Additional charges or refunds related to amendments will be processed via the original payment method (confirmed under paymentMethod). The payment method cannot be changed for processing amendments.

Check for updates on the amendment status

• This endpoint is used to verify updates for PENDING amendments.
• The status of the booking (status) is returned separately from the amendment status (amendmentStatus).
• amendmentStatus will always reflect the latest amendment attempt status. For example, if a booking was successfully amended once, but a second amendment request was submitted and then rejected, the response will return “amendmentStatus”: “REJECTED”.
• When the amendment is rejected, a relevant rejectionReasonCodes will be returned.
                   – All possible rejectionReasonCodes values can be found in the API documentation.
• The price information returned in the response consists of:
                   – initialBookingPrice – returns the value paid in the initial booking (before the amendment)
                   – quotePriceDifference – the price of the amendment: the price of the requested changes vs the price paid in the initial booking.
                   – amendedBookingPrice shows the final view of the booking, if amendment succeeds – it includes lineItem price and totalPrice.

Please note:
                 – The price quotePriceDifference value may be negative (ie, generate a refund).
                 – For markup merchants, quotePriceDifference is purely calculated based on partnerNetPrice.
                 – In case of discounted pricing, price before discount is not returned for amended bookings.
                 – Booking fee is currently not being charged nor refunded when price changes.
                 – You can find more details on how pricing should be handled in this guide: Calculating Product Pricing.

Please read more about the rules applicable to the usage of this endpoint in our Technical guide.