Pricing APIs

Frontend integration contract for itinerary pricing flows.

⚠️ Deprecation Note

• PUT /v1/itinerary/:id/pricing-selection (admin) is deprecated/removed from admin flow.
• Admin must use PUT /v1/itinerary/:id/pricing-table for pricing updates.
• Customer pricing selection is now merged into POST /v1/bookings via required pricingSelection payload.

Removed in current release

• PUT /v1/itinerary/:id/customer-pricing-selection has been removed.
• Migration path: send customer selection in POST /v1/bookings under pricingSelection.

Base

• Base path: /v1/itinerary
• Auth: Bearer JWT (except public lead pricing endpoint)

Category enum values

Pricing categories use HotelCategoryEnum numeric values (src/shared/enums/hotel-category.enum.ts):

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

Markup type values (MarkupTypeEnum):

• 1 = FLAT
• 2 = PERCENTAGE

Discount type values (DiscountTypeEnum, when present in summary):

• 1 = FLAT
• 2 = PERCENTAGE

---

1) GET /v1/itinerary/:id/price-details

Source of truth for pricing table mode, defaults, and summary.

Supported query params

• adults (number)
• children (number)
• extraMattressCount (number; pricing-only, excluded from traveler/slab count)
• selectedCategory (number enum value; applied in customer/b2c flow)
• selectedTransferId (number)
• selectedVehicleName (string)
• selectedCapacityMin (number)
• selectedCapacityMax (number)
• includeDinnerSupplement (true/false)
• channel (b2b or b2c)

GET /price-details recalculates summary from the supplied query params (selection context) in real time.

Compatibility: legacy query params childrenWithoutBed and childrenWithBed are still accepted as aliases for children and extraMattressCount.

Common response envelope

{
  "message": "SUC_PRICE_DETAILS_FETCHED",
  "data": {
    "itineraryId": 958,
    "pricingTableType": "hotel_transfer",
    "mappingSnapshot": {
      "hasActivities": true,
      "hasHotels": true,
      "hasTransfers": true
    },
    "defaultCategory": 5,
    "availableCategories": [1, 2, 3, 4, 5],
    "selection": {
      "selectedCategory": 5,
      "selectedVehicleSlab": {
        "transferId": 3002,
        "vehicleName": "Innova / Xylo / Similar",
        "capacityMin": 1,
        "capacityMax": 3
      },
      "travelerDetails": {
        "adults": 2,
        "children": 1,
        "infants": 0
      },
      "extraMattressCount": 0,
      "includeDinnerSupplement": false,
      "displayMode": 1
    },
    "pricingTable": {},
    "summary": {
      "channel": "b2b",
      "currency": "INR",
      "baseCost": 0,
      "gstPercent": 5,
      "gstAmount": 0,
      "tcsPercent": 0,
      "tcsAmount": 0,
      "discountType": 1,
      "discountValue": 0,
      "discountAmount": 0,
      "grandTotal": 0,
      "tcsApplicable": false,
      "markupPercent": 5,
      "markupType": 2,
      "markupValue": 5,
      "markupAmount": 0
    }
  }
}

---

2) pricingTable by scenario

A) activities_only

{
  "pricingTableType": "activities_only",
  "pricingTable": {
    "activitiesOnly": {
      "adultPrice": 5000,
      "childPrice": 2000
    }
  }
}

B) hotel_only

{
  "pricingTableType": "hotel_only",
  "pricingTable": {
    "categoryPerPersonPrices": [
      {
        "category": 5,
        "perPersonPrice": 15100,
        "primaryMappedHotelName": "Taj City Center"
      },
      {
        "category": 2,
        "perPersonPrice": 18400,
        "primaryMappedHotelName": null
      }
    ],
    "hotelRows": [
      {
        "category": 5,
        "pricePerPerson": 15100,
        "plan": "CP",
        "extraBedPrice": 4050,
        "childWithoutBedPrice": 2100,
        "dinnerSupplementPrice": 1950
      },
      {
        "category": 2,
        "pricePerPerson": 18400,
        "plan": "CP",
        "extraBedPrice": 5500,
        "childWithoutBedPrice": 3800,
        "dinnerSupplementPrice": 2400
      }
    ]
  }
}

C) transfer_only

{
  "pricingTableType": "transfer_only",
  "pricingTable": {
    "transferRows": [
      {
        "transferId": 3001,
        "vehicleName": "Wagon R / Similar",
        "capacityMin": 1,
        "capacityMax": 3,
        "pricePerPerson": 15100
      },
      {
        "transferId": 3002,
        "vehicleName": "Innova / Xylo / Similar",
        "capacityMin": 1,
        "capacityMax": 3,
        "pricePerPerson": 18400
      },
      {
        "transferId": 3002,
        "vehicleName": "Innova / Xylo / Similar",
        "capacityMin": 4,
        "capacityMax": 6,
        "pricePerPerson": 12350
      }
    ]
  }
}

