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

# List Orders

> Retrieve a paginated list of orders for your store with search and filtering.

## Query parameters

<ParamField query="q" type="string">
  Search by order name/number or customer email. Performs a partial, case-insensitive match.
</ParamField>

<ParamField query="email" type="string">
  Filter by customer email address. Partial, case-insensitive match.
</ParamField>

<ParamField query="status" type="string">
  Filter by financial status. Accepts: `paid`, `pending`, `partially_paid`, `partially_refunded`, `refunded`, `voided`, `authorized`.
</ParamField>

<ParamField query="shopify_product_id" type="integer">
  Only return orders that bought a specific Shopify product. Matches the Shopify
  product behind the order's digital products — useful for targeting buyers of a
  single product.
</ParamField>

<ParamField query="digital_product_id" type="string">
  Only return orders linked to a specific Filemonk digital product (collection
  UUID). Can be combined with `shopify_product_id`.
</ParamField>

<ParamField query="created_at_min" type="string">
  Filter orders created on or after this date. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="created_at_max" type="string">
  Filter orders created on or before this date. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of orders per page. Minimum: 1, maximum: 250.
</ParamField>

<ParamField query="sort" type="string" default="created_at_desc">
  Sort order. Accepts: `created_at_desc`, `created_at_asc`, `name_asc`, `name_desc`.
</ParamField>

## Response

<ResponseField name="orders" type="array" required>
  List of order objects.

  <Expandable title="Order properties">
    <ResponseField name="id" type="string" required>
      Unique order identifier (UUID).
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Order name/number, e.g. `#1001`.
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Customer email address.
    </ResponseField>

    <ResponseField name="phone" type="string | null">
      Customer phone number.
    </ResponseField>

    <ResponseField name="financial_status" type="string | null">
      Financial status: `paid`, `pending`, `partially_paid`, `partially_refunded`, `refunded`, `voided`, or `authorized`.
    </ResponseField>

    <ResponseField name="fulfillment_status" type="string | null">
      Fulfillment status, e.g. `fulfilled`, `partial`.
    </ResponseField>

    <ResponseField name="total_price" type="string | null">
      Total price of the order.
    </ResponseField>

    <ResponseField name="currency" type="string | null">
      ISO 4217 currency code, e.g. `USD`.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp of when the order was created in Shopify.
    </ResponseField>

    <ResponseField name="download_count" type="integer" required>
      Total number of file downloads across all files in this order.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata.

  <Expandable title="Pagination properties">
    <ResponseField name="current_page" type="integer" required>
      Current page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Number of items per page.
    </ResponseField>

    <ResponseField name="total_count" type="integer" required>
      Total number of orders matching the filters.
    </ResponseField>

    <ResponseField name="total_pages" type="integer" required>
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://app.filemonk.io/api/v1/external/orders?status=paid&per_page=10' \
    -H 'X-Auth-Token: fm_api_key_your_key_here'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://app.filemonk.io/api/v1/external/orders?status=paid&per_page=10',
    { headers: { 'X-Auth-Token': 'fm_api_key_your_key_here' } }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.filemonk.io/api/v1/external/orders',
      headers={'X-Auth-Token': 'fm_api_key_your_key_here'},
      params={'status': 'paid', 'per_page': 10}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "orders": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "#1042",
        "email": "customer@example.com",
        "phone": "+1234567890",
        "financial_status": "paid",
        "fulfillment_status": "fulfilled",
        "total_price": "29.99",
        "currency": "USD",
        "created_at": "2026-03-01T14:30:00Z",
        "download_count": 3
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "#1041",
        "email": "buyer@example.com",
        "phone": null,
        "financial_status": "paid",
        "fulfillment_status": null,
        "total_price": "9.99",
        "currency": "USD",
        "created_at": "2026-02-28T09:15:00Z",
        "download_count": 1
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total_count": 142,
      "total_pages": 15
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```
</ResponseExample>