---
title: "List session orders"
method: GET
path: "/api/orders"
---

# List session orders

`GET /api/orders`

## Request

- Base URL: `https://postedly.com`
- URL: `https://postedly.com/api/orders`
- Auth: HTTP bearer

## Response `200`

Up to 100 newest orders for the authenticated owner.

- OrderList
  - `orders` Order[], required: HTTP returns up to 100 newest orders. MCP postedly_orders returns up to 50.
    - `id` string, uuid, required
    - `service` string, required: Recorded service; historical orders can retain a service no longer offered.
    - `amountCents` integer, required: Amount in integer US cents; never a floating-point dollar amount.
    - `refundedCents` integer, required: Amount in integer US cents; never a floating-point dollar amount.
    - `currency` 'usd', required: Order storage uses lowercase usd; quote responses use uppercase USD.
    - `paymentStatus` 'checkout_pending' | 'authorized' | 'paid' | 'failed' | 'cancelled' | 'refund_pending' | 'refunded', required: Separate from fulfillment. authorized is a hold, used for fax before capture following confirmed transmission. paid does not mean sent or delivered. refund_pending is not a completed refund.
    - `fulfillmentStatus` 'awaiting_payment' | 'queued' | 'submitting' | 'submission_unknown' | 'submitted' | 'processing' | 'sent' | 'delivered' | 'failed' | 'cancelled', required: Recorded provider progression. submission_unknown requires reconciliation, never a blind resend. Fax delivered means all approved pages were confirmed by the receiving machine, not that a person read them. Postal statuses reflect available provider milestones.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `recipient` Contact, required
      - `name` string, required
      - `email` string, email
      - `fax` string
      - `phone` string
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string
    - `sender` Contact, required
      - `name` string, required
      - `email` string, email
      - `fax` string
      - `phone` string
      - `address1` string
      - `address2` string
      - `city` string
      - `state` string
      - `postalCode` string
      - `country` string
    - `receiptEmail` string, email: The immutable verified receipt destination; distinct from the quoted postal sender.
    - `options` object, required
    - `handwritten` HandwrittenReview: Immutable quoted card, handwriting style, exact text, postal addresses and postage option. Images are design/style samples, not a rendered final-message proof.
      - `cardId` string, required
      - `cardName` string, required
      - `cardImageUrl` string, uri, required
      - `fontId` string, required
      - `fontLabel` string, required
      - `fontImageUrl` string, uri, required
      - `message` string, required
      - `wishes` string, required
      - `sender` Contact, required
        - `name` string, required
        - `email` string, email
        - `fax` string
        - `phone` string
        - `address1` string
        - `address2` string
        - `city` string
        - `state` string
        - `postalCode` string
        - `country` string
      - `recipient` Contact, required
        - `name` string, required
        - `email` string, email
        - `fax` string
        - `phone` string
        - `address1` string
        - `address2` string
        - `city` string
        - `state` string
        - `postalCode` string
        - `country` string
      - `previewKind` 'design_and_style_samples', required
      - `stampOptionId` integer, required
      - `stampName` string, required
    - `addressWarnings` AddressWarning[]
      - `role` 'recipient' | 'sender', required
      - `code` 'address_unit_required' | 'address_unverified', required
      - `message` string, required
      - `address` Contact, required
        - `name` string, required
        - `email` string, email
        - `fax` string
        - `phone` string
        - `address1` string
        - `address2` string
        - `city` string
        - `state` string
        - `postalCode` string
        - `country` string
    - `document` OrderDocument: Stored order document metadata; this response does not include a preview URL or contentType. Mail orders may refer to the source document, while the quote contains its final print proof.
      - `id` string, uuid, required
      - `name` string, required
      - `pages` integer, required
      - `bytes` integer, required
      - `sha256` string, required: SHA-256 of the exact raw file bytes, as 64 hexadecimal characters.
    - `checkoutUrl` string, uri, nullable: Present only while paymentStatus is checkout_pending; may be null if checkout creation has not completed. Private URL, not payment evidence.
    - `timeline` OrderEvent[], required: Up to 200 earliest events, in ascending timestamp order.
      - `id` string, required: Opaque event identifier, not necessarily a UUID.
      - `type` string, required: Extensible event type; do not treat it as a payment/fulfillment enum.
      - `message` string, required
      - `createdAt` string, date-time, required
    - `canCancel` boolean, required: True for awaiting_payment or queued. Advisory snapshot; a cancellation race may still return 409.
    - `evidence` object: Optional provider-specific evidence. Fields vary by channel; do not assume a tracking number or proof of a recipient reading the item.

## Other responses

- `401`: Authentication required
- `403`: Insufficient scope
- `500`: Order list could not be read; do not infer no orders exist

---

[API](https://skmtc.dev/postedly/apis/postedly-send-api.md) · [All operations](https://skmtc.dev/postedly/apis/postedly-send-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postedly/apis/postedly-send-api/revisions/c7c71c05f64b?raw)