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

# Avalex Orders API — Create and Manage Order Records

> Create and retrieve order records in Avalex. Each order links a customer to one or more products and their associated license IDs.

The `/orders` resource records purchase transactions in Avalex. An order captures which customer made a purchase, which products were included, the total amount charged, and the IDs of any licenses that were generated as a result. Orders provide an auditable paper trail connecting your customers, products, and licenses in a single record.

## Required Permissions

| Action                 | Permission      |
| ---------------------- | --------------- |
| List / retrieve orders | `orders:read`   |
| Create / update orders | `orders:write`  |
| Delete orders          | `orders:delete` |

***

## List All Orders

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

Returns an array of all order records in your Avalex account.

```bash theme={null}
curl http://localhost:8080/orders \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

```json theme={null}
[
  {
    "id": "ord_123",
    "customerId": "cust_123",
    "productIds": ["prod_123"],
    "totalAmount": 299.99,
    "licenseIds": ["lic_12345"],
    "createdAtEpochMillis": 1723140000000
  }
]
```

***

## Create an Order

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

<ParamField body="customerId" type="string" required>
  ID of the customer placing the order.
</ParamField>

<ParamField body="productIds" type="string[]" required>
  Array of product IDs included in this order.
</ParamField>

<ParamField body="totalAmount" type="number" required>
  Total charged amount in your account's base currency.
</ParamField>

<ParamField body="licenseIds" type="string[]">
  Array of license IDs to associate with this order. These should reference licenses already created via `/licenses`.
</ParamField>

Creates a new order record and returns it with a server-generated ID.

```bash theme={null}
curl -X POST http://localhost:8080/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_123",
    "productIds": ["prod_123"],
    "totalAmount": 299.99,
    "licenseIds": ["lic_12345"]
  }'
```

**Response — 201 Created**

```json theme={null}
{
  "id": "ord_123",
  "customerId": "cust_123",
  "productIds": ["prod_123"],
  "totalAmount": 299.99,
  "licenseIds": ["lic_12345"],
  "createdAtEpochMillis": 1723140000000
}
```

***

## Get an Order by ID

<ParamField path="id" type="string" required>
  The unique order ID (e.g. `ord_123`).
</ParamField>

Returns a single order record. Responds with `404 Not Found` if no order with that ID exists.

```bash theme={null}
curl http://localhost:8080/orders/ord_123 \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

```json theme={null}
{
  "id": "ord_123",
  "customerId": "cust_123",
  "productIds": ["prod_123"],
  "totalAmount": 299.99,
  "licenseIds": ["lic_12345"],
  "createdAtEpochMillis": 1723140000000
}
```

***

## Update an Order

<ParamField path="id" type="string" required>
  The unique order ID.
</ParamField>

Performs a full replacement of the order record. You must include all fields you want to retain. Returns `404 Not Found` if the order does not exist.

<Note>
  This is a full replacement (`PUT`). Omitted fields — such as `licenseIds` — will be cleared. Include all existing values you want to keep.
</Note>

```bash theme={null}
curl -X PUT http://localhost:8080/orders/ord_123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_123",
    "productIds": ["prod_123"],
    "totalAmount": 349.99,
    "licenseIds": ["lic_12345"]
  }'
```

**Response — 200 OK**

```json theme={null}
{
  "id": "ord_123",
  "customerId": "cust_123",
  "productIds": ["prod_123"],
  "totalAmount": 349.99,
  "licenseIds": ["lic_12345"],
  "createdAtEpochMillis": 1723140000000
}
```

***

## Delete an Order

<ParamField path="id" type="string" required>
  The unique order ID.
</ParamField>

Permanently removes the order record. Returns `204 No Content` on success and `404 Not Found` if the ID does not exist.

```bash theme={null}
curl -X DELETE http://localhost:8080/orders/ord_123 \
  -H "Authorization: Bearer <token>"
```

**Response — 204 No Content**

***

## Order Schema

<Expandable title="Order fields">
  <ResponseField name="id" type="string">
    Unique identifier for the order, assigned by Avalex on creation (e.g. `ord_123`).
  </ResponseField>

  <ResponseField name="customerId" type="string">
    ID of the customer who placed this order.
  </ResponseField>

  <ResponseField name="productIds" type="string[]">
    Array of product IDs included in this order. An order may reference one or more products.
  </ResponseField>

  <ResponseField name="totalAmount" type="number">
    Total charged amount for the order in your account's base currency.
  </ResponseField>

  <ResponseField name="licenseIds" type="string[]">
    Array of license IDs associated with this order. Each entry references a license record in `/licenses`.
  </ResponseField>

  <ResponseField name="createdAtEpochMillis" type="number">
    Unix timestamp in milliseconds representing when this order was created.
  </ResponseField>
</Expandable>

### Full Schema Example

```json theme={null}
{
  "id": "ord_123",
  "customerId": "cust_123",
  "productIds": ["prod_123"],
  "totalAmount": 299.99,
  "licenseIds": ["lic_12345"],
  "createdAtEpochMillis": 1723140000000
}
```