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

# List Receipts

> Retrieve all receipts with support for filters and sorting

## Purpose

Speeds up your reconciliation flows by listing sales receipts by date, amount, or status.

## HTTP Request

```http theme={null}
GET https://integrations.clopos.com/open-api/v2/receipts
```

<Warning>
  This endpoint requires authentication. Include your JWT in the `x-token` header. See [Authentication](/authentication) for how to obtain a token and [Errors](/errors) for error responses.
</Warning>

## Query Parameters

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

<ParamField query="limit" type="integer" default="50">
  Number of receipts per page.
</ParamField>

<ParamField query="date[0]" type="string">
  Start date of a `created_at` range, inclusive. Format: `YYYY-MM-DD`. Pair with `date[1]`.
</ParamField>

<ParamField query="date[1]" type="string">
  End date of a `created_at` range, inclusive. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="sort[0]" type="string">
  Field to sort by (e.g. `created_at`, `updated_at`, `closed_at`, `total`). Inspect the `sorts` array in the response to discover all sortable fields the API currently supports.
</ParamField>

<ParamField query="sort[1]" type="integer">
  Sort direction: `1` = ascending, `-1` = descending.
</ParamField>

<ParamField query="with[]" type="array[string]">
  Related resources to include in each receipt. Repeat with indexed brackets (e.g. `with[0]=receipt_products&with[1]=receipt_products.modificators`). Common values:

  * `receipt_products` — line items on each receipt
  * `receipt_products.modificators` — modifiers applied to each line item
  * `receipt_products.product.unit`, `receipt_products.product.station` — product relations
</ParamField>

<ParamField query="filters[N]" type="array">
  Field-level filter tuples using PHP bracket notation: `filters[N][0]=field_name&filters[N][1]=value`. Stack filters by incrementing `N` (0-based). Commonly used with `status`, `sale_type_id`, `terminal_id`.
</ParamField>

## Request Example

<CodeGroup>
  ```bash curl theme={null}
  # Basic request with filters
  curl --location --globoff "https://integrations.clopos.com/open-api/v2/receipts?page=1&sort[0]=created_at&sort[1]=-1&limit=50&date[0]=2026-01-19&date[1]=2026-01-19" \
    -H "x-token: oauth_example_token"

  # With products and modifiers
  curl --location --globoff "https://integrations.clopos.com/open-api/v2/receipts?page=1&sort[0]=created_at&sort[1]=-1&limit=50&date[0]=2026-01-19&date[1]=2026-01-19&with[0]=receipt_products.product.unit&with[1]=receipt_products.product.station&with[2]=receipt_products.modificators.modificator_group" \
    -H "x-token: oauth_example_token"
  ```

  ```javascript javascript theme={null}
  const headers = { 'x-token': 'oauth_example_token' };

  // Basic request with filters
  const params = new URLSearchParams({
    'page': '1',
    'sort[0]': 'created_at',
    'sort[1]': '-1',
    'limit': '50',
    'date[0]': '2026-01-19',
    'date[1]': '2026-01-19'
  });

  const response = await fetch(
    `https://integrations.clopos.com/open-api/v2/receipts?${params}`,
    { headers }
  );
  const receipts = await response.json();

  // With products and modifiers
  const paramsWithProducts = new URLSearchParams({
    'page': '1',
    'sort[0]': 'created_at',
    'sort[1]': '-1',
    'limit': '50',
    'date[0]': '2025-08-12',
    'date[1]': '2025-08-18',
    'with[0]': 'receipt_products.product.unit',
    'with[1]': 'receipt_products.product.station',
    'with[2]': 'receipt_products.modificators.modificator_group'
  });

  const responseWithProducts = await fetch(
    `https://integrations.clopos.com/open-api/v2/receipts?${paramsWithProducts}`,
    { headers }
  );
  const receiptsWithProducts = await responseWithProducts.json();
  ```

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

  url = "https://integrations.clopos.com/open-api/v2/receipts"
  headers = {
      "x-token": "oauth_example_token",
  }

  # Basic request with filters
  params = {
      "page": 1,
      "sort[0]": "created_at",
      "sort[1]": -1,
      "limit": 50,
      "date[0]": "2026-01-19",
      "date[1]": "2026-01-19"
  }

  response = requests.get(url, headers=headers, params=params)
  receipts = response.json()

  # With products and modifiers
  params_with_products = {
      "page": 1,
      "sort[0]": "created_at",
      "sort[1]": -1,
      "limit": 50,
      "date[0]": "2025-08-12",
      "date[1]": "2025-08-18",
      "with[0]": "receipt_products.product.unit",
      "with[1]": "receipt_products.product.station",
      "with[2]": "receipt_products.modificators.modificator_group"
  }

  response = requests.get(url, headers=headers, params=params_with_products)
  receipts_with_products = response.json()
  ```
</CodeGroup>

## Response

