> ## 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 Products API — Create, Read, Update, Delete

> Manage your software product catalog via the Avalex API. Configure license requirements, subscription billing, and default HWID/IP slot limits.

The `/products` resource represents the software titles and services you sell through Avalex. Each product record defines how licensing works — whether a license is required, whether billing recurs on a schedule, and the default number of IP addresses and hardware IDs (HWIDs) that a license for this product allows. When a license is issued for a product, it inherits these defaults unless overridden at the license level.

## Required Permissions

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

***

## List All Products

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

Returns an array of all product records in your catalog.

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

**Response — 200 OK**

```json theme={null}
[
  {
    "id": "prod_123",
    "name": "Enterprise Suite",
    "productType": "software",
    "description": "Full desktop application",
    "price": 299.99,
    "requiresLicense": true,
    "isSubscription": true,
    "recurringPeriodDays": 365,
    "maxIps": 5,
    "maxHwids": 2,
    "createdAtEpochMillis": 1723140000000
  }
]
```

***

## Create a Product

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

<ParamField body="name" type="string" required>
  Display name of the product.
</ParamField>

<ParamField body="productType" type="string" required>
  Category of the product, such as `software`.
</ParamField>

<ParamField body="description" type="string">
  Human-readable description of the product.
</ParamField>

<ParamField body="price" type="number" required>
  Price in your account's base currency.
</ParamField>

<ParamField body="requiresLicense" type="boolean" required>
  Whether customers must have a valid license to use this product.
</ParamField>

<ParamField body="isSubscription" type="boolean" required>
  Whether this product is billed on a recurring schedule.
</ParamField>

<ParamField body="recurringPeriodDays" type="integer">
  Number of days between billing cycles. Only relevant when `isSubscription` is `true`.
</ParamField>

<ParamField body="maxIps" type="integer | null">
  Default maximum number of IP addresses a license for this product may be bound to. Set to `null` for unlimited.
</ParamField>

<ParamField body="maxHwids" type="integer | null">
  Default maximum number of hardware IDs a license for this product may be bound to. Set to `null` for unlimited.
</ParamField>

Creates a new product and returns the created record.

```bash theme={null}
curl -X POST http://localhost:8080/products \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Suite",
    "productType": "software",
    "description": "Full desktop application",
    "price": 299.99,
    "requiresLicense": true,
    "isSubscription": true,
    "recurringPeriodDays": 365,
    "maxIps": 5,
    "maxHwids": 2
  }'
```

**Response — 201 Created**

```json theme={null}
{
  "id": "prod_123",
  "name": "Enterprise Suite",
  "productType": "software",
  "description": "Full desktop application",
  "price": 299.99,
  "requiresLicense": true,
  "isSubscription": true,
  "recurringPeriodDays": 365,
  "maxIps": 5,
  "maxHwids": 2,
  "createdAtEpochMillis": 1723140000000
}
```

***

## Get a Product by ID

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

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

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

**Response — 200 OK**

```json theme={null}
{
  "id": "prod_123",
  "name": "Enterprise Suite",
  "productType": "software",
  "description": "Full desktop application",
  "price": 299.99,
  "requiresLicense": true,
  "isSubscription": true,
  "recurringPeriodDays": 365,
  "maxIps": 5,
  "maxHwids": 2,
  "createdAtEpochMillis": 1723140000000
}
```

***

## Update a Product

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

Performs a full replacement of the product record. You must include all fields you want to retain — omitted fields will be cleared. Returns `404 Not Found` if the product does not exist.

<Note>
  Changing `maxIps` or `maxHwids` on a product does **not** retroactively update licenses that have already been issued. Only new licenses inherit the updated defaults.
</Note>

```bash theme={null}
curl -X PUT http://localhost:8080/products/prod_123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Suite",
    "productType": "software",
    "description": "Full desktop application — v2",
    "price": 349.99,
    "requiresLicense": true,
    "isSubscription": true,
    "recurringPeriodDays": 365,
    "maxIps": 10,
    "maxHwids": 4
  }'
```

**Response — 200 OK**

```json theme={null}
{
  "id": "prod_123",
  "name": "Enterprise Suite",
  "productType": "software",
  "description": "Full desktop application — v2",
  "price": 349.99,
  "requiresLicense": true,
  "isSubscription": true,
  "recurringPeriodDays": 365,
  "maxIps": 10,
  "maxHwids": 4,
  "createdAtEpochMillis": 1723140000000
}
```

***

## Delete a Product

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

Permanently removes the product 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/products/prod_123 \
  -H "Authorization: Bearer <token>"
```

**Response — 204 No Content**

***

## Product Schema

<Expandable title="Product fields">
  <ResponseField name="id" type="string">
    Unique identifier assigned by Avalex on creation (e.g. `prod_123`).
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name of the product as shown in the dashboard and API responses.
  </ResponseField>

  <ResponseField name="productType" type="string">
    Category string describing the kind of product (e.g. `software`).
  </ResponseField>

  <ResponseField name="description" type="string">
    Human-readable description of what the product includes or does.
  </ResponseField>

  <ResponseField name="price" type="number">
    Product price in your account's base currency.
  </ResponseField>

  <ResponseField name="requiresLicense" type="boolean">
    When `true`, customers must hold a valid Avalex license to use this product.
  </ResponseField>

  <ResponseField name="isSubscription" type="boolean">
    When `true`, this product is billed on a recurring schedule defined by `recurringPeriodDays`.
  </ResponseField>

  <ResponseField name="recurringPeriodDays" type="integer">
    Number of days in each billing cycle. Applicable only when `isSubscription` is `true`.
  </ResponseField>

  <ResponseField name="maxIps" type="integer | null">
    Default maximum number of IP addresses a license for this product may bind to. `null` means unlimited. This value is inherited by newly issued licenses.
  </ResponseField>

  <ResponseField name="maxHwids" type="integer | null">
    Default maximum number of hardware IDs a license for this product may bind to. `null` means unlimited. This value is inherited by newly issued licenses.
  </ResponseField>

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

### Full Schema Example

```json theme={null}
{
  "id": "prod_123",
  "name": "Enterprise Suite",
  "productType": "software",
  "description": "Full desktop application",
  "price": 299.99,
  "requiresLicense": true,
  "isSubscription": true,
  "recurringPeriodDays": 365,
  "maxIps": 5,
  "maxHwids": 2,
  "createdAtEpochMillis": 1723140000000
}
```