D) hotel_transfer

{
  "pricingTableType": "hotel_transfer",
    "pricingTable": {
      "categoryPerPersonPrices": [
        {
          "category": 5,
          "perPersonPrice": 15100,
          "primaryMappedHotelName": "Taj City Center"
        }
      ],
      "rows": [
        {
        "category": 5,
        "plan": "CP",
        "extraBedPrice": 4050,
        "childWithoutBedPrice": 2100,
        "dinnerSupplementPrice": 1950,
        "vehiclePricing": [
          {
            "transferId": 3001,
            "vehicleName": "Wagon R / Similar",
            "capacityMin": 1,
            "capacityMax": 3,
            "pricePerPerson": 15100
          },
          {
            "transferId": 3002,
            "vehicleName": "Innova / Xylo / Similar",
            "capacityMin": 1,
            "capacityMax": 3,
            "pricePerPerson": 18400
          },
          {
            "transferId": 3002,
            "vehicleName": "Innova / Xylo / Similar",
            "capacityMin": 4,
            "capacityMax": 6,
            "pricePerPerson": 12350
          }
        ]
      }
    ]
  }
}

---

3) Customer pricing selection via booking create

Customer write path:

• Customer: POST /v1/bookings (booking-jwt)
  • requires pricingSelection payload
  • computes and stores pricing snapshot on booking (booking.priceDetails)

Request (pricingSelection block inside booking payload)

{
  "channel": "b2c",
  "selectedCategory": 5,
  "selectedVehicleSlab": {
    "transferId": 3002,
    "vehicleName": "Innova / Xylo / Similar",
    "capacityMin": 1,
    "capacityMax": 3
  },
  "travelerDetails": {
    "adults": 2,
    "children": 1,
    "infants": 0
  },
  "extraMattressCount": 0,
  "includeDinnerSupplement": true,
  "displayMode": 1
}

Response

Booking response includes booking.priceDetails in same structure as GET /price-details with recalculated summary.

Notes:

• selectedCategory is meaningful for hotel-involved flows.
• selectedVehicleSlab is meaningful for transfer-involved flows.
• Backward compatibility: pricingSelection.travelerDetails.childrenWithoutBed and pricingSelection.travelerDetails.childrenWithBed are accepted as legacy aliases.
• vehiclePricing[] and transferRows[] include transferId for transfer reference binding.
• In pricingSelection.travelerDetails, children and infants are optional; pricing computation uses adults + children for traveler/slab count.
• extraMattressCount is pricing-only and must be sent outside travelerDetails.
• In hotel_transfer and hotel_only, pricingTable.categoryPerPersonPrices provides category-wise per-person prices (markup included, dinner supplement excluded) for category card display, plus primaryMappedHotelName for that category.
• In hotel_only, each pricingTable.hotelRows[] now also includes pricePerPerson for table column rendering.
• In b2c channel for hotel_transfer and hotel_only, categories with perPersonPrice = 0 are omitted from categoryPerPersonPrices.
• If no primary mapped hotel exists for a category, primaryMappedHotelName is null.
• Bundle pricing capacity rows require transferId; vehicle name is resolved from transfer master.
• Capacity bands are stored in bundle pricing rows (not derived from transfer in response):
  • always include 1-3
  • if transfer seater > 3, also include 4-seater
• In activities_only, customer selection does not accept activity prices; prices come from admin pricing-table config.
• Do not send pricingTable.rows (or any rows) in pricingSelection; selection inputs only.

---

4) PUT /v1/itinerary/:id/pricing-table (admin only)

Upsert pricing master rows (rate card) for each scenario.

• Auth: JWT + TRIP permission
• Purpose: update base price table values (not traveler selection)
• Admin pricing table updates are b2b configuration operations.

A) hotel_transfer payload

{
  "scenario": "hotel_transfer",
  "rows": [
    {
      "category": 5,
      "plan": "CP",
      "extraBedPrice": 4050,
      "childWithoutBedPrice": 2100,
      "dinnerSupplementPrice": 1950,
      "vehiclePricing": [
        {
          "transferId": 3001,
          "capacityMin": 1,
          "capacityMax": 3,
          "pricePerPerson": 15100
        }
      ]
    }
  ]
}

B) hotel_only payload

{
  "scenario": "hotel_only",
  "hotelRows": [
    {
      "category": 5,
      "pricePerPerson": 15100,
      "plan": "CP",
      "extraBedPrice": 4050,
      "childWithoutBedPrice": 2100,
      "dinnerSupplementPrice": 1950
    }
  ]
}

C) transfer_only payload

{
  "scenario": "transfer_only",
  "category": 5,
  "transferRows": [
    {
      "transferId": 3001,
      "capacityMin": 1,
      "capacityMax": 3,
      "pricePerPerson": 12000
    }
  ]
}

