OffshoreFares API v2.0

B2B Flight Search, Booking & Ticketing — UAT: https://apiuat.offshorefares.com/v2

Booking Flow

1
Authenticate
POST /v2/auth/token
2
Search
POST /v2/flights/search
3
Revalidate
POST /v2/flights/revalidate_fares
4
Create PNR
POST /v2/flights/create_pnr
5
Create Order
POST /v2/flights/order
6
Order Status
POST /v2/flights/order_status
Headers on every request (except auth):
Authorization: Bearer <token>
X-Session: <sessionId>
Content-Type: application/json

1. Authentication

POST/v2/auth/token

Authenticate an affiliate account and retrieve a secure JWT session token. Returns a signed bearer token valid for 1 hour (3600s).

Request
200 Response
FieldTypeDescription
emailStringYesAffiliate email registered on OffshoreFares
api_keyStringYesUnique B2B API developer key issued to the partner
company_nameStringYesOfficially registered company name under the affiliate
curl
curl -X POST {{API_URL}}/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
  "email": "affiliate@travelpartner.com",
  "api_key": "offshore_pk_live_89c72e18fa4b",
  "company_name": "Global Travel Solutions Ltd"
}'
FieldTypeDescription
tokenStringSigned JWT bearer credential
tokenTypeStringAlways "Bearer"
expiresInIntegerToken validity in seconds (3600)
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

2. Flight Search

POST/v2/flights/search

Search available flights with pricing and itineraries. The response includes a sessionId that must be sent as the X-Session header on all subsequent calls. Sessions expire after 15 minutes of inactivity.

Request
200 Response
FieldTypeDescription
depCityStringYesOrigin airport IATA code (e.g. "BOM")
arrCityStringYesDestination airport IATA code (e.g. "DXB")
fromDateStringYesDeparture date — YYYYMMDD
retDateStringNoReturn date YYYYMMDD (round-trip only)
adultNumberIntegerYesAdult count (age ≥12), 1–9
childNumberIntegerYesChild count (age 2–11), 0–9
infantNumberIntegerYesInfant-on-lap count (age <2), 0–9
cabinClassStringYes"E" Economy, "P" Premium Economy, "J" Business, "F" First
stopsStringNo"" All, "0" Non-Stop, "1" 1-Stop, "2" 2+ Stops
exclAirlinesArrayNoIATA codes to exclude (e.g. ["AI","BA"])
inclAirlinesArrayNoIATA codes to restrict search to (e.g. ["YT"])
refundableBooleanNoFilter by refundable fare only
curl
curl -X POST {{API_URL}}/v2/flights/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "depCity": "BOM",
  "arrCity": "DXB",
  "fromDate": "20261114",
  "retDate": null,
  "adultNumber": 1,
  "childNumber": 0,
  "infantNumber": 0,
  "cabinClass": "E",
  "stops": "0",
  "exclAirlines": [],
  "inclAirlines": ["YT"],
  "refundable": true
}'
Response Envelope
FieldTypeDescription
statusString"SUCCESS" or "ERROR"
statusCodeIntegerHTTP status (e.g. 200)
msgStringHuman-readable processing message
sessionIdStringUnique session identifier — use as X-Session header moving forward
itinerariesArrayList of matching flight itinerary options

Itinerary Object

FieldTypeDescription
itineraryIdStringUnique identifier for this itinerary (e.g. "ITI_0ec3d1df3be...")
productTypeStringInventory tier — "PUB" (public GDS) or "OFF" (offshore special)
fareTypeStringBooking tier (e.g. "SAVER", "FLEX")
isRefundableBooleanWhether the itinerary allows cancellation refunds
journeysObjectContains onwardJourney and optional returnJourney
pricingBreakdownObjectMonetary summary: base, tax, fees, markup, discounts, totals
fareRulesObjectRefund and change penalty policies in local currency

Journey > Segment

