Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceorders

Search orders

POST/v1/orders/search
Accepts X-Api-Key · oauthClientCredentials · bearer

Filter orders by clientReference, traveler, date, product, state

POST because filter objects outgrow query strings.Show morePOST because filter objects outgrow query strings. The crash-recovery entry point. Read-path failures: when the order store times out the answer is 502 UPSTREAM_UNAVAILABLE, retryable true (retry with backoff; nothing is written by a read); when the deployment has no order reader assembled it is 501 NOT_IMPLEMENTED, retryable false.

Request bodyOrderSearchRequest

  • contextMondeeContextRequired
    Request context envelope. domain selects the product; URL carries the verb.
    13 child attributes
    • domainstringRequired
      Canonical code or alias per the domain registry; unknown = 400 UNKNOWN_DOMAIN.Show moreCanonical code or alias per the domain registry; unknown = 400 UNKNOWN_DOMAIN. APTSVC (airport services: meet and assist, porter, buggy, wheelchair, concierge bundles) is registered by this release beside FASTTRK. FNB (dining: restaurant reservations; aliases REST, DINING, RESTAURANT, RESTAURANTS; category DO, money model FREE, artifact CONF_NUMBER, served under the dining service key with base path /v1/dining) is registered since v1.7.0. GIFT (gift cards; category SUPPORT, money model MERCHANT, artifact VOUCHER, served under the gift-cards service key with base path /v1/gift-cards) is described from v1.31.0: until the backend seam change merges, domain GIFT answers 400 UNKNOWN_DOMAIN. AICONT (the Example Content experience-scraping service's operations; category DO, money model MERCHANT, artifact NONE, served under the aicont service key with base path /v1/aicont; a content supplier) has its typed intent from v1.39.0; it answers only where its supplier set is landed and ACTIVE. PARK (airport and cruise-port parking; aliases PRK and PARKING; category SUPPORT, money model MERCHANT, artifact CONF_NUMBER — the supplier's gate barcode is the order's BARCODE document — served under the parking service key with base path /v1/parking) has its typed intent and its verb book from v1.55.0.
    • actionstringOptional
      Mirrors the verb; optional (server sets from route)
    • enricharray of stringOptional
      Opt-in enrichment on shopping answers: EMISSIONS | RATINGS | AMENITIES | ROUTE.Show moreOpt-in enrichment on shopping answers: EMISSIONS | RATINGS | AMENITIES | ROUTE. Absent = the tenant's configured default. Decoration reads cache or the pre-warmed store only and never delays the verb.
    • session_idstringOptional
      Your own id for the user session the call belongs to.
    • transaction_idstringOptional
      Constant across one shop-to-book journey
    • currencystringOptional
      ISO-4217; absent = tenant default; blank/invalid = 400
    • localestringOptional
      The language and region for text in the answer, as a BCP 47 tag (for example en-US).
    • posstringOptional
      Point-of-sale market, orthogonal to tenant
    • clientReferencestringOptional
      Caller's own id; searchable; the reconciliation primitive
    • fareSourcePolicystringOptional
      BYOC tenants only; narrows, never widens, the configured strategy
      • DEFAULT
      • OWN_ONLY
      • MONDEE_ONLY
      • BLEND
    • includeUpstreambooleanOptionalDefault false
      Ask for the supplier's own answer, verbatim, beside what the platform read from it: Offer.upstream on every offer of a search, poll, detail or flight-returns answer, AirReturnOption.upstream on each…Show moreAsk for the supplier's own answer, verbatim, beside what the platform read from it: Offer.upstream on every offer of a search, poll, detail or flight-returns answer, AirReturnOption.upstream on each listed return, RepriceResponse.message.upstream and OrderItem.upstream. Served only where the deployment enables upstream pass-through; elsewhere a true value is 400 VALIDATION details.reason UPSTREAM_PASS_THROUGH_DISABLED, details.field context.includeUpstream, before any supplier call. Absent or false, nothing changes. The block is informational: offerRef, repriceRef and price stay the only handles and the only price of record.
    • selectionSelectionPreferencesOptional
      context.selection: the caller's offer-selection preferences for this search.Show morecontext.selection: the caller's offer-selection preferences for this search. Each field set here replaces the tenant's and the platform's for this search, within the caller's entitlements and the platform's ceilings, unless the tenant has locked request overrides. It never widens reach: a preferred supplier the caller may not reach is ignored with context.warnings[] SELECTION_PREFERENCE_IGNORED. Ignored where selection is off.
      4 child attributes
      • viewstringOptional
        SELECTED (one entry per item, alternatives under the winner) or ALL (the flat list, tagged)
        • SELECTED
        • ALL
      • objectivestringOptional
        How the winner of an item is picked. CHEAPEST is the lowest comparison total; REFUNDABLE_FIRST the lowest total among offers free to cancel now (else CHEAPEST); PREFERRED_SUPPLIERS the first of…Show moreHow the winner of an item is picked. CHEAPEST is the lowest comparison total; REFUNDABLE_FIRST the lowest total among offers free to cancel now (else CHEAPEST); PREFERRED_SUPPLIERS the first of preferSuppliers with an offer inside the tenant's preference band (else CHEAPEST); PLATFORM_DEFAULT defers to the tenant and platform policies. Any other value is 400 VALIDATION details.field context.selection.objective.
        • CHEAPEST
        • REFUNDABLE_FIRST
        • PREFERRED_SUPPLIERS
        • PLATFORM_DEFAULT
      • preferSuppliersarray of stringOptional
        Supplier codes as in fareSource.supplier, most preferred first (PREFERRED_SUPPLIERS)
      • excludeSuppliersarray of stringOptional
        Supplier codes whose offers this search does not show; narrows only
    • onBehalfOfOnBehalfOfOptional
      Who a desk or agent books FOR: stamped into the audit actor and the clientReference lineage of the order.Show moreWho a desk or agent books FOR: stamped into the audit actor and the clientReference lineage of the order. Send customerId (a customer or traveller id the tenant knows) or traveler (a free-text identity), or both. Attribution only: it grants nothing, and the credential's own actor is still what authorises the call. Audit mapping: the audit actor.onBehalfOf (a string) is customerId when present, otherwise "traveler:<redacted-hash>" (a stable hash of traveler, never the text).
      2 child attributes
      • customerIdstringOptional
        A customer or traveller id your own system knows.
      • travelerstringOptional
        Free-text traveller identity when there is no customer id.Show moreFree-text traveller identity when there is no customer id. Personal data: it is logged redacted, never in clear. A card number in it is 400 VALIDATION details.reason INSTRUMENT_DATA_REFUSED.
  • messageobjectRequired
    1 child attribute
    • pageOrderSearchPageOptional
      Request paging for POST /v1/orders/search.Show moreRequest paging for POST /v1/orders/search. cursor is the context.page.nextCursor of the previous answer, unchanged; absent = the first page. limit caps the rows returned; the server applies its own default and maximum.
      2 child attributes
      • cursorstringOptional
      • limitintegerOptional

Responses

  • 200Paged order summariesOrderSearchResponse
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403
    AGENT_TIER_INSUFFICIENT, also 403, is a request whose agent tier does not allow the tool class; it carries nextAction verify_agent and details.tier, details.required, details.toolClass and…Show moreAGENT_TIER_INSUFFICIENT, also 403, is a request whose agent tier does not allow the tool class; it carries nextAction verify_agent and details.tier, details.required, details.toolClass and details.operationId. A ceiling only narrows an unverified caller and never widens a scope.
    ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug.Show moreNOT_IMPLEMENTED — honest fallback; every production 501 is a capabilities-doc bug. Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) on a deployment with no order reader assembled; not retryable.
    ApiErrorResponse
  • 502Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) when the order store times out: details.store names the store, retryable true.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
message.intent.checkOut must be after message.intent.checkIn
not retryable
400UNKNOWN_DOMAIN
Unknown domain 'HOTELS'. Did you mean HTL?
not retryable
401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Role lacks the required scope: booking:write
not retryable
403TAB_DISABLED
Tenant acme-travel is not entitled to sell CRU
not retryable
403OUT_OF_SCOPE
The token's scope ladder does not reach this customer subtree
not retryable
403TENANT_MISMATCH
orderRef MO-8KD-2FQ-9XT does not belong to tenant acme-travel
not retryable
405VALIDATION
This method is not served.
not retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
seatmap is NOT_APPLICABLE for HTL; GET /v1/capabilities says so
not retryable
502UPSTREAM_UNAVAILABLE
Every supplier for HTL is circuit-open; no fan-out was attempted
retryable