# List history for an order

`GET /orders/{orderId}/history`

OMS API, Orders.

Returns a paginated, append-only history of the order's lifecycle transitions — creation, payment capture, 3PL submission attempts, failures and skips, fulfillments, status changes, cancellation, age-out — each with when it happened, curated context, and what kind of thing caused it. Orders created before history recording was introduced start with an empty history.

**Authentication:** Send `Authorization: Bearer <token>`. Either an identity token issued by the auth service (dashboard flow; requires the selected merchant account id in the `X-Odus-Merchant` header), or a merchant secret key (`sk_...`) for server-to-server calls. Both are sent as `Authorization: Bearer <token>`.

## Parameters

### Path parameters

- `orderId` (string, required)

### Query parameters

- `sortBy` (string): Field to sort by (default: createdAt) One of `id`, `createdAt`.
- `sortDirection` (string): Sort direction (default: desc) One of `asc`, `desc`.
- `page` (number): Page number (default: 1)
- `pageSize` (number): Items per page (default: 10, max: 100)
- `limit` (number): Items per page for cursor pagination (default: 10, max: 100). Sending it switches the response to cursor mode; omit it for offset pagination.
- `cursor` (string): Opaque cursor from a previous response’s `nextCursor` or `prevCursor`. Only read when `limit` is present, and must be used with the same `sortBy`/`sortDirection` it was issued for.

## Responses

### `200`

Type: object.

- `pagination` (object (PageMetaDTO) or object (CursorPageMetaDTO))
  - When the value is PageMetaDTO:
    - `page` (number, required)
    - `pageSize` (number, required)
    - `totalItems` (number, required)
    - `totalPages` (number, required)
  - When the value is CursorPageMetaDTO:
    - `mode` (constant `cursor`, required): Discriminator identifying cursor-based pagination metadata. Example: `cursor`.
    - `pageSize` (number, required): Number of items requested per page. Minimum 1. Example: `10`.
    - `hasNextPage` (boolean, required): Whether a next page exists. Example: `false`.
    - `hasPreviousPage` (boolean, required): Whether a previous page exists. Example: `true`.
    - `nextCursor` (string, required, nullable): Opaque cursor for fetching the next page. Null when there is no next page. Example: `eyJzIjoiY3JlYXRlZEF0IiwiZCI6ImFzYyIsIm4iOiJmb3J3YXJkIn0`.
    - `prevCursor` (string, required, nullable): Opaque cursor for fetching the previous page. Null when there is no previous page. Example: `eyJzIjoiY3JlYXRlZEF0IiwiZCI6ImFzYyIsIm4iOiJiYWNrd2FyZCJ9`.