{
  "segmentId":             Integer,
  "flightDurationMinutes": Integer,
  "carrier": {
    "marketing":           String,
    "operating":           String,
    "validating":          String,
    "aircraftCode":        String,
    "flightNumber":        String,
    "operatingFlightNumber": String
  },
  "departure": {
    "airport":             String,
    "terminal":            String,
    "dateTime":            String  // ISO 8601
  },
  "arrival": {
    "airport":             String,
    "terminal":            String,
    "dateTime":            String  // ISO 8601
  },
  "bookingDetails": {
    "cabinClass":          String,
    "rbd":                 String,
    "fareBasis":           String,
    "seatsRemaining":      Integer
  },
  "baggage": [{
    "passengerType":       String,  // "ADT", "CHD", "INF"
    "checkedPiece":        Integer,
    "checkedWeightKG":      String,
    "carryOnPiece":        Integer,
    "carryOnWeightKG":     Integer
  }],
  "otherFareRules":        Array
}

pricingBreakdown

{
  "currency":          String,   // e.g. "NPR"
  "baseFareTotal":     Number,
  "taxTotal":          Number,
  "feeTotal":          Number,
  "otherTotal":        Number,
  "markupTotal":       Number,
  "discountTotal":     Number,
  "gstTotal":          Number,
  "grandTotal":        Number,
  "passengerFares":    PassengerFare[]
}

PassengerFare

{
  "passengerType":          String,  // "ADT", "CHD", "INF"
  "count":                  Integer,
  "baseFarePerPassenger":   Number,
  "taxPerPassenger":        Number,
  "feePerPassenger":        Number,
  "otherPerPassenger":      Number,
  "markupPerPassenger":     Number,
  "gstPerPassenger":        Number,
  "discountPerPassenger":   Number,
  "totalPerPassenger":      Number
}

fareRules

{
  "refund": {
    "allowed":      Boolean,
    "fee":          Number,
    "currency":     String,
    "policyNotes":  String
  },
  "change": {
    "allowed":      Boolean,
    "fee":          Number,
    "currency":     String,
    "policyNotes":  String
  }
}
Example Response (truncated)
{
  "status": "SUCCESS",
  "statusCode": 200,
  "msg": "success",
  "sessionId": "ST_dc5ef320bf1442f0",
  "itineraries": [{
    "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
    "productType": "PUB",
    "fareType": "SAVER",
    "isRefundable": true,
    "journeys": {
      "onwardJourney": {
        "totalDurationMinutes": 25,
        "stopsCount": 0,
        "segments": [{
          "segmentId": 1,
          "carrier": {
            "marketing": "YETI", "operating": "YT", "validating": "YT",
            "aircraftCode": "", "flightNumber": "671", "operatingFlightNumber": "671"
          },
          "departure": { "airport": "BOM", "terminal": null, "dateTime": "2026-11-14T07:20:00" },
          "arrival": { "airport": "DXB", "terminal": null, "dateTime": "2026-11-14T07:45:00" },
          "flightDurationMinutes": 25,
          "bookingDetails": { "cabinClass": "E", "rbd": "Y", "fareBasis": "YOWNEPAL", "seatsRemaining": 9 },
          "baggage": [{ "passengerType": "ADT", "checkedPiece": 1, "checkedWeightKG": "15", "carryOnPiece": 1, "carryOnWeightKG": 7 }],
          "otherFareRules": []
        }],
        "layovers": []
      },
      "returnJourney": null
    },
    "pricingBreakdown": {
      "currency": "NPR", "baseFareTotal": 14200, "taxTotal": 0,
      "feeTotal": 0, "otherTotal": 0, "markupTotal": 0,
      "discountTotal": 0, "gstTotal": 0, "grandTotal": 14200,
      "passengerFares": [{
        "passengerType": "ADT", "count": 1, "baseFarePerPassenger": 14200,
        "taxPerPassenger": 0, "feePerPassenger": 0, "otherPerPassenger": 0,
        "markupPerPassenger": 0, "gstPerPassenger": 0,
        "discountPerPassenger": 0, "totalPerPassenger": 14200
      }]
    },
    "fareRules": {
      "refund": { "allowed": true, "fee": 0, "currency": "NPR", "policyNotes": "Refundable up to 2 hours before departure" },
      "change": { "allowed": true, "fee": 1500, "currency": "NPR", "policyNotes": "Date change charges apply plus fare difference" }
    }
  }]
}

