Frontend API Change Impact Guide

This guide summarizes what frontend consumers need to change after recent pricing/import updates.

⚠️ Deprecation Note

• Admin PUT /v1/itinerary/:id/pricing-selection should no longer be called.
• For admin pricing changes, call PUT /v1/itinerary/:id/pricing-table.
• For customer quote recalculation/save, use POST /v1/bookings with required pricingSelection block.

Scope

Applies to:

• pricing page flows (admin + customer)
• full import itinerary flow
• inventory pre-check/search flows for hotel/transfer

---

1) Pricing API updates

1.1 Admin vs Customer write endpoints

Use separated admin/customer write paths:

• Admin pricing-master update: PUT /v1/itinerary/:id/pricing-table (JWT + TRIP permission)
• Customer selection save: POST /v1/bookings with required pricingSelection (booking-jwt)

Booking create integration:

• POST /v1/bookings now requires pricingSelection payload (b2c) and computes booking.priceDetails from it.
• If pricingSelection is missing, booking create fails validation.

Both return pricing response in the same shape as GET /v1/itinerary/:id/price-details.

Usage split:

• PUT /pricing-table: update base pricing rows/slabs (rate card)
• POST /bookings pricingSelection: update customer selection only (category/slab/travelers/channel)
• In activities_only, customer selection request must send only traveler counts; activity prices are admin-managed via /pricing-table.

1.2 Category values

Category fields are numeric enum values (not string labels) — HotelCategoryEnum (src/shared/enums/hotel-category.enum.ts):

• 1 = LUXURY
• 2 = PREMIUM
• 3 = SUPER_DELUXE
• 4 = DELUXE
• 5 = STANDARD

For hotel_transfer and hotel_only scenarios, availableCategories in the price-details response always returns all five values [1,2,3,4,5]. Use categoryPerPersonPrices to determine which categories have actual pricing rows.

1.3 Slab banding rule

Vehicle slab auto-selection uses adults + children (extraMattressCount/childrenWithBed and infants are excluded from slab banding):

• Finds the slab where capacityMin ≤ totalPax ≤ capacityMax
• Falls back to the first row if no slab matches
• Typical example: <= 3 pax → selects 1-3 slab; > 3 pax → selects 4-N slab

1.3.1 B2B category lock rule

• In admin/b2b price-details flow (channel=b2b or omitted), the pricing summary category is derived from itinerary tripType via normalizeTripTypeToCategory().
• selectedCategory query param is ignored for b2b summary computation.
• The b2b summary includes markupPercent, markupType, markupValue, and markupAmount as separate fields.
• The b2b summary's baseCost is the raw cost before markup is applied.

1.4 defaultHotelCategory removed

• Do not read or send defaultHotelCategory.
• Use tripType as canonical category source.

1.5 Markup source changed

• Pricing no longer relies on fixed global constant markup.
• Markup is resolved at query time from the Markup entity per itinerary (never stored in pricing rows):
  • Itinerary-specific markup (most recently updated active non-deleted record for this itinerary) → highest priority
  • Global all-trips markup (isGlobal=true) → fallback
  • No markup → price returned at base cost
• GST is resolved from a separate Markup record with category='gst', same priority order. When GST is not configured, gstPercent and gstAmount in the summary are null, not 0.
• Both markup types are supported: FLAT (type=1) and PERCENTAGE (type=2).

1.6 Booking channel must be b2c

• POST /v1/bookings validates that pricingSelection.channel is "b2c" or omitted.
• Sending channel: "b2b" in a booking request returns ERR_BOOKING_PRICING_CHANNEL_MUST_BE_B2C.
• The channel is automatically forced to "b2c" inside the booking service regardless.

---

2) Import Full Itinerary payload updates

Endpoint: POST /v1/itinerary/import-itinerary-full

2.1 Inventory references

Use IDs only:

• hotelIds: number[]
• transferIds: number[]

Do not send old hotels[] / transfers[] create-resolve payloads.

2.2 Activities

activities[] are created and mapped day-wise.

Required fields per item:

• dayOrder (number)
• title (string)
• startTime (string, mandatory)

Optional fields:

• duration (minutes)
• description, catgType, subCatgType, activityType, latitude, longitude

2.3 Hotel day-wise mapping

Explicit mapping supported via:

• hotelDayMappings: [{ hotelId, dayOrder }]

Validation:

• day must exist
• hotel must exist
• day location must match hotel city/location

Backward compatibility:

• if hotelDayMappings is omitted, backend maps hotel to all itinerary days with matching location.

2.4 Transfer mapping

• Transfer remains itinerary-wise only (not day-wise).

---

3) Inventory APIs response enrichments

3.1 Hotel inventory responses (import-related)

For check-inventory, search-inventory, and inventory responses, hotel objects now include:

• id, name, cityId, category
• address, description, starRating, checkInTime, checkOutTime, roomType

POST /v1/hotel/check-inventory also returns:

• hotels: [] (all matched priority-name hotels)
• hotel (first match for backward compatibility)

3.2 Transfer inventory responses (import-related)

For check-by-name, search, and inventory responses, transfer objects now include:

• id, vehicleName, vehicleType, seater
• description, notes, isActive, createdAt, updatedAt

POST /v1/transfer/check-by-name request is bulk:

{ "items": [{ "name": "Wagon R / Similar" }, { "name": "Innova / Similar" }] }

Response includes requestedName per item.

Transfer update validation:

• If transfer seater/capacity is being changed and transfer is mapped to any itinerary, update is blocked.
• User must first unmap the transfer from itineraries, then update seater.

---

4) Existing GET APIs and break-risk

The following endpoints are not route-changed by these updates:

