↑↓ selectEnter openEsc close

    1. Elbuz
    2. Legacy API v1

    Legacy API v1 reference: requests, operations and errors

    12 min readUpdated

    Through API v1, Elbuz sends and accepts products, categories, contacts and documents via POST requests with a token. Every operation here comes with a working PHP example and a real server response.

    When you need this:

    • You maintain an integration written for v1 — the full list of operations and scopes.
    • A request returns code 200 but no data — read the error from the response structure.
    • You get exactly 100 records — pages of up to 500 records and paging to the end.
    • You only want what changed — a ready-made incremental sync recipe.

    Where to start: a minimal script — sign in, send a request, print the result.

    What API v1 can do

    Write any new integration on API v2 right away: v1 is marked as deprecated (how to migrate).

    How to make your first request

    A minimal working script: sign in, request data, print the result. Fill in your address, user name and key.

    <?php
    $host = 'https://your-account.elbuz.com';  // your account address
    $user = 'site';                           // “User” from the key card
    $key  = 'YOUR_KEY';                       // “Access Key”
    
    function elbuz_call($host, $route, array $post) {
        $ch = curl_init($host . '/admin/index.php?route=' . $route);
        curl_setopt_array($ch, array(
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => http_build_query($post),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 120,
        ));
        $body = curl_exec($ch);
        return json_decode($body, true);
    }
    
    // 1. sign in — get a token
    $login = elbuz_call($host, 'api/login', array('username' => $user, 'key' => $key));
    if (empty($login['api_token'])) {
        exit('Sign-in failed: ' . json_encode($login, JSON_UNESCAPED_UNICODE));
    }
    $token = $login['api_token'];
    
    // 2. request data
    $res = elbuz_call($host, 'api/scope/get', array(
        'api_token'   => $token,
        'scope'       => 'category',
        'max_rows'    => 2,
        'limit_field' => 'name',
    ));
    
    print_r($res);

    Response to the sign-in:

    {
        "success": "API session started!",
        "api_token": "b439dd5c3b386d36464bef450d"
    }

    Response to the category request — exactly what the server returned:

    {
        "item_list": {
            "83": {
                "category_id": "83",
                "parent_id": "11",
                "name": "Варочные поверхности"
            },
            "84": {
                "category_id": "84",
                "parent_id": "11",
                "name": "Встраиваемые вытяжки"
            }
        },
        "meta": {
            "item_scope": "category",
            "total_row": 234,
            "page_total": 117,
            "page_next": 2,
            "page_current": 1,
            "request_time": "00:00:00"
        }
    }

    Note: the request had limit_field=name, yet the response also contains category_id and parent_id. That's expected — a scope's required fields are always added.

    How the protocol works: token, rate, language

    WhatHow
    Base addressaccount address + /admin/index.php?route= + route
    MethodPOST only
    Request bodya regular form, application/x-www-form-urlencoded
    Response with the Content-Type: application/json header
    HTTP codealways 200 — even on error
    Tokenthe api_token parameter in the POST body or in the URL

    Don't rely on the HTTP code: an error also comes with code 200. Parse the structure: an error is a JSON array of strings, a successful response is an object with item_list or meta.

    Token lifetime

    The token is a session ID. Sessions not used for more than an hour are deleted; every request with the token extends the session. So an always-on integration signs in once and calls api/login again only in response to an access error.

    function elbuz_get($host, $user, $key, &$token, array $post) {
        $post['api_token'] = $token;
        $res = elbuz_call($host, 'api/scope/get', $post);
    
        // an error comes as an array of strings — the session may have expired
        if (isset($res[0]) && is_string($res[0])) {
            $login = elbuz_call($host, 'api/login', array('username' => $user, 'key' => $key));
            if (empty($login['api_token'])) return $res;   // not a session problem
            $token = $login['api_token'];
            $post['api_token'] = $token;
            $res = elbuz_call($host, 'api/scope/get', $post);
        }
        return $res;
    }

    Rate limit

    A key has a request limit — 30 per minute by default. It works as a minimum interval: 60 divided by that number, so by default no more than once every two seconds. You can't save up idle time and fire a burst of requests: every request that arrives before the interval is up is rejected.

    {"Error": "Rate limit exceeded! Time passed:0.0582 Time minimal request:0.1"}

    The response shows both numbers: time since the previous request and the time required. The format differs from other errors — the key is Error with a capital letter, and it's an object instead of an array. Handle both:

    if (isset($res['Error'])) {                    // rate limit
        sleep(2);
        // repeat the same request
    }
    if (isset($res[0]) && is_string($res[0])) {    // regular API error
        throw new RuntimeException($res[0]);
    }

    You can't change the limit in the interface — contact technical support.

    The checks every request with a token goes through, in order. The rate limit is checked before the IP address, and “Read only” only on operations that change data
    NoYesNoYesNoYesNoYesYesNoRequest with api_tokenSession alive, key is “Active”and access end date not passed?“You do not have permission toaccess the API”Minimum interval sincethe previous request passed?Rate limit exceededIP address is in the key's listor the list is empty?Is it add, update or delete?Request is executedIs the key set to“Read only”?“You do not have permission tomodify data”
    • Start or end
    • Action or result
    • Decision: the path depends on the answer

    Response language

    Texts come in the language of the employee the key works on behalf of — the account owner. But an access error without a token comes in the database's default language, because the employee isn't known yet. So two messages from the same API can be in different languages. One more reason to parse responses by structure, not by text.

    Which operations and scopes exist

    RoutePurposeRequired parameters
    api/loginget a tokenusername, key
    api/scope/describedescribe a scope's fieldsapi_token, scope
    api/scope/getget recordsapi_token, scope
    api/scope/addadd a record or a batchapi_token, scope + record fields
    api/scope/updateupdateapi_token, scope, ID
    api/scope/deletedeleteapi_token, scope, ID
    api/scope/searchsearch products with the search indexapi_token, scope=product

    Set the scope with the scope parameter or append it to the route — both work the same:

    api/scope/get          + scope=currency
    api/scope/get/currency

    Scopes by operation

    The sets differ. Check this first before designing an integration: you can read almost everything, but change far from everything.

    OperationScope codes
    getcategory, product, product_price, attribute, attribute_block, language, article, manufacturer, stock_status, warehouse, store, company, contractor, contractor_group, currency, document, document_type, document_status, document_payment_status, document_delivery_status, print_template
    addcategory, product, product_price, manufacturer, contractor, document, document_extended, user, company, attribute, attribute_block, article, contractor_price, mail_send
    updatecategory, product, currency, contractor, document
    deletecategory, product, contractor, attribute_block, attribute, manufacturer, article, document
    describeproduct, product_price, manufacturer, contractor, document, user, company
    searchproduct

    product_price is available for adding but not for updating: price list rows can be created through the API, but changed only by importing a price list. Plan your integration with this in mind.

    How to find field names: describe

    Field names in requests are not the labels you see in the interface. describe returns the field registry: internal name, human-readable label and type.

    $res = elbuz_call($host, 'api/scope/describe', array(
        'api_token'   => $token,
        'scope'       => 'contractor',
        'limit_field' => 'datafield,datafield_type,grid_field_name',
    ));
    {
        "item_list": {
            "347": {"row_id": "347", "datafield": "name",         "datafield_type": "string", "grid_field_name": "Назва"},
            "349": {"row_id": "349", "datafield": "phones",       "datafield_type": "string", "grid_field_name": "Телефон"},
            "560": {"row_id": "560", "datafield": "status_name",  "datafield_type": "string", "grid_field_name": "Статус"},
            "562": {"row_id": "562", "datafield": "manager_name", "datafield_type": "string", "grid_field_name": "Відповідальний менеджер"}
        },
        "meta": {"item_scope": "contractor", "total_row": 118, "page_total": 1, "page_next": 0, "page_current": 1, "request_time": "00:00:00"}
    }

    It's the same registry you see in the “Set up grid” window with the “Tech names” switch. Without limit_field, each field comes with some thirty internal properties — take just the three columns you need.

    How to read records: get

    Parameters

    ParameterDefaultWhat it does
    scope—scope code, required
    page1page number
    max_rows100records per page. Cap of 500; anything above is simply cut off
    language_idaccount languagelanguage of text fields
    limit_fieldall fieldscomma-separated list of the fields you need
    extend—nested data: photos, attributes, document lines
    filterscount and others—filter conditions

    Required fields

    These fields always come, even if you didn't ask for them — without them you can't match the response to your data:

    ScopeAlways added
    productproduct_id, name, price
    product_pricesupply_product_id, contractor_id, price_id, product_id, sku_manufacturer, manufacturer, name, price, stock_status_id, field_ssd_stock_status_name
    categorycategory_id, parent_id, name
    documentdocument_id, contractor_id, type_id, document_type_name, document_number
    attributeattribute_id, attribute_name
    languagelanguage_id, code, name
    print_templatenothing is added
    all otherstheir own ID and name

    Pages

    Records come as an object, not an array: the key is the record ID. The meta block holds everything you need for paging; the end is reached when page_next equals zero.

    $page = 1;
    $all  = array();
    
    do {
        $res = elbuz_call($host, 'api/scope/get', array(
            'api_token'   => $token,
            'scope'       => 'product',
            'max_rows'    => 500,          // cap for the cloud
            'limit_field' => 'product_id,name,price,quantity',
            'page'        => $page,
        ));
    
        if (!isset($res['item_list'])) break;        // error or empty result
    
        $all += $res['item_list'];                   // keys = IDs, no duplicates
        $page = (int)$res['meta']['page_next'];
    
        sleep(2);                                     // default rate limit
    } while ($page > 0);
    
    echo 'received: ' . count($all);

    On the currency scope with thirteen records at five per page, this loop makes exactly three requests: the third page returns page_next: 0, and paging stops.

    An empty result is not an empty item_list but the “Item not found!” error. If the filter matched nothing, the isset($res['item_list']) check breaks the loop — that's why it comes before parsing.

    How to filter records and get photos and attributes

    Filters

    For product and document, filtering works the same as in interface grids: filterscount is the number of conditions, then four numbered parameters per condition, starting from zero.

    ParameterValue
    filterdatafield0field, as in describe
    filtervalue0value
    filtercondition0EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL
    filteroperator00 — join with the next condition using “and”, 1 — using “or”

    Products changed after a given date:

    $res = elbuz_call($host, 'api/scope/get', array(
        'api_token'        => $token,
        'scope'            => 'product',
        'max_rows'         => 2,
        'limit_field'      => 'product_id,name,quantity,date_modified',
        'filterscount'     => 1,
        'filterdatafield0' => 'date_modified',
        'filtervalue0'     => '2026-01-01',
        'filtercondition0' => 'GREATER_THAN_OR_EQUAL',
        'filteroperator0'  => 0,
    ));
    {
        "item_list": {
            "6068": {
                "product_id": "6068",
                "price": "1200.00000000",
                "quantity": "0",
                "date_modified": "2026-09-12 14:54:23",
                "name": "Ardesto LESH-Y305"
            }
        },
        "meta": {
            "item_scope": "product",
            "total_row": 126999,
            "page_total": 63500,
            "page_next": 2,
            "page_current": 1,
            "request_time": "00:00:00"
        }
    }

    You can also filter by attributes: the field name is attribute_ plus the attribute number, which describe gives you.

    Nested data

    Photos, attributes and document lines aren't part of the record itself — request them with the comma-separated extend parameter.

    Scopeextend valuesResponse field
    productattribute, image, file, video, categoryextend_attribute, extend_image, extend_file, extend_video, extend_category
    product_priceattribute, imagethe same
    documentcontractor, productextend_contractor, extend_product
    $res = elbuz_call($host, 'api/scope/get', array(
        'api_token'   => $token,
        'scope'       => 'product',
        'max_rows'    => 1,
        'limit_field' => 'product_id,name',
        'extend'      => 'image,category',
    ));
    {
        "item_list": {
            "6068": {
                "product_id": "6068",
                "price": "1200.00000000",
                "name": "Ardesto LESH-Y305",
                "extend_image": [
                    {
                        "product_image_id": "201587",
                        "image": "100/68/product_image_6068_201587.jpg",
                        "sort_order": "1",
                        "image_original": "https://…/product_image_6068_201587.jpg",
                        "image_cloud_url": ""
                    }
                ],
                "extend_category": [ {"category_id": "1201"} ]
            }
        }
    }

    You can also choose the fields of a nested block: extend_limit_field_attribute, extend_limit_field_image, extend_limit_field_product and similar. By default, attributes return attribute_id, attribute_name, attribute_value, and document lines return product_id, sku, mpn, name, quantity, price, price_sum, ean, isbn.

    With extend, the response shape changes: item_list is no longer an object keyed by ID but a plain list. Code written without extend breaks the moment someone adds it. Handle both shapes from the start:

    $rows = $res['item_list'];
    $rows = isset($rows[0]) ? $rows : array_values($rows);   // same for both shapes
    foreach ($rows as $row) { /* … */ }

    How to add, update and delete: add, update, delete

    All three return the same short response:

    {"meta": {"item_scope": "product", "result": 1024, "request_time": "00:00:00"}}

    result holds what the operation returned: the new record's ID for adding, a success flag for the others. There's no separate field with a validation error text: if the record wasn't created, result is empty.

    Batch product operations return an object in result. After adding: status, total_item_add (products created) and item_list_add (the created products, each with product_id and uuid). After updating: total_item_update. If the whole batch is rejected, status is 0 and status_text gives the reason, e.g. “Unknown field” with the field name or “Too many products” with the limit.

    Compare total_item_add with the number of rows you sent: a batch skips some rows without an error — see the section on breaks and retries.

    Batch operations

    Instead of the fields of one record, pass item_list — a list of records:

    $res = elbuz_call($host, 'api/scope/add', array(
        'api_token' => $token,
        'scope'     => 'product',
        'item_list' => array(
            array('name' => 'Product 1', 'price' => 100, 'sku' => 'A-001'),
            array('name' => 'Product 2', 'price' => 200, 'sku' => 'A-002'),
        ),
    ));
    ScopeOperationRecords per request
    productadd and updateup to 10,000
    product_priceaddup to 100

    A batch is more than a convenience. With a limit of one request every two seconds, ten thousand products one by one take almost six hours; as a batch, it's one request.

    Source tag

    The source_code parameter in add marks where the data came from; the tag is written to the product's “Source - Code” field, so you can later see that this integration created the product, not a person. Without the parameter, jumper is set.

    Batch update api/scope/update doesn't take your tag from the request: it writes api to “Source - Code” for every updated product. So your tag lasts only until the product is updated in a batch — keep this in mind if you plan to find the integration's products by it (rolling back a bad batch).

    Deleting

    Pass the ID in the field named after the scope: category_id, product_id, manufacturer_id, attribute_id, attribute_block_id, article_id, document_id.

    Pass only the field that matches the scope. If the required ID is missing, the request doesn't fail — processing moves on down the list of scopes and may reach document deletion if the request body contains document_id. The response still names the scope you asked for. Don't build a universal request body with IDs from different scopes.

    Posted documents can't be deleted — such an attempt returns an empty result.

    Which errors the API returns

    api/scope/* errors come as an array with one string:

    ["Warning: You do not have permission to modify data!"]
    MessageCauseWhat to do
    You do not have permission to access the APIno token was passed, the session expired or the key is disabledrepeat api/login; if that doesn't help, check “Active”
    You do not have permission to modify datathe key has “Read only” setclear the checkbox in the key card
    Scope code is not setno scope parameteradd scope or append it to the route
    Unknown scope codethe scope isn't supported by this operationcheck against the scope table
    Item not foundthe result is emptycheck the filter; this isn't a failure
    {"error":{"key":"Warning: Incorrect API Key!"}}sign-in failed authorization: the “User” + “Access Key” pair doesn't match the card, or “Active” is cleared in the card, or the “Access end date” has passed. The same response for all three causescheck username and key against the key card, check “Active” and the date; an empty username gives “Warning: Incorrect username!”
    {"error":{"ip":"Warning: Your IP … is not allowed to access this API!"}}sign-in: the key is correct, but the address isn't in the “Allowed IP addresses” listthe address is named in the error text — add it to the key
    {"Error":"Rate limit exceeded…"}requests come more often than the allowed intervalpause and retry

    Successful requests are written to the work log as an “api” operation with the response body — the easiest way to see what the integration did. Error responses (no permission, unknown scope, “Item not found!” etc.) and an add that added nothing aren't logged — look for such failures in the responses your integration received.

    Ready-made recipes

    Incremental catalog sync

    Instead of downloading the whole catalog every night, fetch what changed since last time.

    $since = file_exists('last_sync.txt') ? trim(file_get_contents('last_sync.txt')) : '2000-01-01';
    $started = date('Y-m-d H:i:s');
    $page = 1;
    
    do {
        $res = elbuz_call($host, 'api/scope/get', array(
            'api_token'        => $token,
            'scope'            => 'product',
            'max_rows'         => 500,
            'limit_field'      => 'product_id,name,price,quantity,sku',
            'page'             => $page,
            'filterscount'     => 1,
            'filterdatafield0' => 'date_modified',
            'filtervalue0'     => $since,
            'filtercondition0' => 'GREATER_THAN_OR_EQUAL',
            'filteroperator0'  => 0,
        ));
    
        if (!isset($res['item_list'])) break;   // “Item not found!” = no changes
    
        foreach ($res['item_list'] as $id => $row) {
            // your logic: update the product in your system
        }
    
        $page = (int)$res['meta']['page_next'];
        sleep(2);
    } while ($page > 0);
    
    file_put_contents('last_sync.txt', $started);   // START time, not finish time

    Save the start time of the run: anything changed during paging then gets into the next run instead of falling between them.

    This loop never sees deleted products — how to detect them is covered in the section on deleted and missing data.

    Batch product import

    $products = array( /* your product array */ );
    
    foreach (array_chunk($products, 1000) as $chunk) {
        do {
            $res = elbuz_call($host, 'api/scope/add', array(
                'api_token'   => $token,
                'scope'       => 'product',
                'source_code' => 'my_erp',    // source tag in the “Source - Code” field
                'item_list'   => $chunk,       // each product has your uuid, see below
            ));
            sleep(2);
        } while (isset($res['Error']));      // rate limit — retry the same chunk
    }

    The retry here loops around the same chunk. A plain continue would move on to the next chunk, and the rejected thousand products would never reach Elbuz.

    A thousand records per chunk is a trade-off: the limit is 10,000, but the bigger the chunk, the longer the response and the more painful the retry if the request breaks off.

    Send stock and prices to a website

    The most common task — and the cheapest: you need three fields, so the response is small and there are few pages.

    $res = elbuz_call($host, 'api/scope/get', array(
        'api_token'   => $token,
        'scope'       => 'product',
        'max_rows'    => 500,
        'limit_field' => 'sku,price,quantity',   // product_id and name are added automatically
    ));

    What to do when a request doesn't work

    What you seeWhyWhat to do
    It worked, then stopped an hour laterthe token session expired with no requestssign in again on an access error
    “Rate limit exceeded” on every other requestrequests come more often than the intervalpause between requests or use batch operations
    You get exactly 100 recordsdefault page sizemax_rows up to 500 and paging by page_next
    Paging loops foreverpage_next isn't checkedzero means the end
    Extra fields in the responsea scope's required fields are always addedthat's expected
    Parsing broke after adding extenditem_list became a list instead of an objecthandle both shapes
    An empty result comes as an errorthat's how get responds when nothing is foundcheck whether item_list is present
    Updating price list rows doesn't workproduct_price isn't in the update listupdate the price list by importing a file

    FAQ

    Do I need to sign in before every request?

    No. A session lives while it's used and is deleted after an hour without requests. Sign in again in response to an access error (token lifetime).

    How many requests per minute are allowed?

    Thirty by default, counted as a minimum interval: no more than once every two seconds. You can't send a burst in a row, even after a long pause (rate limit).

    How do I sync the catalog without downloading all of it?

    Filter by date_modified with the date of the previous sync. Save the start time of the run, not the finish time (recipe).

    How do I upload many products at once?

    Use the item_list parameter in the add operation: up to ten thousand catalog products per request, up to a hundred price list rows (batch operations).

    Can I rely on the HTTP response code?

    No, it's always 200 — for both success and error. An error comes as an array of strings; a success contains item_list or meta.

    Where it is and who has access

    There is no window for the : requests go to your account's address, and the key is issued in the “API & access tokens” window.

    Address
    account address + /admin/index.php?route= + route
    Key
    v1 key card: the “User” and “Access Key” fields (key fields)
    Prepare
    a key created before 14.10.2026: a new key works only with API v2

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free