3. Revalidate Fares

POST/v2/flights/revalidate_fares

Re-price a selected itinerary before booking. Executes a real-time validation to guarantee availability and lock the currency-specific tariff layout. Revalidation calls also reset the 15-minute session idle timer.

Request
200 Response
FieldTypeDescription
itineraryIdStringYesThe itinerary ID from search results (e.g. "ITI_0ec3d1df3be...")
curl
curl -X POST {{API_URL}}/v2/flights/revalidate_fares \
  -H "Authorization: Bearer <token>" \
  -H "X-Session: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{
  "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01"
}'
FieldTypeDescription
statusString"SUCCESS" or "ERROR"
statusCodeIntegerMapped process status (e.g. 200)
msgStringTransaction outcome detail
sessionIdStringPersistent/refreshed session identifier
fareDetailsObjectLocked structural matrices: pricingBreakdown + fareRules
Example Response
{
  "status": "SUCCESS",
  "statusCode": 200,
  "msg": "Fare validated",
  "sessionId": "ST_dc5ef320bf1442f0",
  "fareDetails": {
    "pricingBreakdown": {
      "currency": "NPR", "baseFareTotal": 14200, "taxTotal": 400,
      "feeTotal": 200, "otherTotal": 0, "markupTotal": 0,
      "discountTotal": 0, "gstTotal": 0, "grandTotal": 14200,
      "passengerFares": [{
        "passengerType": "ADT", "count": 1, "baseFarePerPassenger": 14200,
        "taxPerPassenger": 400, "feePerPassenger": 200, "otherPerPassenger": 0,
        "markupPerPassenger": 0, "gstPerPassenger": 0,
        "discountPerPassenger": 0, "totalPerPassenger": 14200
      }]
    },
    "fareRules": {
      "refund": { "allowed": true, "fee": 0, "currency": "NPR", "policyNotes": "Refundable" },
      "change": { "allowed": true, "fee": 1500, "currency": "NPR", "policyNotes": "Date change applies" }
    }
  }
}

4. Create PNR

POST/v2/flights/create_pnr

Compile traveler identities, contact details, documentation, and payment authorization to create a confirmed booking reference locator (PNR).

Request
200 Response
FieldTypeDescription
itineraryIdStringYesTarget itinerary reference code from search/revalidate
bookingActionStringYesWorkflow dispatch: "Book" or "Issued"
contactDetailsObjectYesBooking contact information (see below)
passengersArrayYesList of passenger documents matching GDS constraints
paymentModeStringYes"CREDIT_CARD", "DEBIT_CARD", "BANK_TRANSFER", or "WALLET"
paymentDetailsObjectYesPayment confirmation metadata (see below)

contactDetails

{
  "email":  String,
  "mobile": String,
  "name":   String
}

Passenger

{
  "passengerType": String,   // "ADT", "CHD", "INF"
  "firstName":     String,   // match passport exactly
  "middleName":    String,
  "lastName":      String,   // match passport exactly
  "gender":        String,   // "M" or "F"
  "birthday":      String,   // YYYYMMDD
  "nationality":   String,   // ISO 2-letter country code
  "docType":       String,   // "P" = passport
  "docNumber":     String,   // passport number
  "frequentFlyer": String,   // FF number or ""
  "issueCountry":  String,   // ISO 2-letter
  "docExpiredAt":  String    // YYYYMMDD
}

paymentDetails

