# Lot

> Base URL: `https://pos.pages.fm/api/v1`. Authenticate with the `api_key` query parameter.

## Lot list (expiry date)

`GET /shops/{SHOP_ID}/lots`

Get the list of expiry-date lots of products (products with type `LOT`). Each lot has a lot code (`custom_id`), manufacturing date and expiry date, and is linked to one or more variations of the product via `lot_variations`.

Datetime values (`expire_date`, `manufacturing_date`, ...) are in UTC.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `SHOP_ID` | path | integer | yes | Shop ID |
| `page` | query | integer |  | Page number |
| `page_size` | query | integer |  | Page size |
| `search` | query | string |  | Search by lot code, product code/display ID or variation code/display ID |
| `warehouse_ids[]` | query | string[] |  | Filter lots that have stock records in these warehouses (lots without any stock record are still returned) |
| `remain_quantity` | query | string |  | Filter by sellable quantity of the lot, JSON with fields: - `type`: `greaterOrEqual` \| `smallerOrEqual` \| `between` - `value`: quantity (for `greaterOrEqual` / `smallerOrEqual`) - `minValue`, `maxValue`: range (for `between`) - `warehouseId`: warehouse ID, `all` for all warehouses - `isFilterTotal`: `true` to compare the total across warehouses, otherwise compare each warehouse record |
| `actual_remain_quantity` | query | string |  | Filter by stock (quantity physically on hand) of the lot, same JSON format as `remain_quantity` |
| `min_retail_price` | query | integer |  | Filter lots having a linked variation with retail price greater than or equal to this value |
| `max_retail_price` | query | integer |  | Filter lots having a linked variation with retail price less than or equal to this value |
| `expiry_date` | query | string |  | Filter by expiry date, only lots that still have sellable stock (`remain_quantity > 0`) in at least one warehouse are returned: - `in_date`: not expired yet - `out_of_date`: already expired - JSON `{"start_date": <unix>, "end_date": <unix>}`: expiry date within the range (unix timestamp in seconds) |
| `range` | query | string |  | Filter by time range, JSON `{"key": ..., "since": <unix>, "until": <unix>}` (unix timestamp in seconds, `until` defaults to now). `key`: - `inserted_at`: by created time (default) - `manufacturing`: by manufacturing date - `expire`: by expiry date |
| `sort_field` | query | string |  | Sort, JSON `{"field": ..., "order": "ascend" \| "descend"}`. `field`: `mfg` (manufacturing date), `exp` (expiry date), `inserted_at` (created time), `updated_at` (updated time). Default: expiry date descending, then created time descending |

### Responses

- `200` Success (object)

```json
{
  "success": true,
  "data": [
    {
      "id": "d0e4a4b0-0c6d-4dc1-8252-447bba021b3e",
      "custom_id": "LO-XA",
      "expire_date": "2027-10-11T17:00:00",
      "manufacturing_date": "2026-10-11T17:00:00",
      "inserted_at": "2026-10-12T07:35:10.000000",
      "updated_at": "2026-10-12T07:35:10.000000",
      "product": {
        "id": "da9b9e28-af65-4456-916e-ac8f8eb00334",
        "name": "TEST6972#2",
        "type": "LOT",
        "image": null,
        "tags": [],
        "custom_id": "SP-L",
        "display_id": 13721,
        "bonus_products": [],
        "brand_id": null,
        "creator_id": "84616be7-7a6b-4f58-af37-2c64d9ee04a9",
        "inserted_at": "2026-10-12T07:29:45",
        "is_published": true,
        "is_sell_negative": null,
        "limit_quantity_to_warn": 0,
        "limit_quantity_to_warn_by_warehouse": null,
        "manipulation_warehouses": [],
        "materials": [],
        "measure_group_id": null,
        "note": null,
        "note_product": "",
        "product_attributes": [],
        "supplier_product_ids": [],
        "warning_by_variation": false,
        "categories": []
      },
      "lot_variations": [
        {
          "id": "a560ac18-8d5b-46ef-82f6-bf1474ad1c8f",
          "variation_id": "daf62728-ae6f-4354-94e4-4a12855c4293",
          "inserted_at": "2026-10-12T07:35:10.000000",
          "updated_at": "2026-10-12T07:35:10.000000"
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 30,
  "total_entries": 1,
  "total_pages": 1
}
```