> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# trip

> Create and manage a trip — add or remove items, set travelers, select ancillaries

Assemble and edit a trip before sending it to checkout. Use it to add a flight or hotel offer, set traveler details, swap one item for another, or attach ancillaries like bags and seats. Flights and hotels can sit side by side in the same trip and settle through a single checkout.

Unified trip management endpoint. In a single call you can `add_item` (by `trip_item_token`), `remove_item` (by `item_id`), and `upsert_travelers` (travelers + contact). Omit `trip_id` to create a new trip; include it to update an existing one. Returns the resulting trip state.

Ancillaries are selected on a separate endpoint. See [select-ancillaries](/api/select-ancillaries).


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/trip
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.1.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.
servers: []
security: []
paths:
  /v1/trip:
    post:
      tags:
        - Pricing & booking
      summary: >-
        Create and manage a trip — add or remove items, set travelers, select
        ancillaries
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TripRequest'
      responses:
        '200':
          description: The trip
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: Malformed JSON in request body.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_REQUIRED
                  message: Invalid or expired API key.
                  doc_url: https://docs.gojinko.com/api-reference/authentication
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: >-
                    origins: origins is required; trip_type: trip_type is
                    required
                  doc_url: https://docs.gojinko.com/concepts/errors
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit or quota exceeded.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '502':
          description: Upstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_ERROR
                  message: Upstream travel provider returned an error. Please retry.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    TripRequest:
      type: object
      properties:
        trip_id:
          type: string
        add_item:
          type: object
          properties:
            trip_item_token:
              type: string
          required:
            - trip_item_token
        remove_item:
          type: object
          properties:
            item_id:
              type: string
          required:
            - item_id
        upsert_travelers:
          type: object
          properties:
            travelers:
              type: array
              items:
                $ref: '#/components/schemas/Traveler'
              description: >-
                Travelers on the trip (replaces all). Required to complete a
                booking; the first traveler also supplies the booking contact
                name.
            contact:
              $ref: '#/components/schemas/Contact'
          required:
            - travelers
        intent:
          $ref: '#/components/schemas/IntentInput'
      example:
        trip_id: trip_1048576
        add_item:
          trip_item_token: tok_flt_9f3b2a17
    TripResponse:
      type: object
      properties:
        trip_id:
          type: string
          example: trip_1048576
        status:
          type: string
          example: draft
        actions_performed:
          type: array
          items:
            type: string
          example:
            - created
            - add_item
        items:
          type: array
          items:
            type: object
            properties:
              item_id:
                type: string
                example: itm_4b91c2
              kind:
                type: string
                example: flight
              price:
                type: object
                properties:
                  amount:
                    type: number
                    example: 318.4
                  value:
                    type: number
                  currency:
                    type: string
                    example: USD
                  decimal_places:
                    type: integer
                    example: 2
              pax_count:
                type: number
                example: 1
              available_ancillaries:
                type: array
                items:
                  nullable: true
              selected_ancillaries:
                type: array
                items:
                  nullable: true
        travelers:
          type: array
          items:
            nullable: true
        contact:
          type: object
          properties:
            email:
              type: string
            phone:
              type: string
        totals:
          type: object
          properties:
            currency:
              type: string
            total:
              type: number
          example:
            currency: USD
            total: 318.4
      required:
        - trip_id
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    Traveler:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: >-
            Date of birth (YYYY-MM-DD). Required for flights; optional for
            hotel-only trips.
        gender:
          type: string
          enum:
            - MALE
            - FEMALE
          description: Required for flights; optional for hotel-only trips.
        passenger_type:
          type: string
          enum:
            - ADULT
            - CHILD
            - INFANT
        nationality:
          type: string
        passport_number:
          type: string
        passport_expiry:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        passport_country:
          type: string
        frequent_flyer:
          $ref: '#/components/schemas/FrequentFlyer'
      required:
        - first_name
        - last_name
        - passenger_type
    Contact:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Contact email for booking confirmations.
        phone:
          type: string
          description: >-
            Contact phone with country code. Required — connectors reject
            bookings without it.
      required:
        - email
        - phone
      description: >-
        Booking contact (email + phone). Optional while building the cart, but
        required before booking.
    IntentInput:
      type: object
      properties:
        user_intent:
          type: string
          nullable: true
          description: >-
            The user's natural-language intent: the Alpic PII-stripped
            paraphrase when available, else a best-effort fallback to the
            client-provided NL query.
          example: find a cheap flight to Tokyo
    FrequentFlyer:
      type: object
      properties:
        airline:
          type: string
          description: >-
            IATA code of the loyalty program issuer (e.g. `LH` for Lufthansa
            Miles & More), not necessarily the operating carrier — alliances
            credit miles on partner flights.
          example: LH
        number:
          type: string
          description: Membership / account number for that loyalty program.
          example: '992100100'
      required:
        - airline
        - number
      description: >-
        Optional per-passenger frequent-flyer membership so airline miles are
        credited on the booking. Flights only; when present, both airline and
        number are required.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````