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

# List Products

> Retrieve a paginated list of products with optional filtering and sorting

Retrieves a paginated list of all products. You can filter and sort the results using query parameters.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve (1-indexed).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of products to return per page. Must be one of: `5`, `10`, `25`, `50`, or `100`. Values exceeding `100` are capped automatically.
</ParamField>

<ParamField query="filters" type="string">
  A JSON-encoded array of filter objects. Each filter object has the following properties:

  <Expandable title="Filter Object">
    <ParamField body="field" type="string" required>
      The field to filter on. Supported fields:

      | Field               | Description                                                |
      | ------------------- | ---------------------------------------------------------- |
      | `fee_type`          | The pricing class of the product (e.g. `fixed`, `metered`) |
      | `metric_ids`        | Metric IDs associated with the product                     |
      | `payment_terms`     | Payment terms (e.g. `arrears`, `advance`)                  |
      | `billing_frequency` | Billing frequency (e.g. `recurring`, `one_time`)           |
      | `tag_ids`           | Tag IDs associated with the product                        |
    </ParamField>

    <ParamField body="operator" type="string" required>
      The comparison operator. All product filter fields support the `in` operator for matching any value in a comma-separated list.
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match against. Use comma-separated values with the `in` operator.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="sort" type="string">
  Sort specification in `field:order` format. Order is either `asc` (ascending) or `desc` (descending).

  Sortable fields: `name`, `fee_type`, `metric_ids`, `payment_terms`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.alguna.io/products?page=1&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with filters and sort) theme={null}
  curl -G "https://api.alguna.io/products" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'page=1' \
    --data-urlencode 'limit=10' \
    --data-urlencode 'filters=[{"field":"fee_type","operator":"in","value":"fixed,metered"}]' \
    --data-urlencode 'sort=name:asc'
  ```

  ```javascript Node.js theme={null}
  const products = await alguna.products.list({
    page: 1,
    limit: 25,
    filters: [
      { field: "fee_type", operator: "in", value: "metered" }
    ],
    sort: "name:asc"
  });
  ```
</RequestExample>

## Response

<Snippet file="products-create-response.mdx" />

<ResponseField name="items" type="array">
  List of product objects.

  <Expandable title="Product Object">
    <ResponseField name="id" type="string">
      The unique identifier for the product.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the product.
    </ResponseField>

    <ResponseField name="description" type="string">
      A brief description of the product.
    </ResponseField>

    <ResponseField name="sku" type="string">
      A product code used in external ERP solutions or revenue recognition.
    </ResponseField>

    <ResponseField name="feeType" type="string">
      The fee type of the product, indicating whether the cost is fixed or based on usage (metered).
    </ResponseField>

    <ResponseField name="paymentTerms" type="string">
      The payment terms for the product, such as arrears.
    </ResponseField>

    <ResponseField name="billingFrequency" type="string">
      The frequency at which the product is billed, e.g., recurring.
    </ResponseField>

    <ResponseField name="metricIds" type="[]string">
      The identifiers for the associated metrics. This field is applicable for metered products.
    </ResponseField>

    <ResponseField name="createdAt" type="datetime">
      The timestamp when the product was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="datetime">
      The timestamp when the product was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Total number of pages available based on the current limit.
</ResponseField>

<ResponseField name="limit" type="integer">
  The number of items per page used for this request.
</ResponseField>