Retrieving a List of Purchases | Controlata API Documentation

Returns the company's purchases, from newest to oldest by purchase order date. Purchase lines are not included in the list; they are returned by v1/purchases/get_entry.

v1/purchases/get_list.php

Parameters

Field	Type	Required	Description
date_from	string	No	Purchases from this order date inclusive
date_to	string	No	Purchases up to this order date inclusive
supplier_id	int	No	Only this supplier's purchases
limit	int	No	Page size, from 1 to 1000
offset	int	No	How many records to skip

The date filters work on date_placed. Without parameters, all the company's purchases are returned. See Common Rules for pagination.

Response

An array purchases with the purchase's fields:

Field	Type	Description
id	int	Purchase ID
status	int	Status, a code from Changing the Purchase Status
payment	int	Payment status, a code from Changing the Payment Status
date_placed	string	Purchase order date
date_received	string	Received date. Empty string if not set
supplier_id	int	Supplier ID
supplier_name	string	Supplier name
materials_storage_id	int	Materials storage location
materials_storage_name	string	Materials storage location name
products_storage_id	int	Products storage location
products_storage_name	string	Products storage location name
subtotal	float	Sum of the lines
delivery_price	float	Delivery cost
discount	float	Discount
total	float	Total: subtotal plus delivery_price minus discount
amount	float	Total quantity if all lines share one unit, otherwise null
lines	int	Number of lines
notes	string	Notes

The total field in the response root holds the total number of purchases matching the filters.

Example request

{
    "date_from": "2026-10-01",
    "supplier_id": 45,
    "limit": 100,
    "offset": 0
}

Example response

{
    "success": true,
    "purchases": [
        {
            "id": 29645,
            "status": 1,
            "payment": 0,
            "date_placed": "2026-10-06",
            "date_received": "",
            "supplier_id": 45,
            "supplier_name": "Woodtrade Ltd",
            "materials_storage_id": 3998,
            "materials_storage_name": "Main location",
            "products_storage_id": 3998,
            "products_storage_name": "Main location",
            "subtotal": 30000,
            "delivery_price": 1500,
            "discount": 0,
            "total": 31500,
            "amount": null,
            "lines": 2,
            "notes": "Invoice No. 118"
        }
    ],
    "total": 1
}

Errors

Error	Reason
Date is not a valid date in format YYYY-MM-DD	Invalid date_from or date_to
Invalid limit value. Must be between 1 and 1000	Invalid limit
Invalid offset value. Must be 0 or greater	Invalid offset
Offset requires limit	offset passed without limit