### 200 OK — List of receipts

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 1,
      "venue_id": 1,
      "cid": "96ab5d26-d6bb-4976-a6f8-9e8806ef6aa5",
      "customer_id": null,
      "sale_type_id": 2,
      "source": "web",
      "guests": 1,
      "status": 2,
      "order_status": "IN_PROGRESS",
      "order_number": "006",
      "lock": false,
      "total": 33000,
      "subtotal": 33000,
      "discount_type": 0,
      "discount_value": 0,
      "discount_rate": 0,
      "total_discount": 0,
      "service_charge": 0,
      "service_charge_value": 0,
      "delivery_fee": 0,
      "remaining": 0,
      "i_tax": 0,
      "e_tax": 0,
      "total_tax": 0,
      "payment_methods": [
        {
          "id": 1,
          "name": "Cash",
          "amount": 33000
        }
      ],
      "fiscal_id": null,
      "loyalty_type": null,
      "loyalty_value": null,
      "address": null,
      "description": null,
      "created_at": "2026-01-19 14:51:33",
      "updated_at": "2026-01-19 15:07:49",
      "closed_at": "2026-01-19 15:07:49",
      "shift_date": "2026-01-19"
    }
  ],
  "total": 1
}
```

### 400 Bad Request — Parameter error

```json theme={null}
{
  "success": false,
  "error": "invalid_parameter",
  "message": "sort[1] must be 1 or -1"
}
```

### 401 Unauthorized — Missing header

```json theme={null}
{
  "success": false,
  "error": "unauthorized",
  "message": "Missing authentication headers"
}
```

## Field Reference

### Receipt object

| Field                  | Type         | Description                                                                                                       |
| ---------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `id`                   | number       | Unique receipt identifier.                                                                                        |
| `cid`                  | string       | Client-generated UUID for the receipt.                                                                            |
| `venue_id`             | number       | Venue (location) the receipt belongs to.                                                                          |
| `customer_id`          | number\|null | Customer associated with the receipt.                                                                             |
| `sale_type_id`         | number       | Sale type identifier (e.g., dine-in, delivery).                                                                   |
| `source`               | string       | Origin of the receipt (e.g., `"web"`, `"pos"`).                                                                   |
| `guests`               | number       | Number of guests on the receipt.                                                                                  |
| `status`               | number       | Receipt status: `1` = open, `2` = closed.                                                                         |
| `order_status`         | string       | Order workflow status. One of: `NEW`, `SCHEDULED`, `IN_PROGRESS`, `READY`, `PICKED_UP`, `COMPLETED`, `CANCELLED`. |
| `order_number`         | string\|null | External or display order number.                                                                                 |
| `lock`                 | boolean      | Whether the receipt is locked from further changes.                                                               |
| `total`                | number       | Total amount collected.                                                                                           |
| `subtotal`             | number       | Subtotal before discounts, taxes, and fees.                                                                       |
| `discount_type`        | number       | Discount type applied (0 = none).                                                                                 |
| `discount_value`       | number       | Discount amount or percentage value.                                                                              |
| `discount_rate`        | number       | Effective discount rate.                                                                                          |
| `total_discount`       | number       | Total discount applied to the receipt.                                                                            |
| `service_charge`       | number       | Service charge percentage.                                                                                        |
| `service_charge_value` | number       | Calculated service charge amount.                                                                                 |
| `delivery_fee`         | number       | Delivery fee amount.                                                                                              |
| `remaining`            | number       | Outstanding balance (0 when fully paid).                                                                          |
| `i_tax`                | number       | Inclusive tax amount.                                                                                             |
| `e_tax`                | number       | Exclusive tax amount.                                                                                             |
| `total_tax`            | number       | Total tax amount (inclusive + exclusive).                                                                         |
| `payment_methods`      | array        | Payment breakdown. See [Payment method](/common-objects#payment-method-in-receipts).                              |
| `fiscal_id`            | string\|null | Fiscal receipt identifier for tax reporting.                                                                      |
| `loyalty_type`         | string\|null | Loyalty program type applied.                                                                                     |
| `loyalty_value`        | number\|null | Loyalty discount or points value.                                                                                 |
| `address`              | string\|null | Delivery address.                                                                                                 |
| `description`          | string\|null | Delivery or order notes.                                                                                          |
| `created_at`           | string       | Receipt creation time (YYYY-MM-DD HH:mm:ss).                                                                      |
| `updated_at`           | string       | Last update time (YYYY-MM-DD HH:mm:ss).                                                                           |
| `closed_at`            | string\|null | Receipt close time (YYYY-MM-DD HH:mm:ss).                                                                         |
| `shift_date`           | string       | Business day the receipt belongs to (YYYY-MM-DD).                                                                 |

See [Payment method](/common-objects#payment-method-in-receipts) for the `payment_methods[]` structure.

## Notes

* Use the `date[0]` and `date[1]` filters to restrict receipts to a date range (inclusive, YYYY-MM-DD).
* Sorting accepts multiple fields (`sort[0]`, `sort[1]`, etc.); directions must be `1` (ascending) or `-1` (descending).
* Pagination uses classic `page` and `limit` semantics; the default `limit` is 50.
* Combine `status`, `sale_type_id`, and date filters via the OpenAPI explorer when you need more granular reporting.
* The response also includes `time`, `timestamp`, `unix`, and `sorts` fields for diagnostics and discovering sortable fields; these are omitted from examples for brevity.