- `data` (array of object (OrderHistoryEntryDTO))
  - `createdAt` (string (date-time), required): The date and time when the entity was created. Example: `2024-02-18T12:00:00Z`.
  - `updatedAt` (string (date-time), required, nullable): The date and time when the entity was last updated. Example: `2024-02-21T12:15:00Z`.
  - `metadata` (map of string to string, required, nullable): Metadata used by merchants to store additional information about the entity.
  - `id` (string, required)
  - `order` (string, required): ID of the order this entry belongs to. Example: `ord_2c9NxQ3jSVWpaAqEbTORrivRV20`.
  - `type` (string, required): Which lifecycle transition this entry records. One of `order_created`, `items_added`, `payment_captured`, `customer_updated`, `status_changed`, `tpl_submission_succeeded`, `tpl_submission_failed`, `tpl_submission_dead_letter`, `tpl_submission_awaiting_funds`, `tpl_submission_rearmed`, `tpl_submission_skipped`, `fulfillment_route_skipped`, `tpl_submission_items_withheld`, `fulfillment_created`, `fulfillment_tracking_updated`, `aged_out`, `aged_out_cleared`, `tpl_hold`, `tpl_resubmitted`, `tpl_hold_awaiting_funds`, `tpl_hold_released`, `cancelled_units_shipped`, `tpl_cancellation_requested`, `tpl_address_update_requested`. Example: `status_changed`.
  - `source` (string, required): What kind of thing caused the transition — a dashboard user, an API call, the payment import, an inbound webhook, or the system acting on its own (cron-driven retries, age-out). Provenance only; no user attribution. One of `user`, `api`, `import`, `webhook`, `system`. Example: `system`.
  - `details` (map of string to (string or number or boolean or array of string or null), required, nullable): Curated context for the transition. The keys depend on the type — e.g. a failed 3PL submission carries the integration, attempt number, error and next retry time. A customer update carries `fields`, naming which parts of the customer details changed, and `addressFields` when the shipping address is one of them, naming the parts of the address that changed. A `cancelled_units_shipped` entry carries the `provider`, the shipment's `externalShipmentId`, the identifiers the provider assigned the shipment when it shipped in `shipmentIds`, the tracking number to follow it by in `trackingNumber`, its `carrier`, the cancelled `skus` it carried and their total `quantity`. A `tpl_cancellation_requested` entry records that an order you cancelled was cancelled at its provider too: it carries the `provider`, the provider's order number in `externalOrderId`, and the provider's answer in `outcome` — `cancelled`; `partially_cancelled`, when the provider cancelled only part of the order; `cancelling`, when the provider's warehouse was already preparing the order and decides whether it can still stop it; `not_cancellable`, when the provider had already started shipping the order or had closed it, with the provider's `code` when it gives one; or `failed`, when the request could not be made, with the `reason`. A `tpl_address_update_requested` entry records that the order's shipping address was sent to ShipBob, for an order ShipBob holds because it could not validate the address — after you corrected the customer, or when you resubmitted the order: it carries the `provider`, the provider's order number in `externalOrderId`, and the provider's answer in `outcome` — `updated`, when the provider saved the address, and the order stays on hold until the provider releases it; `partially_updated`, when the provider saved it for some of the shipments it holds but not for the rest, with the provider's `code` when it refused one; `not_held`, when the provider no longer held the order for its address, so nothing was sent; `refused`, when the provider did not accept the address, with the provider's `code` when it gives one; or `failed`, when the request could not be made, with the `reason`. A resubmission made for you because you corrected the customer carries `trigger` `customer_updated`, the type of the entry recording that correction. Entries that carry an `integrationId` also gain an `integrationName` at read time — the integration's current user-given name — when the integration still exists. Values from the customer details themselves are never recorded: an entry says what changed, not what it changed to.

### `202`

The merchant is entitled but its OMS environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to an active-entitled merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.

Type: object (ProvisioningInProgress).

- `status` (string, required): Signals the merchant OMS environment is still being provisioned. One of `provisioning`.
- `merchantAccountId` (string, required): The merchant account whose OMS environment is being provisioned. Example: `dAI3aa87ROOeupeBCjNSKCOBOisBCYjB`.

### `400`

The request was rejected. `type` is `invalid_request_error`; when the failure is a validation failure `code` is `validation_failed` and `errors` lists every problem found, with field-attributable entries prefixed by the field’s path.

Type: object (ValidationErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): The first error message from the validation errors. Example: `note must be a string`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.
- `errors` (array of string): Complete list of validation errors.

### `401`

No credentials were supplied, or the identity token / secret key is not valid for the target merchant. `type` is `authentication_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `403`

The credentials are valid but lack the permission this operation requires. `type` is `permission_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `404`

No resource exists with the requested identifier. `type` is `not_found_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `429`

Too many requests. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `500`

The request could not be completed because of an unexpected error. `type` is `api_error`.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `503`

A dependency needed to serve the request is temporarily unavailable — for every operation the auth service that verifies credentials and resolves entitlement, and on the provisioning routes also the ODUS API the OMS reconciles against. `type` is `api_error`. Unlike a plain 500 the condition is transient rather than a fault in the request, so it is worth retrying with backoff.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

### `504`

The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect.

Type: object (ErrorResponse).

- `statusCode` (number, required): HTTP status code. Example: `400`.
- `requestId` (string, required): Unique identifier for the request. Example: `dfc10de3-36bb-4bcc-b081-316216194033`.
- `message` (string, required): Human-readable description of the failure. Example: `An error occurred`.
- `type` (string, required): Coarse, stable classifier for the failure. Present on every error response including 5xx. This is the field to branch on: `statusCode` is too coarse and `message` is human prose that may be reworded. The set is closed and every member is permanent, so it is safe to handle exhaustively. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `invalid_state_error`, `conflict_error`, `rate_limit_error`, `payment_error`, `api_error`. Example: `invalid_request_error`.
- `code` (string): Fine-grained identifier for the failure, present only where it adds something `type` does not — for example separating a replayed idempotency key from a held lock, or naming the reason a payment was declined. The set is open and grows over time, so treat an unrecognised value as absent and fall back to `type`. Example: `validation_failed`.

---

Generated from the OMS API OpenAPI document, https://sandbox-oms-api.odus.com/openapi.json. Interactive page: https://docs.odus.com/docs/api/oms/order-controller-find-history