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

# Add Order Timeline Note

> Add a note to an order's timeline

<Note>
  **V2 Preview** — This endpoint is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

Add a note to the timeline of a specific order. This creates a timestamped entry visible to both the vendor and the merchant.

### Use Cases

* **Internal notes** — Record shipping updates, special handling instructions, or delays
* **Communication trail** — Leave a message for the merchant about the order
* **Status updates** — Document progress on custom or made-to-order items

## Headers

<ParamField header="x-access-token" type="string" required>
  A valid vendor JWT. Requires `orders:write` scope.
</ParamField>

## Path Parameters

<ParamField path="orderId" type="string" required>
  The `_id` of the order.
</ParamField>

## Request Body

<ParamField body="message" type="string" required>
  The note text to add to the timeline.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "_id": "664a1b2c3d4e5f6a7b8c9d10",
    "message": "Customer requested gift wrapping — added to package",
    "type": "note",
    "createdBy": "vendor@example.com",
    "createdAt": "2026-05-17T09:15:00Z"
  }
}
```

### Error Responses

```json 400 theme={null}
{ "success": false, "error": { "message": "\"message\" is required", "code": "VALIDATION_ERROR" } }
```

```json 401 theme={null}
{ "success": false, "error": { "message": "Invalid or expired token" } }
```

```json 404 theme={null}
{ "success": false, "error": { "message": "Order not found", "code": "NOT_FOUND" } }
```

## Example

```bash theme={null}
curl -X POST "https://staging-api.puppetvendors.com/orders/507f1f77bcf86cd799439011/timeline" \
  -H "Content-Type: application/json" \
  -H "x-access-token: YOUR_VENDOR_JWT" \
  -d '{
    "message": "Customer requested gift wrapping — added to package"
  }'
```