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

# Orders

> Order retrieval, HR decisions, contract data, products, and downloadable order documents.

Orders are read-only except for the dedicated HR decision operation.

## Status values

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
under_review  rejected  approved  active  archived  withdrawn
```

Only `under_review` can be changed by the public decision operation, to `approved` or `rejected`.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram-v2
    [*] --> under_review
    under_review --> approved: public decision
    under_review --> rejected: public decision
    approved --> active: outside decision endpoint
    active --> archived: outside decision endpoint
    under_review --> withdrawn: outside decision endpoint
```

## Endpoints

<CardGroup cols={2}>
  <Card title="List orders" icon="list" href="/api-reference/orders/list-orders">
    Retrieve orders by status, employee, dates, and documented scalar fields. Use `X-Tenant-ID` to restrict the tenant context where required.
  </Card>

  <Card title="Get an order" icon="shopping-bag" href="/api-reference/orders/get-order">
    Read products, contract fields, employee, status, and attachment references.
  </Card>

  <Card title="Approve or reject" icon="badge-check" href="/api-reference/orders/decide-order">
    Validate and apply one HR decision from `under_review`.
  </Card>

  <Card title="Download attachment" icon="download" href="/api-reference/orders/download-attachment">
    Download a contract document by attachment ID.
  </Card>
</CardGroup>

## Order response model

The provider's updated schema no longer returns `tenant` or `divisionId` inside an order. Tenant restriction remains available through `X-Tenant-ID` where the operation documents that header.

HR review data is returned in `hrHistory`:

| Field         | Type                | Meaning                                                                       |
| ------------- | ------------------- | ----------------------------------------------------------------------------- |
| `approvedBy`  | string or `null`    | User ID associated with approval when available                               |
| `approvedAt`  | date-time or `null` | Approval timestamp                                                            |
| `rejectedBy`  | string or `null`    | Rejecting user ID, or `null` for automated decisions and orders not rejected  |
| `rejectedAt`  | date-time or `null` | Rejection timestamp                                                           |
| `requestedAt` | date-time or `null` | Time at which HR review was requested                                         |
| `decisionBy`  | string or `null`    | User ID that made the decision, or `null` for automated and API-key decisions |

`hrHistory` replaces the previous `hrReviewDecision` object. The old actor-category enum in `decisionBy` is no longer part of the provider schema.

## Product response model

Each entry in `products[]` exposes product identity, classification, VAT, gross and net amounts, optional service amounts, and the accessory flag.

| Field              | Type                     | Meaning                                                     |
| ------------------ | ------------------------ | ----------------------------------------------------------- |
| `id`               | string                   | Product identifier                                          |
| `label`            | string                   | Complete product label including the selected configuration |
| `model`            | string or `null`         | Product model name when available                           |
| `vatRate`          | decimal string           | VAT percentage with two decimal places                      |
| `manufacturerName` | string or `null`         | Manufacturer display name when available                    |
| `articleGroupName` | string or `null`         | Assigned article group when available                       |
| `grossAmount`      | decimal string           | Gross monthly amount with two decimal places                |
| `netAmount`        | decimal string           | Net monthly amount with four decimal places                 |
| `service`          | boolean or `null`        | Whether a service is selected; `null` for an accessory      |
| `grossService`     | decimal string or `null` | Gross service amount, when applicable                       |
| `netService`       | decimal string or `null` | Net service amount, when applicable                         |
| `isAccessory`      | boolean                  | Whether the entry is an accessory                           |

<Warning>
  The current API version remains `1.0.0`, but the order response shape has changed. Update generated clients, DTOs, deserializers, mappings, calculations, mocks, and contract tests before adopting the refreshed schema. Do not interpret the new decimal strings as integer cents.
</Warning>

## Decision rules

* Re-read the order immediately before deciding.
* Use dry run before the real decision.
* A final decision cannot be overwritten through the endpoint.
* Approval applies documented contract-date defaults and corresponding notifications.
* The contract does not enumerate notification recipients; do not depend on an undocumented list.
* After a timeout, re-read the order before any replay.

<Card title="Order processing guide" icon="workflow" horizontal href="/guides/process-orders">
  Follow the review swimlane, state checks, conflict handling, and timeout reconciliation.
</Card>