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

# Order Lifecycle

> The commercial flow from quote to costed, production-ready sales order

# Order Lifecycle

The order lifecycle is the commercial spine of PLM. A customer enquiry becomes a **quote**, an accepted quote converts to a **sales order**, the order is **costed** against its BOM, and the approved order is released to **MES** as a production order. **Sample plans** and **labor cost** estimation run alongside to validate feasibility and margin.

## The flow

```mermaid theme={null}
flowchart LR
    Draft[Quote draft] --> Submit[Submit quote]
    Submit --> Accept{Accepted?}
    Accept -->|reject| Closed[Closed]
    Accept -->|accept| Convert[Convert to Sales Order]
    Convert --> SO[Sales Order]
    SO --> Costing[Costing]
    Costing --> Approve{Approved?}
    Approve -->|reject| Costing
    Approve -->|approve| Prod[Production Order · MES]
```

```mermaid theme={null}
sequenceDiagram
    actor Staff
    participant API
    participant Quote
    participant SalesOrder
    participant Costing
    participant MES

    Staff->>API: POST /quotes (draft)
    API->>Quote: create
    Staff->>API: PUT /quotes/{id}/submit
    Staff->>API: PUT /quotes/{id}/accept
    Staff->>API: POST /quotes/{id}/convert-to-sales-order
    API->>SalesOrder: create order
    SalesOrder-->>Staff: order id
    Staff->>API: POST /costings (for order)
    API->>Costing: build cost sheet from BOM
    Staff->>API: POST /costings/{id}/submit
    Staff->>API: POST /costings/{id}/approve
    Costing->>MES: release production order
    MES-->>Staff: production order created
```

## Quotes

A quote is the first commercial artifact. It starts as a draft, is submitted for review, and is accepted or rejected by the client. An accepted quote can be converted into a sales order in one call.

```bash theme={null}
GET /api/v1/quotes
Authorization: Bearer <access_token>
```

### Create a quote

<ParamField body="client_id" type="string" required>
  The client this quote is for.
</ParamField>

<ParamField body="style_id" type="string">
  Optional style this quote prices.
</ParamField>

<ParamField body="lines" type="array" required>
  Quote line items with quantity and unit price.
</ParamField>

```bash theme={null}
POST /api/v1/quotes
Authorization: Bearer <access_token>

{
  "client_id": "uuid",
  "style_id": "uuid",
  "lines": [
    { "description": "Crew neck tee", "quantity": 1000, "unit_price": 4.20 }
  ]
}
```

**Response (201):**

```json theme={null}
{
  "id": "uuid",
  "ref": "QT-2026-0042",
  "status": "draft",
  "total": 4200.00
}
```

### Move a quote through its states

```bash theme={null}
PUT /api/v1/quotes/{quote_id}/submit
PUT /api/v1/quotes/{quote_id}/accept
PUT /api/v1/quotes/{quote_id}/reject
```

### Convert to a sales order

Once accepted, convert the quote directly into a sales order. Line items and pricing carry over.

```bash theme={null}
POST /quotes/{quote_id}/convert-to-sales-order
Authorization: Bearer <access_token>
```

**Response (201):**

```json theme={null}
{
  "order_id": "uuid",
  "order_ref": "SO-2026-0042",
  "status": "open"
}
```

<Tip>
  Use `PUT /api/v1/quotes/{quote_id}` to revise pricing while the quote is still in draft. Submitted quotes should be revised through a new version rather than edited in place.
</Tip>

## Sales Orders

The sales order is the confirmed commercial commitment. It tracks order quantities, delivery dates, and links to the costing and production order.

```bash theme={null}
GET /api/v1/orders
POST /api/v1/orders
GET /api/v1/orders/{document_id}
PATCH /api/v1/orders/{document_id}
Authorization: Bearer <access_token>
```

<Note>
  Most orders are created via `convert-to-sales-order`. Use `POST /api/v1/orders` directly only when there is no originating quote.
</Note>

## Costing Management

Costing turns the BOM into a cost sheet — material, labor, and overhead rolled into a unit cost and margin. Cost sheets are versioned and run through a submit → approve workflow before the order can be released to production.

```bash theme={null}
GET /api/v1/costings
POST /api/v1/costings
GET /api/v1/costings/{costing_id}
PATCH /api/v1/costings/{costing_id}
Authorization: Bearer <access_token>
```

### Approval workflow

```bash theme={null}
POST /api/v1/costings/{costing_id}/submit
POST /api/v1/costings/{costing_id}/approve
POST /api/v1/costings/{costing_id}/reject
POST /api/v1/costings/{costing_id}/withdraw
```

### Analysis and versioning

<ParamField body="target_margin" type="number">
  Target margin to evaluate the cost sheet against.
</ParamField>

```bash theme={null}
POST /api/v1/costings/{costing_id}/margin-analysis
GET  /api/v1/costings/compare
POST /api/v1/costings/{costing_id}/versions
GET  /api/v1/costings/dashboard
```

Cost sheets can be saved as reusable **templates** and instantiated for new orders:

```bash theme={null}
POST /api/v1/costings/templates
POST /api/v1/costings/from-template/{template_id}
```

<Info>
  Approved cost sheets post to **Finindex** via the cost-sheet GL endpoints (`POST /api/v1/cost-sheets/{cost_sheet_id}/post-gl`). See `/finindex`.
</Info>

## Labor Cost

Labor estimation prices the sewing operations behind a style. It can be run standalone or pulled into a cost sheet.

```bash theme={null}
POST /api/v1/labor-cost/estimate
POST /api/v1/labor-cost/compare
Authorization: Bearer <access_token>
```

## Sample Plans

Sample plans schedule and track the pre-production samples (proto, fit, PP) that validate a style before bulk production is released.

```bash theme={null}
GET    /api/v1/sample-plans
POST   /api/v1/sample-plans
PATCH  /api/v1/sample-plans/{plan_id}
DELETE /api/v1/sample-plans/{plan_id}
Authorization: Bearer <access_token>
```

See the **API Reference** tab for the full endpoint list.

## Next

<CardGroup cols={2}>
  <Card title="Procurement" icon="truck" href="/cutmake/plm/procurement">
    Source the materials the costed BOM demands.
  </Card>

  <Card title="MES Production" icon="industry" href="/cutmake/mes">
    Where the approved order is produced.
  </Card>
</CardGroup>