{
  "transactionId":   String,
  "amount":          Number,
  "currency":        String,
  "paymentDate":     String,   // YYYYMMDD
  "paymentStatus":   String,   // "SUCCESS"
  "paymentGateway":  String,   // e.g. "ESEWA"
  "paymentReference":String
}
curl
curl -X POST {{API_URL}}/v2/flights/create_pnr \
  -H "Authorization: Bearer <token>" \
  -H "X-Session: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{
  "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
  "bookingAction": "Book",
  "contactDetails": {
    "email": "jane@example.com",
    "mobile": "+9779800000000",
    "name": "Jane Smith"
  },
  "passengers": [{
    "passengerType": "ADT",
    "firstName": "JANE",
    "middleName": null,
    "lastName": "SMITH",
    "gender": "F",
    "birthday": "19940821",
    "nationality": "NP",
    "docType": "P",
    "docNumber": "11234567A",
    "frequentFlyer": "",
    "issueCountry": "NP",
    "docExpiredAt": "20340820"
  }],
  "paymentMode": "WALLET",
  "paymentDetails": {
    "transactionId": "TXN_7823412903",
    "amount": 14200,
    "currency": "NPR",
    "paymentDate": "20260629",
    "paymentStatus": "SUCCESS",
    "paymentGateway": "ESEWA",
    "paymentReference": "REF-992381-P"
  }
}'
Response Envelope
FieldTypeDescription
statusString"SUCCESS" or "ERROR"
statusCodeIntegerProcess API code (e.g. 200)
msgStringTransaction description
sessionIdStringLocked session tracking hash
bookingInfoObjectPNR details container

bookingInfo

FieldTypeDescription
bookingReferenceStringGDS/System record locator PNR (e.g. "PNR123456")
bookingStatusString"CONFIRMED" or "HELD"
bookingDateStringPNR generation timestamp (ISO format)
itineraryIdStringIdentical reference key matching reserved itinerary
passengersArrayConfirmation details with assigned transient passengerId
Example Response
{
  "status": "SUCCESS",
  "statusCode": 200,
  "msg": "success",
  "sessionId": "ST_dc5ef320bf1442f0",
  "bookingInfo": {
    "bookingReference": "PNR123456",
    "bookingStatus": "CONFIRMED",
    "bookingDate": "2026-11-14T06:20:00Z",
    "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
    "passengers": [{
      "passengerType": "ADT",
      "passengerId": "PAX_98124",
      "firstName": "JANE",
      "middleName": null,
      "lastName": "SMITH",
      "gender": "F",
      "birthday": "19940821",
      "nationality": "NP",
      "docType": "P",
      "docNumber": "11234567A",
      "frequentFlyer": "",
      "issueCountry": "NP",
      "docExpiredAt": "20340820"
    }]
  }
}

5. Create Order (Ticketing)

POST/v2/flights/order

Dispatch the finalized order payload utilizing the established PNR reservation. Commits the billing context to transition the record to "TICKETED" status, completing the booking journey.

Request
200 Response
FieldTypeDescription
itineraryIdStringYesTarget itinerary reference from search/revalidate
bookingReferenceStringYesGDS/System PNR locator from create_pnr
paymentModeStringYesBilling scheme: "WALLET", etc.
paymentDetailsObjectYesGateway transaction metadata
curl
curl -X POST {{API_URL}}/v2/flights/order \
  -H "Authorization: Bearer <token>" \
  -H "X-Session: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{
  "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
  "bookingReference": "PNR123456",
  "paymentMode": "WALLET",
  "paymentDetails": {
    "transactionId": "TXN_7823412903",
    "amount": 14200,
    "currency": "NPR",
    "paymentDate": "20260629",
    "paymentStatus": "SUCCESS",
    "paymentGateway": "ESEWA",
    "paymentReference": "REF-992381-P"
  }
}'
FieldTypeDescription
statusString"SUCCESS" or "ERROR"
statusCodeIntegerResponse execution status (e.g. 200)
msgStringExecution outcome description
sessionIdStringActive session tracking key
bookingDetailsObjectMaster ticketing mapping

bookingDetails

