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

# List a patient's Passport orders

> The patient's pharmacy orders, with each order's current step and shipment tracking. Returns the first page only: `pagination.after` is `PAGING_NOT_SUPPORTED` when the list may have more items than `limit`, and `null` when the list is complete. Sending `cursor` answers 400 until paging is supported.

**Availability:** Patient Passport answers only for organizations enabled for it. Any other organization gets 403 `ORG_NOT_ENABLED`; ask your OLH implementation contact to enable yours.

Service tokens only: a user token gets 403 `FORBIDDEN`. Every response carries `Cache-Control: no-store`.

**Permissions:** `orders:read`



## OpenAPI

````yaml /openapi.json get /passport/orders
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /passport/orders:
    get:
      tags:
        - Patient Passport
      summary: List a patient's Passport orders
      description: >-
        The patient's pharmacy orders, with each order's current step and
        shipment tracking. Returns the first page only: `pagination.after` is
        `PAGING_NOT_SUPPORTED` when the list may have more items than `limit`,
        and `null` when the list is complete. Sending `cursor` answers 400 until
        paging is supported.


        **Availability:** Patient Passport answers only for organizations
        enabled for it. Any other organization gets 403 `ORG_NOT_ENABLED`; ask
        your OLH implementation contact to enable yours.


        Service tokens only: a user token gets 403 `FORBIDDEN`. Every response
        carries `Cache-Control: no-store`.


        **Permissions:** `orders:read`
      parameters:
        - name: patient_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            The patient's `id` in the Partner API, the same `id` that `GET
            /patients` returns. Anything that isn't a UUID answers 404.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Maximum number of items to return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PassportOrder'
                  pagination:
                    $ref: '#/components/schemas/PassportPagination'
                  request_id:
                    type: string
                required:
                  - items
                  - pagination
                  - request_id
        '400':
          description: '`BAD_REQUEST`: a `cursor` was sent. Paging isn''t supported yet.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >-
            Missing or invalid access token. The Partner API answers this before
            the request reaches Patient Passport.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            `error_code` says why: `FORBIDDEN` (the token lacks `orders:read`,
            or isn't a partner service token), `ORG_NOT_MAPPED` (your
            organization has no Healthie organization linked) or
            `ORG_NOT_ENABLED` (your organization isn't enabled for Patient
            Passport).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            `PATIENT_NOT_FOUND`: no patient with that id in your organization,
            or `patient_id` isn't a UUID. The cases are deliberately
            indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `PATIENT_IDENTITY_UNRESOLVED`: the patient can't be matched to a
            single Patient Passport record. Quote `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            `VALIDATION_ERROR`: `patient_id` is missing, or `limit` is outside 1
            to 50.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Too many requests. The route is throttled at 100 requests per
            second, with bursts of 120. Back off and retry.
        '500':
          description: >-
            `UNHANDLED_EXCEPTION`: something failed that names no cause. Quote
            `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            `UPSTREAM_UNAVAILABLE`: patient data is temporarily unavailable.
            Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Patient Passport didn't answer within 29 seconds. Safe to retry.
      security:
        - serviceToken:
            - orders:read
components:
  schemas:
    PassportOrder:
      type: object
      properties:
        fill:
          type: integer
          description: Fill number of the order.
        program_upi:
          type:
            - string
            - 'null'
        program_name:
          type:
            - string
            - 'null'
        placed_at:
          type: string
          format: date-time
        status:
          type: string
          description: >-
            The order's latest raw pharmacy status, passed through as is, for
            detail only. It's an open set and can disagree with `step` (for
            example, `step` is `shipped` while the latest event is a
            correction), so use `step` for the order's state.


            | `status` | Contributes `step` |

            |---|---|

            | `PrescriptionCreated` | none (`processing`) |

            | `PrescriptionInvoiced` | none (`processing`) |

            | `PrescriptionPaid` | `paid` |

            | `PrescriptionOrdered` | `sent_to_pharmacy` |

            | `PrescriptionShipped` | `shipped` |

            | `PrescriptionShipmentUpdate` (a shipment update without a carrier
            status) | `shipped` |

            | A carrier shipment status, such as `in_transit` | `shipped` |

            | A carrier shipment status of `delivered` (any case) | `delivered`
            |

            | `PrescriptionCancelled` | `cancelled` |


            Carrier statuses are free text from the pharmacy's carrier feed and
            aren't normalized: treat any value not in this table as `shipped`
            detail and show `step` instead. `PrescriptionChanged` is a
            correction, not a status, so it never appears.
          example: PrescriptionShipped
        status_at:
          type: string
          format: date-time
          description: When the latest status happened (UTC).
        step:
          type: string
          enum:
            - processing
            - paid
            - sent_to_pharmacy
            - shipped
            - delivered
            - cancelled
          description: >-
            The order's progress: the furthest step it has reached, or
            `cancelled` when the latest event is a cancel. Key your UI on this
            field.


            | `step` | Meaning |

            |---|---|

            | `processing` | The order exists but hasn't been paid yet (created
            or invoiced only). |

            | `paid` | Payment received. |

            | `sent_to_pharmacy` | Sent to the pharmacy to fill. |

            | `shipped` | Shipped, including any carrier tracking update short
            of delivered. |

            | `delivered` | The carrier reported it delivered. |

            | `cancelled` | Cancelled, including a shipment that came back after
            a cancel (returned to sender). |


            - **Furthest step wins.** `step` never moves backwards: a late paid
            event after shipped doesn't change it.

            - **Cancel wins.** When the latest event is a cancel, the order
            shows `cancelled` whatever came before.

            - **Re-fill after a cancel.** If the order moves on again after a
            cancel (paid, sent or shipped again), `step` shows the furthest of
            those new steps.

            - **Shipped comes from pharmacy events only**, never from `carrier`
            or `tracking_number` alone.
        step_dates:
          $ref: '#/components/schemas/PassportOrderStepDates'
        status_age_days:
          type:
            - integer
            - 'null'
          description: Whole UTC calendar days since `status_at`; 0 for today.
        carrier:
          type:
            - string
            - 'null'
        tracking_number:
          type:
            - string
            - 'null'
        tracking_url:
          type:
            - string
            - 'null'
      required:
        - fill
        - placed_at
        - status
        - status_at
        - step
        - step_dates
    PassportPagination:
      type: object
      description: >-
        Paging state of a Patient Passport list. Paging isn't supported yet, so
        a list is always its first page.
      properties:
        after:
          type:
            - string
            - 'null'
          description: >-
            `null` when the list is complete. `PAGING_NOT_SUPPORTED` when the
            list may have more items than `limit`: it is a marker, not a cursor,
            and sending it back as `cursor` answers 400.
        before:
          type:
            - string
            - 'null'
          description: Always `null`.
        items:
          type: integer
          description: Number of items on this page.
      required:
        - after
        - before
        - items
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id
    PassportOrderStepDates:
      type: object
      description: >-
        When the order reached each step (UTC), or `null` for a step it hasn't
        reached. Each date is the first time the order reached that step.


        A `cancelled` order has every date `null`: steps before the cancel are
        dropped, so a cancelled or returned order never counts as shipped. An
        order that moves on after a cancel shows only the dates of its steps
        since the cancel.
      properties:
        paid:
          type:
            - string
            - 'null'
          format: date-time
        sent_to_pharmacy:
          type:
            - string
            - 'null'
          format: date-time
        shipped:
          type:
            - string
            - 'null'
          format: date-time
        delivered:
          type:
            - string
            - 'null'
          format: date-time
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}

````

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