Archived V2 compatibility guide

Retired

V2 is retired from new integrations. Its endpoint is retained temporarily for existing callers. This archived guide documents that compatibility contract, including presentation reanchoring.

For new integrations, use the current API documentation and room mapping playground.

1. Submit your supplier offers

POST https://model.plexe.ai/v2/room-mappings
Headers: Authorization: Bearer <your existing key> and Content-Type: application/json.

hotelId is the same Plexe catalogue hotel ID used in V1. Keep supplier-specific room IDs and codes on the offers. V2 requires a catalogue ID; name-only hotel lookup is available through V1.

{
  "hotelId": "39626591",
  "view": "products",
  "includeRanking": true,
  "roomRates": [
    {
      "index": 0,
      "roomName": "Superior Room, 1 Queen Bed",
      "provider": "supplier-a",
      "nightlyPrice": 110,
      "currency": "INR",
      "beds": [
        "Queen"
      ]
    },
    {
      "index": 1,
      "roomName": "Superior Queen Room",
      "provider": "supplier-b",
      "nightlyPrice": 95,
      "currency": "INR"
    },
    {
      "index": 2,
      "roomName": "Twin Room, 2 Twin Beds",
      "provider": "supplier-a",
      "nightlyPrice": 105,
      "currency": "INR",
      "beds": [
        "Twin",
        "Twin"
      ]
    },
    {
      "index": 3,
      "roomName": "Twin Room",
      "provider": "supplier-b",
      "nightlyPrice": 100,
      "currency": "INR"
    },
    {
      "index": 4,
      "roomName": "Run of House",
      "provider": "supplier-c",
      "nightlyPrice": 80,
      "currency": "INR"
    },
    {
      "index": 5,
      "roomName": "Superior Room, 1 Queen Bed",
      "provider": "supplier-c",
      "nightlyPrice": 120,
      "currency": "INR"
    }
  ]
}

Illustrative suppliers and prices, not live availability. Original offer fields are retained. Room names and property evidence propose identities. Explicit supplier beds, views and descriptions are also checked before returning results, including cached results. Supplier room codes remain supplier-specific.

2. Handle 202 and poll until complete

A new job returns HTTP 202 with status: "pending", jobId, progress.stage and retryAfterSeconds. Wait that interval, then POST only the returned job ID to the same endpoint with the same key:

{"jobId": "<your returned job ID>"}

Continue until HTTP 200 with status: "completed". Cached requests can return 200 immediately. Cold jobs can take minutes. Polls do not consume the submission quota.

Stopping polling stops waiting in your client, not the server job. Resume polling with the same job ID to retrieve the result.

3. Render products and preserve every offer

FieldUse
cards[]Product cards by default, with productId, label, identityStatus, attributes and offers.
offers[].offerIndexZero-based position in your submitted array, even when supplier codes or IDs repeat.
offers[].offerYour complete original offer, including supplier, price and booking terms.
identityStatus: "insufficient"Unresolved identity. Keep these offers visible; a cheaper offer may be here.
view: "families"Fewer top-level cards with products[] inside. Keep each product separately selectable. Families are not guaranteed official categories or equivalent offers.

No room identity is claimed to be externally verified. Product IDs can change when the submitted inventory changes.

4. Understand content selection and reranking

Supplier offers + property catalogue
                  |
             Identity mapper
                  |
       Products with original offers
                  |
       Content selection + reranking
                  |
    Ordered products or family cards
       with every offer still available

The mapper determines product membership. The presentation layer then chooses useful content and orders the existing products and offers. Reranking cannot repair an incorrect identity mapping.

StepHow it worksRead from
Content-source selectionChoose one representative offer by search and preference fit, then information completeness. Ties keep the earlier input offer.Product ranking.contentSelection
Product rerankingOrder room choices using search/preference fit, completeness and comparable price.Top-level ranking.productOrder; product order and reasons
Offer orderingCheaper offers first within a compatible comparison group. Unknown or incompatible terms stay separate and available.Product ranking.offerOrder and comparableOfferGroups
Family browsingShow broader cards containing separately selectable products.view: "families" and products[]

Presentation reanchoring means choosing the source offer for the displayed details. There is no separate reanchor request flag. This source can differ from the cheapest offer; selecting it does not rename products or move offers between them.

Completeness considers stated beds, view, room size, room-specific images, landmark view, board basis, refundability and occupancy. Generic hotel images and unspecified views do not add room evidence. Requested features must coexist on one offer.

Example: two Queen Room offers have matching physical guarantees, stay and booking terms. Supplier A costs INR 8,000 per night; supplier B costs INR 8,400 and adds room photos. A stays first in their comparable group, while B can supply the selected content. Both remain available. These prices are illustrative; A does not automatically guarantee B's photos or unstated attributes.

Ranking defaults to enabled. Top-level ranking.productOrder gives display order. Each product's ranking.offerOrder refers to offer indexes. Ranking does not change room identities or remove offers. includeRanking: false disables it.

ranking.contentSelection on a product names one offerIndex and source-linked fields with appliesTo: "referenced_offer_only". Show those details as belonging to that offer; do not imply every offer guarantees the selected bed, view or photo. Shared mapper attributes remain in the card's attributes.

lowestObservedOffers records observed prices, not necessarily equivalent deals. Read priceComparison, comparableOfferGroups and missing price fields. Supply stay, occupancy, currency, tax basis and individual offer booking terms for meaningful comparison:

"rankingContext": {
  "currency": "INR", "checkIn": "2026-11-01", "checkOut": "2026-11-03",
  "occupancy": {"adults": 2, "childAges": []},
  "priceIncludesTaxesAndFees": true
},
"rankingPreferences": {"beds": "queen:1"}

Resubmit the full inventory with fresh prices and terms to refresh ranking and content selection. Mapping can reuse its identity cache while presentation is recomputed. Polling an old job returns that job's original snapshot.

This describes V2. Existing V1 and customer-specific routes retain their own behavior.

Compatibility and limits

Existing V2 clients use a 202/polling loop and render cards/offers instead of V1 groups. Tenant keys and catalogue hotel IDs retain their meaning. V1 feedback does not automatically apply to V2. New integrations should use the current API.

Per request: 1,000 offers, 600 distinct names and 256 KiB. Only submissions count against the daily quota. Missing or conflicted catalogues return unresolved supplier products with every offer retained; a job outside your tenant returns 404, and invalid keys return 401. Products and Families use the same identity and ranking policy.

Evaluate wrong merges and reduction on fresh hotels. The model does not guarantee zero errors.

Labels and request logs

Labels use supported catalogue names when available, otherwise supplier names. Read labelSource and labelAppliesTo. If a label applies to referenced_offer_only, its labelOfferIndex identifies the source; do not promise its attributes for every offer.

Completed and failed jobs update the same log automatically, even after you stop polling. Missing confidence means unknown. V1 and V2 submissions share your daily quota; polling is free.