FieldTypeDescription
bookingReferenceStringMaster GDS booking locator/PNR
bookingStatusString"CONFIRMED"
bookingDateStringConfirmation timestamp (ISO format)
gdsPNRStringGDS record reference
airlinePNRStringAirline internal inventory PNR
ticketingStatusString"TICKETED"
itineraryIdStringReference ID for selected itinerary
paymentDetailsObjectSettled payment values and transaction references
passengersArrayFinal passenger mapping with system-confirmed tickets
Example Response
{
  "status": "SUCCESS",
  "statusCode": 200,
  "msg": "success",
  "sessionId": "ST_dc5ef320bf1442f0",
  "bookingDetails": {
    "bookingReference": "PNR123456",
    "bookingStatus": "CONFIRMED",
    "bookingDate": "2026-11-14T06:20:00Z",
    "gdsPNR": "PNR123456",
    "airlinePNR": "YT123456",
    "ticketingStatus": "TICKETED",
    "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
    "paymentDetails": {
      "transactionId": "TXN_7823412903",
      "amount": 14200,
      "currency": "NPR",
      "paymentDate": "20260629",
      "paymentStatus": "SUCCESS",
      "paymentGateway": "ESEWA",
      "paymentReference": "REF-992381-P"
    },
    "passengers": [{
      "passengerType": "ADT",
      "passengerId": "PAX_98124",
      "firstName": "JANE",
      "middleName": null,
      "lastName": "SMITH",
      "gender": "F",
      "birthday": "19940821",
      "nationality": "NP",
      "docType": "P",
      "docNumber": "11234567A",
      "frequentFlyer": "",
      "issueCountry": "NP",
      "docExpiredAt": "20340820"
    }]
  }
}

6. Order Status Query

POST/v2/flights/order_status

Check the status of an existing order or booking reservation. Useful for verifying ticketing state in asynchronous payment settlement scenarios.

Request
200 Response
FieldTypeDescription
bookingReferenceStringYesGDS or System PNR locator code (e.g. "PNR123456")
curl
curl -X POST {{API_URL}}/v2/flights/order_status \
  -H "Authorization: Bearer <token>" \
  -H "X-Session: <sessionId>" \
  -H "Content-Type: application/json" \
  -d '{
  "bookingReference": "PNR123456"
}'
FieldTypeDescription
statusString"SUCCESS" or "ERROR"
statusCodeIntegerCanonical REST status integer
msgStringStatus description context
sessionIdStringUnified sequence identifier
bookingDetailsObjectMaster order ledger with pricingBreakdown
Example Response
{
  "status": "SUCCESS",
  "statusCode": 200,
  "msg": "success",
  "sessionId": "ST_dc5ef320bf1442f0",
  "bookingDetails": {
    "bookingReference": "PNR123456",
    "bookingStatus": "CONFIRMED",
    "bookingDate": "2026-11-14T06:20:00Z",
    "gdsPNR": "PNR123456",
    "airlinePNR": "YT123456",
    "ticketingStatus": "TICKETED",
    "itineraryId": "ITI_0ec3d1df3be34316b0_PUB_01",
    "paymentDetails": {
      "transactionId": "TXN_7823412903",
      "amount": 14200,
      "currency": "NPR",
      "paymentDate": "20260629",
      "paymentStatus": "SUCCESS",
      "paymentGateway": "ESEWA",
      "paymentReference": "REF-992381-P"
    },
    "passengers": [{
      "passengerType": "ADT",
      "passengerId": "PAX_98124",
      "firstName": "JANE",
      "middleName": null,
      "lastName": "SMITH",
      "gender": "F",
      "birthday": "19940821",
      "nationality": "NP",
      "docType": "P",
      "docNumber": "11234567A",
      "frequentFlyer": "",
      "issueCountry": "NP",
      "docExpiredAt": "20340820"
    }],
    "fareDetails": {
      "pricingBreakdown": {
        "currency": "NPR", "baseFareTotal": 14200, "taxTotal": 0,
        "feeTotal": 0, "otherTotal": 0, "markupTotal": 0,
        "discountTotal": 0, "gstTotal": 0, "grandTotal": 14200,
        "passengerFares": [{
          "passengerType": "ADT", "count": 1, "baseFarePerPassenger": 5800,
          "taxPerPassenger": 400, "feePerPassenger": 0,
          "otherPerPassenger": 0, "markupPerPassenger": 0,
          "gstPerPassenger": 0, "discountPerPassenger": 0,
          "totalPerPassenger": 6200
        }]
      }
    }
  }
}

