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

# select-ancillaries

> Select ancillaries (baggage, seats, meals) for a trip item

Add baggage or seat selections to a flight item before checkout. Use it after the trip has a flight item and travelers attached but before `checkout`, for example when a user requests "two checked bags and a window seat for the outbound leg". Selections use full-replacement semantics: include everything the user wants kept on the trip in a single call.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/select_ancillaries
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.125.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.


    ### Per-end-user attribution


    On booking calls you may send an optional `X-End-User-Id` request header to
    attribute the booking to one of your own end users (for per-end-user
    attribution and rate-limiting). The value is an **opaque, tenant-scoped**
    identifier that you choose — not a Jinko account id. Omit it to book as the
    tenant. Values prefixed `user_` or `org_` are rejected.
servers:
  - url: https://api.gojinko.com
    description: Production
  - url: https://api.sandbox.gojinko.com
    description: Sandbox
security: []
paths:
  /v1/select_ancillaries:
    post:
      tags:
        - Pricing & booking
      summary: Select ancillaries (baggage, seats, meals) for a trip item
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AncillaryRequest'
      responses:
        '200':
          description: Updated ancillary selection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AncillaryResponse'
        '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/authentication/api-keys
        '402':
          description: Payment required — organization balance exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PAYMENT_REQUIRED
                  message: >-
                    Insufficient balance — this call costs $0.0150 and your
                    organization has $0.0000 available. Top up at
                    https://dashboard.gojinko.com/developers/billing/topup
                  doc_url: https://docs.gojinko.com/concepts/errors
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '409':
          description: The operation conflicts with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: CONFLICT
                  message: >-
                    The operation conflicts with the current state of the
                    resource.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '410':
          description: The resource this request names no longer exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: GONE
                  message: The resource no longer exists.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: A required field is missing or invalid.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '429':
          description: Rate limit or quota exceeded
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Absent when no interval
                applies.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Too many requests. Retry after the Retry-After delay.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '502':
          description: The travel provider rejected the request, or an upstream call failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_REJECTED
                  message: The request was declined for this offer. Try another offer.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '503':
          description: No travel provider can serve the request right now
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Absent when no interval
                applies.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_UNAVAILABLE
                  message: >-
                    The service is temporarily unavailable. Retry after the
                    Retry-After delay.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '504':
          description: The travel provider did not answer in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_TIMEOUT
                  message: >-
                    The request timed out before a result was available. Retry
                    the request.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    AncillaryRequest:
      type: object
      properties:
        trip_id:
          type: string
        item_id:
          type: string
        selections:
          type: array
          items:
            type: object
            properties:
              offer_id:
                type: string
                description: >-
                  The `offer_id` of an offer in the item’s
                  `available_ancillaries`, exactly as received.
              category:
                type: string
                description: The server resolves the category from the offer.
              traveler_ref:
                type: string
                description: Use the traveler's `traveler_ref` from GET /v1/trip.
              segment_ref_ids:
                type: array
                items:
                  type: string
                description: For a seat, pass the offer's one `segment_ref_id`.
              seat_number:
                type: string
                description: >-
                  The seat to assign, required when the offer is a seat offer.
                  Pick one from the offer's `seat_map.seats` with `available`
                  true. One seat per passenger per segment, and each seat to at
                  most one passenger.
                example: 14A
              journey_ref_id:
                type: string
              quantity:
                type: number
            required:
              - offer_id
        intent:
          $ref: '#/components/schemas/IntentInput'
      required:
        - trip_id
        - item_id
        - selections
      example:
        trip_id: trip_1048576
        item_id: itm_4b91c2
        selections:
          - offer_id: anc_3f9a1c27e4b8d051
            traveler_ref: pax_1
            quantity: 1
          - offer_id: anc_9b04e7d2c6a1f835
            traveler_ref: pax_1
            segment_ref_ids:
              - seg_1
            seat_number: 14A
    AncillaryResponse:
      type: object
      properties:
        trip_id:
          type: string
          example: trip_1048576
        item_id:
          type: string
          description: >-
            The trip item the selection applied to — `items[].item_id` on the
            trip.
          example: itm_4b91c2
        quoted_item_id:
          type: number
          description: >-
            Deprecated: use `item_id` instead. An internal number for the priced
            item.
          example: 8810231
          deprecated: true
        selected_ancillaries:
          type: array
          items:
            $ref: '#/components/schemas/SelectedAncillary'
        total_with_ancillaries:
          allOf:
            - $ref: '#/components/schemas/Money'
            - description: >-
                The item total including the selected ancillaries, in minor
                units: `amount` is an integer to divide by 10 **
                `decimal_places` (e.g. `{amount: 23959, currency: "EUR",
                decimal_places: 2}` is EUR 239.59). `display` is the same figure
                to show.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_SEGMENTS_TO_EXCHANGE
                - PARTIAL_EXCHANGE_UNSUPPORTED
                - LEG_ALREADY_DEPARTED
                - DEPARTURE_DATE_IN_PAST
                - LEG_DATES_OUT_OF_ORDER
                - INVALID_EXCHANGE_REQUEST
                - NOT_EXCHANGEABLE
                - CREDENTIAL_FORMAT_INVALID
                - PAYMENT_TYPE_NOT_ENABLED
                - PAYMENT_CREDENTIAL_INVALID
                - TRIP_OWNED_BY_OTHER_PAYMENT
                - IDEMPOTENCY_KEY_REUSED
                - ATTEMPT_IN_PROGRESS
                - ATTEMPT_TERMINAL
                - TEMPORARILY_UNAVAILABLE
                - AUTH_REQUIRED
                - PAYMENT_REQUIRED
                - RATE_LIMITED
                - BAD_REQUEST
                - FORBIDDEN
                - NOT_FOUND
                - CONFLICT
                - GONE
                - QUOTE_PENDING
                - QUOTE_EXPIRED
                - TRIP_EXPIRED
                - TRIP_STATE_CONFLICT
                - OFFER_EXPIRED
                - OFFER_UNAVAILABLE
                - MISSING_CUSTOMER_DETAILS
                - INVALID_PHONE_NUMBER
                - INVALID_FLIGHT_NUMBER
                - CURRENCY_UNSUPPORTED
                - HOTEL_NAME_LOW_CONFIDENCE
                - DESTINATION_LOW_CONFIDENCE
                - UPSTREAM_REJECTED
                - UPSTREAM_UNAVAILABLE
                - UPSTREAM_TIMEOUT
                - UPSTREAM_ERROR
                - INTERNAL
              description: >-
                What went wrong, as a stable machine-readable code. This is a
                closed set — branch on it rather than on `message`, which is
                prose and may change. New codes arrive in a minor version, so
                treat an unknown one as its HTTP status. A code can also stop
                being emitted: it leaves this set in a minor version, named in
                the changelog, and a branch you wrote for it goes unreached
                rather than wrong.
              example: BAD_REQUEST
            message:
              type: string
              description: >-
                What went wrong, in prose. These codes always carry the same
                message, and it never includes text from a supplier:
                `RATE_LIMITED` — "Too many requests. Retry after the Retry-After
                delay."; `OFFER_EXPIRED` — "This offer has expired. Search
                again."; `OFFER_UNAVAILABLE` — "This offer is no longer
                available. Search again."; `UPSTREAM_REJECTED` — "The request
                was declined for this offer. Try another offer.";
                `UPSTREAM_UNAVAILABLE` — "The service is temporarily
                unavailable. Retry after the Retry-After delay.";
                `UPSTREAM_TIMEOUT` — "The request timed out before a result was
                available. Retry the request."; `UPSTREAM_ERROR` — "The request
                could not be completed.".
            doc_url:
              type: string
            field:
              type: string
              description: >-
                On a 400 `BAD_REQUEST` that names one refused input: the path of
                that field in your request, e.g. `selections[1].quantity` for
                the second selection of a `select_ancillaries` call. Absent when
                the refusal names no single field.
              example: selections[1].quantity
          required:
            - code
            - message
      required:
        - error
    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
    SelectedAncillary:
      type: object
      properties:
        offer_id:
          type: string
          description: >-
            Opaque identifier of this ancillary offer. Pass it back exactly as
            received in `selections[].offer_id`; do not parse or build it.
          example: anc_3f9a1c27e4b8d051
        traveler_ref:
          type: string
          description: >-
            The traveler the selection applies to; absent on a booking-level
            ancillary.
          example: pax_1
        pax_ref_id:
          type: string
          description: 'Deprecated: use `traveler_ref` instead. Same value.'
          example: pax_1
          deprecated: true
        quantity:
          type: integer
          example: 1
        type:
          type: string
          description: >-
            Ancillary family on a booked outcome, e.g. "seat" or "bag"
            (lowercase, open set). May be absent before booking.
          example: seat
        seat_number:
          type: string
          example: 14A
        segment_ref_ids:
          type: array
          items:
            type: string
          example:
            - seg_1
        price:
          allOf:
            - $ref: '#/components/schemas/Money'
            - description: >-
                Deprecated: use `price_money` instead. The unit price of the
                chosen seat, set by the server: major units in the trip
                currency. Absent for a free seat or a selection without its own
                unit price.
              deprecated: true
        price_money:
          allOf:
            - $ref: '#/components/schemas/MoneyValue'
            - description: >-
                The exact unit price of the chosen seat, set by the server.
                Absent for a free seat or a selection without its own unit
                price, e.g. a bag.
        status:
          type: string
          enum:
            - pending
            - confirmed
            - failed
          description: >-
            Absent before booking. For seats, `pending` means the airline has
            not confirmed the seat yet. `confirmed` means booked with the
            airline. `failed` means not booked.
        not_charged:
          type: boolean
          description: true when this seat is not charged to the traveler.
        failure_reason:
          type: string
          description: >-
            Why an ancillary failed, or why a pending airline outcome needs
            reconciliation.
      required:
        - offer_id
      description: >-
        An ancillary selected on a trip item, as the trip read and the
        select_ancillaries response both return it. Provider data is never
        included.
    Money:
      type: object
      properties:
        amount:
          type: number
          description: >-
            Deprecated: use `value` instead (the same integer) where this object
            carries decimal_places. Where it does not, the figure is in MAJOR
            units and the field holding this object is itself deprecated: read
            its `*_money` sibling. The two-scale rule applies only to deprecated
            fields. Alternative to `value` on some endpoints (the two never
            appear together); its scale depends on decimal_places. When this
            object carries decimal_places, amount is an INTEGER in minor units —
            divide by 10 ** decimal_places (e.g. select_ancillaries
            total_with_ancillaries). When there is no decimal_places field,
            amount is a decimal in MAJOR units, safe to display as-is (e.g. trip
            and checkout totals).
          deprecated: true
        value:
          type: integer
          description: >-
            Integer amount in MINOR units, always paired with decimal_places —
            divide by 10 ** decimal_places to display. Example: value 15977 with
            decimal_places 2 is 159.77 USD. Rendering this field directly shows
            prices 100x too high for 2-decimal currencies.
          example: 41250
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        decimal_places:
          type: integer
          description: >-
            Scale of the integer value/amount: display = integer / 10 **
            decimal_places. Always sent alongside minor-unit amounts. Usually
            the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for
            JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry
            a different scale — ALWAYS use the decimal_places sent with the
            amount, never a hardcoded 2. Only if the field is genuinely absent
            on a value-shaped object, fall back to the ISO digits for the
            currency.
          example: 2
        display:
          type: string
          description: >-
            The same figure as a string ready to show: the ISO 4217 code, a
            space, then the amount, e.g. "USD 159.77". With decimal_places it is
            written at exactly that scale (value 1561500, JPY, decimal_places 2
            is "JPY 15615.00"); without, at the ISO digits of the currency. Show
            this; compute with the number. Absent when the figure is not money
            (a cancellation step expressed as a percent or a number of nights)
            or could not be read unambiguously.
          example: USD 412.50
      description: >-
        A money figure in one of two scales. New integrations read the `*_money`
        field beside it (a `MoneyValue`) where there is one, and `value` on
        objects that carry it; the rule below applies only to the deprecated
        forms. When `decimal_places` is present, `value` (or the deprecated
        `amount`) is an INTEGER in minor units: divide by 10 ** decimal_places.
        When it is absent, the deprecated `amount` is already in MAJOR units.
        Branch on whether decimal_places is present in the response you
        received, never on the currency code or the field name. `display` is the
        same figure as a string to show.
    MoneyValue:
      type: object
      properties:
        value:
          type: integer
          description: >-
            Integer amount in MINOR units at the ISO 4217 digits of `currency`:
            divide by 10 ** decimal_places to get the amount. Signed where the
            field says so (a price change delta).
          example: 41250
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 currency code.
          example: USD
        decimal_places:
          type: integer
          description: >-
            The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3
            for BHD/KWD), and the scale of `value`.
          example: 2
        display:
          type: string
          description: >-
            The same figure as a string ready to show: the ISO 4217 code, a
            space, then the amount at `decimal_places`, e.g. "USD 412.50". Show
            this; compute with `value`.
          example: USD 412.50
      required:
        - value
        - currency
        - decimal_places
        - display
      description: >-
        Money as every new field carries it: `value` is an INTEGER in minor
        units at the ISO 4217 digits of `currency` (`decimal_places`), and
        `display` is the same figure ready to show. All four members are always
        present; a figure the platform does not know is absent, never `{value:
        0}`. New integrations read the `*_money` fields (and `value` on the
        objects that carry it); the two-scale rule described on `Money` applies
        only to the deprecated fields.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.