category is optional for transfer_only; if omitted, backend resolves category from: dto.category → basePriceDetails.defaultCategory → basePriceDetails.availableCategories[0] → HotelCategoryEnum.STANDARD (5).

D) activities_only payload

{
  "scenario": "activities_only",
  "displayMode": 1,
  "activitiesOnly": {
    "adultPrice": 5000,
    "childPrice": 2000
  }
}

Response (all scenarios)

{
  "message": "SUC_PRICING_TABLE_SAVED",
  "data": {
    "itineraryId": 958,
    "pricingTableType": "hotel_transfer",
    "pricingTable": {},
    "selection": {},
    "summary": {}
  }
}

Notes:

• This endpoint updates the pricing master table.
• POST /bookings pricingSelection updates customer selection inputs and recalculates totals.
• Do not mix both concerns in one request.

---

5) B2B/B2C summary behavior

• channel = "b2b" (default when channel is omitted)
  • Category is locked to itinerary tripType (normalizeTripTypeToCategory); selectedCategory query param is ignored for summary computation.
  • summary includes markupPercent, markupType, markupValue, markupAmount as separate fields in addition to gstAmount, tcsAmount, discountAmount.
  • summary.baseCost = raw base cost before markup.
• channel = "b2c"
  • Customer category selection (selectedCategory) is honored; defaults to itinerary tripType or first available category.
  • In hotel_transfer, selected category drives transfer slab lookup from that category's bundle rows.
  • summary.baseCost = post-markup amount (markup has been folded into the base).
  • markupPercent, markupType, markupValue, markupAmount are not included in summary.
  • gstAmount, tcsAmount, discountAmount are still returned separately.
  • gstPercent and gstAmount are null (not 0) when no GST is configured.
  • categoryPerPersonPrices rows where perPersonPrice = 0 are omitted in b2c response.

---

6) Other related pricing endpoints

A) GET /v1/itinerary/price-details/:leadId/:tripId

Public lead pricing endpoint.

B) GET /v1/itinerary/:id/customer-price-details

Customer-token variant of itinerary price-details endpoint.

C) PUT /v1/itinerary/:id/travelers

Saves the default traveler/pax configuration on the itinerary (adults, children, infants, selectedCategory, selectedVehicleSlab, extraMattressCount, includeDinnerSupplement, displayMode). These defaults are used when displaying a trip with no customer-supplied selection context.

This endpoint remains active. For customer booking price snapshots, use POST /bookings with pricingSelection.

---

7) Rules for frontend consumers

• tripType is the canonical category source for b2b channel. For b2c, selectedCategory from query/selection is used.
• For hotel_transfer and hotel_only, availableCategories in the response contains all HotelCategoryEnum values [1,2,3,4,5] sorted ascending — not just those with pricing rows. Filter categoryPerPersonPrices to find which categories actually have pricing.
• For transfer_only and activities_only, availableCategories is derived from existing bundle pricing categories + tripType.
• Transfer pricing is category-agnostic; the same vehicle slabs apply regardless of selected hotel category.
• Markup is pulled from tenant markup inventory per itinerary at query time (never stored in pricing rows):
  • Priority: itinerary-specific markup (most recently updated) → global all-trips markup → no markup (price returned as-is)
  • Supports both PERCENTAGE (type 2) and FLAT (type 1) markup types
• GST is resolved separately from the Markup entity with category = 'gst':
  • Priority: itinerary-specific GST (MAX when multiple) → global GST → no GST (null in summary)
• TCS (2%) applies only to international itineraries (any day location, hotel city, or flight airport outside India IN).
• Capacity slab auto-selection uses adults + children count (extraMattressCount and infants excluded from slab banding):
  • Finds row where capacityMin ≤ totalPax ≤ capacityMax
  • Falls back to first row if no match
• Default display order:
  • hotel_transfer: selected/default category hotel bundle + primary transfer vehicle slab.
  • hotel_only: selected/default category hotel bundle.
  • transfer_only: primary transfer pricing slabs.
  • activities_only: adultPrice and childPrice from travelerDetails.

---

8) Publish validation matrix

• hotel + transfer (+activities):
  • category required
  • hotel pricing for selected/default category required
  • primary transfer required
  • transfer pricing required
• hotel-only:
  • category required
  • hotel pricing for selected/default category required
• hotel_only and hotel_transfer (checked only when saving pricing table on a published itinerary):
  • For every category having a non-zero pricePerPerson in the submitted pricing payload, a hotel must be mapped to that itinerary for every unique locationId (day city) under that category. Checked in validatePublishedItineraryPricingCoverage().
• transfer-only:
  • primary transfer required
  • transfer pricing required
• activities-only:
  • adultPrice is mandatory