End-to-End Example

#!/bin/bash
API="{{API_URL}}"

# 1 — Authenticate
TOKEN=$(curl -s -X POST $API/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"affiliate@travelpartner.com","api_key":"offshore_pk_live_89c72e18fa4b","company_name":"Global Travel Solutions Ltd"}' \
  | jq -r '.token')

# 2 — Search (sessionId comes back in response)
SRCH=$(curl -s -X POST $API/v2/flights/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"depCity":"BOM","arrCity":"DXB","fromDate":"20261114","adultNumber":1,"childNumber":0,"infantNumber":0,"cabinClass":"E","stops":"0","inclAirlines":["YT"]}')

SESS=$(echo "$SRCH" | jq -r '.sessionId')
ITIN=$(echo "$SRCH" | jq -r '.itineraries[0].itineraryId')

# 3 — Revalidate
curl -s -X POST $API/v2/flights/revalidate_fares \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Session: $SESS" \
  -H "Content-Type: application/json" \
  -d "{\"itineraryId\":\"$ITIN\"}" | jq .

# 4 — Create PNR
PNR_RESP=$(curl -s -X POST $API/v2/flights/create_pnr \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Session: $SESS" \
  -H "Content-Type: application/json" \
  -d '{
    "itineraryId": "'$ITIN'",
    "bookingAction": "Book",
    "contactDetails": {"email":"jane@example.com","mobile":"+9779800000000","name":"Jane Smith"},
    "passengers": [{"passengerType":"ADT","firstName":"JANE","middleName":null,"lastName":"SMITH","gender":"F","birthday":"19940821","nationality":"NP","docType":"P","docNumber":"11234567A","frequentFlyer":"","issueCountry":"NP","docExpiredAt":"20340820"}],
    "paymentMode": "WALLET",
    "paymentDetails": {"transactionId":"TXN_7823412903","amount":14200,"currency":"NPR","paymentDate":"20260629","paymentStatus":"SUCCESS","paymentGateway":"ESEWA","paymentReference":"REF-992381-P"}
  }')

PNR=$(echo "$PNR_RESP" | jq -r '.bookingInfo.bookingReference')
echo "$PNR_RESP" | jq .

# 5 — Create Order (Ticketing)
curl -s -X POST $API/v2/flights/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Session: $SESS" \
  -H "Content-Type: application/json" \
  -d '{
    "itineraryId": "'$ITIN'",
    "bookingReference": "'$PNR'",
    "paymentMode": "WALLET",
    "paymentDetails": {"transactionId":"TXN_7823412903","amount":14200,"currency":"NPR","paymentDate":"20260629","paymentStatus":"SUCCESS","paymentGateway":"ESEWA","paymentReference":"REF-992381-P"}
  }' | jq .

# 6 — Order Status
curl -s -X POST $API/v2/flights/order_status \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Session: $SESS" \
  -H "Content-Type: application/json" \
  -d "{\"bookingReference\":\"$PNR\"}" | jq .

Appendix: Standard Data Mappings

Cabin Class Identifiers

CodeDescription
EEconomy Class
PPremium Economy
JBusiness Class
FFirst Class

Passenger Type Codes (PTC)

CodeClassificationAge Restriction
ADTAdult TravelerAge ≥ 12 at departure date
CHDChild TravelerAge 2–11 at departure date
INFInfant on LapUnder 2 years on return/arrival date

API Key Request Restrictions & Parameters

Date formats: All dates use YYYYMMDD format without separators (e.g. "20261114").

Names: Passenger first, middle, and last names must match passport details exactly. Remove special characters and diacritical marks for seamless airline database transmission.

Session timeout: Inactive sessions are flushed after 15 minutes of idle state. Revalidation calls reset the active timer.