---
title: "Get an order by id"
method: GET
path: "/api/v1/orders/{id}"
tags: ["orders"]
---

# Get an order by id

`GET /api/v1/orders/{id}`

Returns the full order detail scoped to the caller account: header (id, external order id, channel, status, currency, creation), resolved customer, shipping/billing addresses, items (with metadata), mirrored payments, totals, the resolved state machine (id/code/name/version + transitions of the pinned version), the fulfillment orders block, and a unified chronological timeline that merges order status events, fulfillment order status events and shipment tracking events (each shipment event carries the resolved carrier and tracking code). An order that does not exist, is soft-deleted, or belongs to another account returns 404.

## Path parameters

- `id` string, uuid, required

## Response `200`

The order detail.

- OrderFindResponse
  - `status` object, required
    - `code` string
    - `label` string
    - `color` string, nullable
    - `nature` 'INITIAL' | 'PROCESSING' | 'FINAL' | 'ERROR', nullable
  - `channel` object, required
    - `id` string
    - `code` string, nullable
    - `name` string, nullable
  - `customer` object, nullable, required
    - `id` string
    - `name` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `document` string, nullable
    - `document_type` 'PF' | 'PJ', nullable
    - `external_id` string, nullable
    - `birth_date` string, nullable
  - `state_machine` object, nullable, required
    - `id` string
    - `code` string
    - `name` string
    - `version` number
    - `transitions` object[]
      - `from` string
      - `to` string
  - `metadata` object, nullable, required
  - `timeline` object[], required — Unified chronological timeline of the order journey, merging order status events (type=order), fulfillment order status events (type=fulfillment) and shipment tracking events (type=shipment). Shipment events carry the resolved carrier and tracking code under the shipment block.
    - `id` string
    - `type` 'order' | 'fulfillment' | 'shipment'
    - `status` string
    - `label` string
    - `metadata` object, nullable
    - `occurred_at` string
    - `shipment` object, nullable
      - `id` string
      - `carrier` object, nullable
        - `id` string
        - `code` string
        - `name` string
      - `tracking_code` string, nullable
      - `source` string, nullable
      - `event_id` string, nullable
  - `fulfillments` object[], required
    - `id` string
    - `status` string
    - `store` object, nullable
      - `id` string
      - `code` string
      - `name` string
    - `items` object[]
      - `product_id` string, nullable
      - `sku` string
      - `name` string
      - `quantity` number
  - `id` string, required
  - `external_order_id` string, required
  - `requested_strategy_code` string, nullable, required
  - `source_store` string, nullable, required
  - `shipping_method` string, nullable, required
  - `currency` 'BRL' | 'USD', required
  - `shipping_address` object, required
    - `zip_code` string, required
    - `street` string, required
    - `number` string, required
    - `complement` string, nullable, required
    - `district` string, required
    - `city` string, required
    - `state` string, required
    - `country` string, required
  - `billing_address` object, required
    - `zip_code` string, required
    - `street` string, required
    - `number` string, required
    - `complement` string, nullable, required
    - `district` string, required
    - `city` string, required
    - `state` string, required
    - `country` string, required
  - `items` object[], required
    - `sku` string, required
    - `name` string, required
    - `category` string, nullable, required
    - `quantity` number, required
    - `unit_price` number, required
    - `discount` number, required
    - `total_price` number, required
    - `metadata` object, nullable, required
  - `payments` object[], required
    - `id` string, required
    - `method` string, required
    - `amount` number, required
    - `currency` 'BRL' | 'USD', required
    - `installments` number, required
    - `status` 'PENDING' | 'PAID' | 'REJECTED' | 'REFUNDED', required
    - `gateway` string, nullable, required
    - `gateway_payment_id` string, nullable, required
    - `authorization_code` string, nullable, required
    - `nsu` string, nullable, required
    - `acquirer` string, nullable, required
    - `card` object, required
      - `brand` string, nullable
      - `last4` string, nullable
      - `funding` string, nullable
      - `exp_month` number, nullable
      - `exp_year` number, nullable
    - `pix` object, required
      - `txid` string, nullable
      - `e2eid` string, nullable
      - `qr_code` string, nullable
      - `expires_at` string, nullable
    - `boleto` object, required
      - `digitable_line` string, nullable
      - `url` string, nullable
      - `due_date` string, nullable
    - `paid_at` string, nullable, required
    - `refunded_at` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
  - `totals` object, required
    - `subtotal` number, required
    - `shipping` number, required
    - `discount` number, required
    - `total` number, required
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `400` — Invalid path parameter: id is not a UUID.
- `401` — Authentication is missing, malformed, expired, or refers to a session that is no longer active.
- `403` — The caller is authenticated but lacks the required permission for this action.
- `404` — Order not found in the caller account.
- `500` — Unexpected server error. The response body never leaks internal details.

## Changes

- **2026-07-07** `a3b4750a505f` — 13 info
  - added the required property `billing_address` to the response with the `200` status
  - added the required property `created_at` to the response with the `200` status
  - added the required property `currency` to the response with the `200` status
  - added the required property `external_order_id` to the response with the `200` status
  - …9 more
- **2026-07-07** `84194c31ab85` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kruzer-corp/apis/oms-api/changes/api/v1/orders/:id/get.md)

---

[API](https://skmtc.dev/kruzer-corp/apis/oms-api.md) · [All operations](https://skmtc.dev/kruzer-corp/apis/oms-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kruzer-corp/oms-api/revisions/38ef6e16a7a8/schema)