Controlata API Documentation
Search for the articles here or browse the categories below.
Browse by topic
Find guides, tutorials, and answers organised by category.
Getting Started
Connecting, authorization, request format and reference data
Browse
Materials
Browse
Products
Methods for products and stock levels
Browse
Resources
Browse
Customers
Browse
Sales
Browse
Suppliers
Browse
Purchases
Browse
Production
Browse
Write-offs
Browse
Transfers
Browse
Audits
Browse
Categories
Browse
Storage Locations
Browse
Units of Measure
Browse
Popular articles
What other people are reading right now.
Retrieving a List of Products
Returns the products stocked at a storage location (including those with zero stock), sorted by name. Archived products are included too. v1/products/get_list.php Parameters Field Type Required Description storage_id int Yes Storage location ID limit int No Page size, from 1 to 1000 offset int No How many records to skip Without limit the whole list is returned. See Common Rules for pagination. Response An array products with the product's fields and its stock at storage location storage_id, without alternative SKUs and components: Field Type Description id int Product ID name string Name sku string SKU unit string Unit of measure, a code from Units of Measure price float Sale price per unit cost float Cost per unit batch_size float Batch size: the product quantity the components are given for notes string Notes status int Always 1: deleted products are not returned archived int 1 if the product is archived stock float Stock at storage location storage_id minimum float Minimum stock at storage location storage_id planned float Stock change from operations in the Planned status. null if there are none categories array The product's categories: objects with id and name suppliers array The product's suppliers: objects with id and name The total field holds the total number of products at the storage location. Example request { "storage_id": 3999, "limit": 100, "offset": 0 } Example response { "success": true, "products": [ { "id": 3120, "name": "Dining table", "sku": "P100", "price": 45000, "cost": 13604.25, "batch_size": 10, "notes": "", "status": 1, "archived": 0, "stock": 12, "minimum": 3, "planned": null, "unit": "pcs", "categories": [ { "id": 21, "name": "Furniture" } ], "suppliers": [ { "id": 52, "name": "Furniture Factory" } ] } ], "total": 1 } Errors Error Reason No storage_id in input storage_id is missing Storage ID not found Storage location not found or deleted Invalid limit value. Must be between 1 and 1000 Invalid limit Offset requires limit offset passed without limit
PurchasesRetrieving a Purchase
Returns a purchase's details and its lines. v1/purchases/get_entry.php Parameters Field Type Required Description purchase_id int Yes Purchase ID Response An object purchase 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 And two arrays of purchase lines: materials and products. Line fields: Field Type Description id int Material or product ID sku string SKU name string Name amount float Quantity unit string Unit of measure total float Line total price float Price per unit: total divided by amount cost float Line cost position int Line number in the purchase card, from 0 notes string Comment on the line. Empty string if there is none The position numbering is shared across both arrays: it restores the line order as in the purchase card. The lines from the response can be sent to v1/purchases/edit unchanged: extra fields are ignored. Example request { "purchase_id": 29645 } Example response { "success": true, "purchase": { "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", "materials": [ { "id": 2051, "sku": "M010", "name": "Oak board", "amount": 0.2, "cost": 27300, "unit": "cu m", "position": 0, "total": 26000, "price": 130000, "notes": "Check the thickness" }, { "id": 2052, "sku": "M011", "name": "Wood glue", "amount": 10, "cost": 4200, "unit": "kg", "position": 1, "total": 4000, "price": 400, "notes": "" } ], "products": [] } } Errors Error Reason No purchase_id in input purchase_id is missing Purchase not found or access denied Purchase not found or deleted
Getting StartedAPI Overview
The Controlata API lets external systems (a website, CRM, accounting system or marketplace) work with your data in Controlata: manage the catalog of materials, products and resources, create sales, purchases, productions, write-offs, transfers and audits, and read stock levels at storage locations. Connecting requires programming experience and familiarity with APIs. If you are not a developer, hand this documentation to a technical specialist or an AI assistant: every article can be copied as Markdown. Connecting 1. Open Settings โ Integrations and click Connect next to General API. 2. Copy the API key. It authorizes every request. 3. If needed, change the Sale number prefix. The default is "A-". Base URL and request format Base API URL: https://api.controlata.com/connect/ In this documentation method paths are given relative to this URL. For example, the method v1/materials/add is called at https://api.controlata.com/connect/v1/materials/add.php. The first path segment is the method version: a new version appears only if the response changes incompatibly, and the old one keeps working. - Every method is called with a POST request. - Request body: JSON in UTF-8, header Content-Type: application/json. The API is meant for requests from your server. Requests from a browser on another domain are rejected with code 401. Authorization Pass the API key in the Authorization header as is, without the word Bearer: Authorization: your_api_key Example request: curl -X POST https://api.controlata.com/connect/v1/storages/get_list.php \ -H "Authorization: your_api_key" \ -H "Content-Type: application/json" \ -d '{}' Responses and errors A successful response has code 200 and a success field equal to true. The other fields depend on the method: { "success": true, "material_id": 2051 } On error, success is false and the error field holds a description in English: { "success": false, "error": "Material not found or access denied" } HTTP code When Response body 200 Request completed JSON, success: true 400 Error in the request data: a required field is missing, an invalid value, a record is not found JSON, success: false 401 API key is missing or invalid Empty 429 Daily request limit reached JSON, success: false 500 Internal error JSON, success: false If a required field is missing, the error reads ยซNo in inputยป, for example ยซNo material_id in inputยป. The other errors are listed in each method's article. Request limit A company can send up to 10,000 requests per day. Every request with a valid key counts, including those that end in an error. The counter resets once a day, at night. When the limit is exceeded, the API responds with code 429 and the error ยซDaily connections limit reachedยป. What's next - Common Rules: partial editing, pagination, number precision. - Reference lists integrations usually start with: Categories, Storage Locations, Units of Measure. - Method sections: Materials, Products, Resources, Customers, Sales, Suppliers, Purchases, Production, Write-offs, Transfers, Audits. Controlata keeps a log of API requests. If a request does not work as expected, contact support and include the method and the time of the request.
Getting StartedCommon Rules
Rules that work the same way across all API methods. Number precision Quantities are stored with up to 3 decimal places, amounts and prices to the cent. The API rounds incoming values the same way the Controlata interface does: 0.3333 is saved as 0.333, 10.125 as 10.13. A quantity in operation lines must stay above zero after rounding: 0.0004 is rejected. Editing edit methods change only the fields you pass. Only the record ID is required, the other fields keep their current values. - Arrays (operation lines, categories, suppliers, product components) are replaced as a whole when passed. To clear an array, pass an empty array. - If at least one of the materials and products arrays is passed, the operation lines are replaced as a whole, and the array that is not passed is treated as empty. If neither is passed, the lines stay unchanged. For example, to change only a purchase's notes, pass purchase_id and notes: the lines, dates, storage locations and supplier stay as they were. Pagination get_list methods accept optional pagination parameters. Exception: small reference lists (units of measure, categories and storage locations) are always returned in full and do not accept these parameters. Field Type Description limit int Page size, from 1 to 1000 offset int How many records to skip. Passed together with limit Without limit the whole list is returned. The response has a total field with the total number of records matching the filters. Error Reason 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
ResourcesEditing a Resource
Updates a resource. Only the fields you pass are changed, the rest stay as they were. v1/resources/edit.php Parameters Field Type Required Description resource_id int Yes Resource ID name string No Name type string No Calculation type: "rate", "percent" or "amortized" dynamic int No 1: the price or percentage is specified in the product components unit string No Unit of measure. Used only for a fixed rate and depreciation price float No Price per unit base string No Calculation basis: "cost" or "price" percent float No Percentage initial_cost float No Initial cost useful_life float No Useful life, in the resource's units notes string No Notes categories array No Categories: objects with id or name. Replace the current ones as a whole Which fields each type needs is described in Creating a Resource. When changing type, pass the fields the resource does not have yet: unit for a fixed rate and depreciation, base and percent for a percentage, initial_cost and useful_life for depreciation. The resource's quantity in product components is not recalculated, so check it after the change. For a resource that has already been consumed in production, the calculation type cannot be changed, and for a depreciated resource the initial cost, useful life and unit cannot either. The other fields can be changed. Example request { "resource_id": 57, "price": 650 } Example response { "success": true } Errors Error Reason No resource_id in input resource_id is missing Resource not found or access denied Resource not found or deleted Name must not be empty An empty name was passed Name must be a string Name passed not as a string, e.g. as an array Invalid type value. Must be one of: rate, percent, amortized Invalid type No unit in input Type changed to a fixed rate or depreciation, but the resource has no unit Unit not set An empty unit of measure was passed Unit not found Unknown unit of measure Unit cannot be changed to another unit group: the resource is used in components of products Changing the unit group of a resource used in product components Invalid price value. Must be a number, 0 or greater Price is not a number or below 0 (same for initial_cost) Invalid base value. Must be one of: cost, price Invalid calculation basis, or it was not passed when changing the type to percentage Percent must be greater than 0 and not exceed 100 Percentage out of range, or not passed when changing the type to percentage Useful life must be greater than 0 Useful life is 0 or less, or not passed when changing the type to depreciation The resource is already used in production, so these fields cannot be changed: type, useful_life The resource has already been consumed in production. The fields that cannot be changed are listed at the end: type, initial_cost, useful_life, unit Category 12 not found Category not found
ProductsEditing a Product
Updates a product and its components. Only the fields you pass are changed, the rest stay as they were. v1/products/edit.php Parameters Field Type Required Description product_id int Yes Product ID name string No Name sku string No SKU unit string No Unit of measure price float No Sale price per unit batch_size float No Batch size notes string No Notes minimum float No Minimum stock at storage location storage_id storage_id int With minimum Storage location where the minimum stock is changed categories array No Categories: objects with id or name. Replace the current ones as a whole suppliers array No Suppliers: objects with id. Replace the current ones as a whole alternative_sku array No Alternative SKUs: objects with sku and label. Replace the current ones as a whole materials array No Materials in the components products array No Subassemblies in the components resources array No Resources in the components. Replace the current ones as a whole Product components The components are defined per batch (batch_size units) and passed as the arrays materials, products (subassemblies) and resources. materials and products lines Field Type Required Description id int Yes Material or product ID amount_per_batch float Yes Quantity per batch unit string Yes Line unit. From the same group as the material or product unit: for a material in "kg", "kg" or "g" fit loss_percent float No Loss, in percent. Default 0. Accepted only if showing loss in components is enabled in the company settings position int No Line position in the components If at least one of the materials and products arrays is passed, materials and subassemblies are replaced as a whole, and the array that is not passed is treated as empty. For example, if you pass only materials, the subassemblies are removed from the components. position sets the order of component lines in the Controlata interface, shared by materials and products. Lines without it go last, in the order passed. Controlata renumbers positions from 0, so in Retrieving a Product they may differ from the ones you passed. resources lines Each resource line contains the resource id. Whether amount_per_batch and unit are needed depends on the resource type (see Creating a Resource): Resource type amount_per_batch unit Fixed rate Quantity per batch, e.g. work hours Required Fixed rate, price specified in the product components A money amount per batch Not needed Percentage Not passed: taken from the resource Not needed Percentage, specified in the product components The percentage Not needed Depreciation Quantity per batch, e.g. equipment hours Required Example request A new sale price and material components. No subassemblies are passed, so they are removed from the components; resources stay the same. { "product_id": 3120, "price": 47000, "materials": [ { "id": 2051, "amount_per_batch": 0.6, "unit": "cu m", "loss_percent": 5 }, { "id": 2060, "amount_per_batch": 400, "unit": "pcs" } ] } Change only the minimum stock: { "product_id": 3120, "minimum": 3, "storage_id": 3999 } Example response { "success": true } Errors Error Reason No product_id in input product_id is missing Product not found or access denied Product not found or deleted Name must not be empty An empty name was passed Name must be a string Name passed not as a string, e.g. as an array Unit not set An empty unit of measure was passed Unit not found Unknown unit of measure Unit cannot be changed to another unit group: the product is used in components of other products Changing the unit group of a product used in other products' components Batch size must be greater than 0 Batch size is 0 or less No storage_id in input minimum passed without storage_id Storage ID not found Storage location not found or deleted Product is not stored in storage location 3999, so its minimum cannot be set there The product is not stocked at the storage location Invalid price value. Must be a number The value is not a number (same for batch_size and minimum) Category 12 not found Category not found Supplier not found or access denied Supplier not found or deleted SKU must be from 1 to 50 characters for alternative_sku 0 The alternative SKU is empty or longer than 50 characters Label must not exceed 100 characters for alternative_sku 0 The alternative SKU caption is longer than 100 characters Errors in component lines In the error text, instead of 2051 there is the item ID, and instead of 0 the line number in the array (from 0). Error Reason Materials is not an array materials was not passed as an array (same for products and resources) Line 0 of materials must be an object The line is not an object (same for products and resources) No id for material 0 The material id is missing or not a number (same for product) Material 2051 not found Material not found or deleted Product 2051 not found Product not found or deleted Product cannot be a component of itself The product was added to its own components Amount per batch must be greater than 0 for material 2051 The quantity is missing, not a number, or 0 after rounding to 3 decimals (same for product and resource) Unit not found for material 2051. Use a unit of the same group as the material unit The unit is missing, unknown or from another group (same for product) Loss percent must be from 0 to 100 for material 2051 Loss is below 0, above 100 or not a number (same for product) Loss percent is disabled in company settings for material 2051 Loss was passed, but showing loss in components is disabled in the company settings (same for product) Resource for line 0 not found Resource not found or deleted Percent must not exceed 100 for resource 2051 The percentage in the components is above 100 Unit not found for resource 2051. Use a unit of the same group as the resource unit The resource unit is missing, unknown or from another group