• GET /v1/itinerary/agent
• GET /v1/itinerary
• GET /v1/itinerary/:id
• GET /v1/hotel/itinerary/:id
• GET /v1/transfer/itinerary/:id/transfers
• GET /v1/days/itinerary-details/:id

Potential response/data adjustments frontend should tolerate:

• defaultHotelCategory field removal
• updated tripType category interpretation
• richer day-wise hotel/activity data for newly imported itineraries

---

5) Markup management APIs (admin)

Base: /v1/markup

• POST /v1/markup create markup
• PUT /v1/markup/:id update markup
• DELETE /v1/markup/:id soft delete markup
• GET /v1/markup list markups
• GET /v1/markup/:id get markup details
• GET /v1/markup/unmapped-itineraries list trips not mapped in any specific markup

Behavior rules:

• trip can belong to only one specific markup (tenant scope)
• one all-trips markup per tenant
• all-trips markup cannot be deleted (only update)
• list/detail responses include normalized appliesTo structure:
  • ALL_TRIPS
  • SPECIFIC_TRIPS with tripIds and trips[]

5.1 Create specific-trip markup

POST /v1/markup

{
  "name": "Summer promo - selected trips",
  "isGlobal": false,
  "itineraryIds": [948, 950, 958],
  "type": 2,
  "amount": 7.5,
  "notes": "Percentage markup for selected trips",
  "isActive": true
}

5.2 Create all-trips markup

POST /v1/markup

{
  "name": "Default all-trips fallback",
  "isGlobal": true,
  "type": 1,
  "amount": 1200,
  "notes": "Flat fallback markup for all trips",
  "isActive": true
}

5.3 Update markup

PUT /v1/markup/:id

{
  "name": "Summer promo - revised",
  "isActive": true,
  "type": 2,
  "amount": 8.25,
  "notes": "Revised percentage",
  "addItineraryIds": [970],
  "removeItineraryIds": [950]
}

5.4 Normalized list/detail response (appliesTo)

{
  "id": 12,
  "name": "Summer promo - revised",
  "isGlobal": false,
  "type": 2,
  "amount": "8.25",
  "isActive": true,
  "appliesTo": {
    "type": "SPECIFIC_TRIPS",
    "tripIds": [948, 958, 970],
    "trips": [
      { "id": 948, "name": "Sikkim Delight" },
      { "id": 958, "name": "North East Premium" },
      { "id": 970, "name": "Bhutan Escape" }
    ]
  }
}

For all-trips markup:

{
  "appliesTo": {
    "type": "ALL_TRIPS",
    "tripIds": [],
    "trips": []
  }
}

---

6) Hotel mapping + primary + category update rules

6.1 checkInTime is optional in hotel create/update forms

• Frontend should no longer enforce checkInTime as mandatory.
• For create/update payloads, checkInTime can be omitted.

6.2 Scoped primary rule (important)

Primary uniqueness is now enforced within:

• itineraryId + locationId + category

Frontend requirements:

• Prefer sending locationId and category in POST /v1/hotel/map-itinerary.
• Send locationId and category in PATCH /v1/hotel/primary.

Example:

{
  "hotelId": 647,
  "itineraryId": 948,
  "locationId": 12,
  "category": 1,
  "isPrimary": true
}

Error handling:

• If PATCH /v1/hotel/primary is ambiguous without scope, backend can return:
  • ERR_HOTEL_PRIMARY_SCOPE_REQUIRED

6.3 Hotel category update guard for published itineraries

When updating hotel category (categoryId) in hotel update API:

• If hotel is mapped to any published itinerary, update is blocked.
• User must unpublish those itineraries first.

Error returned:

• ERR_HOTEL_CATEGORY_CHANGE_REQUIRES_UNPUBLISH

6.4 Mapping category sync behavior

• On allowed hotel category update, backend syncs hotel_itinerary_mapping.category for that hotel’s mappings.
• No additional frontend API call is needed for this sync.

---

7) Tenant media URLs API

Endpoint:

• POST /v1/multi-tenancy/tenant-media-urls

Auth/headers:

• JWT required (Authorization: Bearer <token>)
• tenant header required by middleware (tenantId)

Request body:

{
  "tenantId": 1
}

Response highlights:

• message = SUC_TENANT_MEDIA_URLS_FETCHED
• data.mediaByBucketFolder grouped by S3BucketTypeEnum folder keys
• data.summary.totalFolders
• data.summary.totalMediaItems
• data.sourceErrors[] for best-effort source-level failures

Option C URL resolution rule:

• If filename is present/derivable, backend returns rebuilt URL:
  • <awsS3BaseUrl>/<folder>/<fileName>
• If filename is missing, backend falls back to stored DB link.
• Each item includes fallbackLinkUsed to indicate fallback behavior.

Negative cases:

• Invalid payload (tenantId <= 0) -> validation error
• Unknown tenant -> ERR_TENANT_NOT_FOUND&&&tenantId

---

8) Frontend checklist

• Send customer pricing selection in POST /v1/bookings under pricingSelection
• Use admin pricing master save on PUT /v1/itinerary/:id/pricing-table
• Send numeric category enums (1..5), not labels
• Update import payload to hotelIds, transferIds, activities, optional hotelDayMappings
• Include startTime for each imported activity
• Handle enriched hotel/transfer response fields
• Remove any usage of defaultHotelCategory
• Treat hotel checkInTime as optional in create/update forms
• Send locationId + category when calling PATCH /v1/hotel/primary
• Handle ERR_HOTEL_CATEGORY_CHANGE_REQUIRES_UNPUBLISH on hotel category updates
• Integrate POST /v1/multi-tenancy/tenant-media-urls and consume grouped mediaByBucketFolder