↑↓ selectEnter openEsc close

    1. Elbuz
    2. Legacy API v1

    What the legacy API v1 does to products, prices and documents

    11 min readUpdated

    API v1 writes data at once, without confirmation, by its own rules: which fields it overwrites over manual edits, what remains after a batch breaks off, whose price wins. Know them in advance to keep manual edits and undo a failed run.

    When you need this:

    • A manager sets prices, accounting sends its own — “Fixed Price” protects only in add with updating existing products.
    • A 10,000-product batch broke off — a retry won't duplicate products or add photos.
    • A batch created unwanted products — filter by “Source - Code”.
    • The site resends an order after a network failure — no duplicate document.

    Where to start: what overwrites manual edits.

    What to know before launch

    What overwrites manual edits

    api/scope/update for products overwrites exactly the fields present in the request and leaves the rest alone. A product is looked up only by product_id: a row with an ID that isn't in the database is skipped without an error and isn't counted in total_item_update.

    The card's “Do not update” and “Fixed Price” checkboxes do not stop updates through the API. If a manager edited the name or price by hand and checked the box, the next update with that field overwrites the value anyway. The checkboxes protect against catalog update from price lists and against markups, but not against a direct API write.

    Nested lists in a batch update work differently:

    • if a record has image_list, all product photos are deleted and replaced with the ones sent; the “Do not update photo” checkbox doesn't stop this. No image_list — the photos stay as they were;
    • if it has attribute_list, the product's attributes are erased and written from the batch. Here the checkboxes work: a product with “Do not update” or “Do not update attributes” keeps its old attributes.

    The batch skips fields marked “read only” in the field registry without an error. A field missing from the registry entirely rejects the whole batch with “Unknown field” and its name. Field names are checked in the first record of the batch.

    How to lock in your own value:

    SituationWhat to do
    A person maintains the field in Elbuz, and the integration must not touch itdon't pass this field in update. In a single update (without item_list), the value -1 also means “leave the field alone”
    You need to add data without wiping filled-in fieldsinstead of update, send api/scope/add with update_exist_product=1 — its rules are below

    Adding with update_exist_product=1 finds existing products the same way as the duplicate protection (below) and updates them by different rules than update:

    • an empty or zero value in the batch doesn't wipe a filled-in field. Exception: fields where zero means an action — quantity, status, sort_order, subtract_quantity, shipping and all flag_* fields;
    • prices (price, price_rrp, price_old, price_cost, price_special) don't change on products with “Fixed Price”;
    • products with “Do not update” are skipped entirely.

    Without update_exist_product, adding doesn't update the fields of existing products: it finds them and skips them. Only category links from category_list are added to existing products.

    Instead of the flag, you can pass field_list_update_exist_product — a list of fields to update:

    • only these fields are written, again skipping products with “Do not update” and prices of products with “Fixed Price”;
    • this mode doesn't protect price_special;
    • names that aren't product fields are skipped without an error — the rest of the list is updated.

    What happens after a batch breaks off and is retried

    The server processes a batch of 10,000 products as a sequence of separate database writes, without a transaction: first categories and manufacturers, then the products themselves, then product categories, attributes, photos, discounts. If processing breaks off midway, the database keeps whatever was written.

    Retrying the same batch doesn't duplicate products. Before writing, each row is looked up among existing products:

    • if the row has a uuid — by it;
    • if uuid is empty — by a match of three fields together: mpn, name and ext_url (case-insensitive, ignoring leading and trailing spaces).

    A found product isn't created again. But add writes photos and attributes only to new products: if the batch broke off after creating products but before photos, a retry won't add photos. A retry fills in missing attributes with update_existing_attr[product_values]=1: missing values are added, existing ones aren't touched. Send photos separately through api/scope/update with image_list.

    Pass your own stable uuid in every product. Then a retry finds the product unambiguously, even if you changed its name between attempts.

    The batch skips two kinds of rows without an error, and you can tell only because total_item_add is lower than what you sent:

    • a row without a name — discarded before writing;
    • a new product without a category — not created. The batch determines the category by category_id, by the full path in category_name_full (parts separated by /; if no part of the path exists in the database, the category chain is created, otherwise the product goes to the deepest one found by name) or by the category_list. If none works, the product isn't written. The category_create_by_source=1 parameter puts such products in a separate service category with the source code in its name; it's created disabled and excluded from export.
    What happens to one batch row. Left branch — an existing product: without update_exist_product its fields don't change. Right branch — a new product: without a name or category it isn't created and isn't counted in total_item_add
    NoYesYesYesNoNoYesNoYesNoYesNoBatch row in api/scope/addDoes the row have a name?Row is skipped without an error,not counted in total_item_addDoes the product already exist?By uuid; without uuid, by mpn,name and ext_url togetherupdate_exist_product=1or field_list_update_exist_productpassed?Fields are updated.Fields of products with “Do notupdate” stay unchangedProduct fields stay unchanged.Only categories from category_listare addedCategory found by category_idor category_name_full?Product is createdtogether with photos and attributesDoes category_list have a maincategoryfound in the database?category_create_by_source=1?Product goes to the service categoryof the source
    • Start or end
    • Action or result
    • Decision: the path depends on the answer

    Whose price stays

    Three mechanisms write a product's price in Elbuz: the API, base catalog markups and catalog update from price lists. Whoever writes last wins, with these rules:

    Who writesWhat it does with the priceWhat stops it
    api/scope/updatewrites the price as is and doesn't run markups afterwardsnothing: “Fixed Price” and “Do not update” have no effect
    api/scope/addwrites your price, then in the same request runs base catalog markups on the newly created products: if there are active markup rules and you passed price_cost above zero, the price is recalculated from the cost price“Fixed Price” or “Do not update” in the batch itself
    catalog update from price lists and markupsoverwrite the price of products matched to a price list“Fixed Price” (and “Do not update” — for markups)

    So an API price lasts only until the next catalog update or markup run, unless the product has “Fixed Price”. To keep the API price in charge, pass flag_fix_price=1 with it. The checkbox clears itself after the date in “Date to remove the “Fixed price” flag”, if set — this is checked on every catalog update.

    When added products reach the site and exports

    API operations don't export anything by themselves: neither add nor update starts a tunnel or a file export. A product moves on with the next run of whatever export you have set up — manual or scheduled.

    Within the add request itself, everything the catalog needs is already done: markups, service data for sorting and the summary (flat) product table. If the account has several active stores, new products are added to the store from the store_id parameter, or to store number 1 without it.

    The tricky part is the “Only export new data” tunnel mode. In it, the tunnel takes only products with the “Exported” flag cleared.

    • If a product was created through add, the flag is cleared, and the product goes out in the next run.
    • If products were changed by a batch update (with item_list), the flag is cleared too, and the change goes out in the next run.
    • If one product was changed without item_list, the flag is cleared when the request has at least one field of the product itself (price, stock, etc.). A request with only text fields — name, descriptions, meta tags — doesn't clear the flag, and in this mode the change won't reach the site. To send it, pass flag_exported=0 in the same request.

    Deleting through api/scope/delete also removes the product from the site if the tunnel settings allow deleting products on the site: immediately when “Delete data immediately on the site” is also on, otherwise on the next tunnel run. Without that permission, the product stays on the site.

    How to find out what was deleted

    Incremental sync by date_modified doesn't detect deletions. A deleted product is erased from the database completely — with its descriptions, photos, attributes and category links, and the get directories have no deletion log. Deleting a main product also deletes its option products.

    To catch deletions, regularly fetch the full list of IDs (limit_field=product_id, max_rows=500, paging through page_next) and compare it with yours: whatever isn't in Elbuz no longer exists.

    The same rule works the other way: Elbuz doesn't delete anything for you. add and update don't touch a product that has disappeared from your system — it stays in Elbuz with the last data written. You can remove it only with an explicit api/scope/delete with its product_id.

    How to roll back a bad batch

    If an add batch created unwanted or broken products, find them by the source mark. Products created by the batch have your source_code in “Source - Code” (or jumper if you didn't pass one).

    • Through the API: api/scope/get with the filter filterdatafield0=source_code, filtercondition0=EQUAL, filtervalue0=my_erp returns a list of IDs. To narrow it to this particular run, add a second condition on date_added.
    • In the app: in the base catalog product table, filter the “Source - Code” column, select the products found and delete them — the app asks “Delete the selected products?” with the count.

    api/scope/delete deletes one product per request, so rolling back a thousand products through the API takes a thousand requests within the rate limit. The product table deletes all selected products in one action.

    A batch update overwrites “Source - Code” with api. Products that were also updated by a batch after the bad add can no longer be found by your source_code — look for them by date_added or your uuid.

    A bad update is harder: an update request doesn't save previous values anywhere, so you can't roll it back with the API. You'll have to restore data with another update carrying the correct data from your system.

    Documents: status, stock and duplicates

    A document created through api/scope/add with scope=document:

    • requires type_id — without it the response is “Document type not specified”, with a nonexistent one — “Document type not found”;
    • gets the status “New” if status_id isn't passed;
    • gets a number automatically, from its type's numbering;
    • isn't posted unless you pass is_sign=1. Without this parameter, the document doesn't change stock or reservations: reservations count only for posted orders, and posting moves stock. With is_sign=1, the document is posted right away in the same request — just like the post button in the app, with stock movements — and the response gets an is_sign field.

    Document items go in item_list. Elbuz determines the product of each item like this:

    • product_id is present — the item is linked to that product. If there is no product with that product_id in the database, the item isn't written and gets the status Error with “Item not found” in the response; the rest of the document is created.
    • no product_id, but name is present — Elbuz looks for the product itself: first by the ean barcode, then by the sku, then by the exact name. The name is compared ignoring case, extra spaces and quotes, and counts only if exactly one product in the database has that name.
    • the product isn't found by any method — Elbuz creates a new one with the item's name, SKU, barcode and price in the service category “Products - api - api”. The category is created disabled and excluded from export.
    • neither product_id nor name — the item isn't written, status Error, “Item not found”.

    A customer order (type_id=3) with one item by product_id and one with only a name, SKU and barcode (the elbuz_call function comes from the first request in the reference):

    $res = elbuz_call($host, 'api/scope/add', array(
        'api_token' => $token,
        'scope'     => 'document',
        'type_id'   => 3,
        'item_list' => array(
            array('product_id' => 2, 'quantity' => 1, 'price' => 1890),
            array('name' => 'HDMI 2.1 cable, 2 m', 'sku' => 'HDMI-21-2M', 'ean' => '4820000000017', 'quantity' => 3, 'price' => 250),
        ),
    ));

    To avoid piling up products, pass product_id in the item, and if you don't have it — at least the ean or sku, identical to the product card in Elbuz. Name lookup works only on an exact, unique match: a different name in the order or two products with the same name — and a new card appears.

    New cards collect in the “Products - api - api” category: check it to spot items Elbuz didn't recognize.

    The check_unique_field_name parameter protects against duplicates on retry — the name of a document field that is unique in your system (for example, where your order number is stored).

    • If a document with that value already exists, a new one isn't created, and the response returns “Document already exists” with the document_id of the existing one.
    • To check by a pair of fields, there is also check_unique_field_name_2.
    • The name must be the exact name of a document field. If no field matches the name in check_unique_field_name, the check is skipped and the document is created; a nonexistent name in check_unique_field_name_2 only drops the second condition.
    • If the field value isn't passed in the request itself, it counts as empty.

    Scenarios

    Accounting sends prices, and a manager maintains some products by hand

    Task: prices and stock come from accounting, but on some products the manager sets their own price, and the sync must not wipe it.

    What to turn on: “Fixed Price” on the manager's products, and “Do not update” where nothing may be touched. The integration sends api/scope/add with item_list, update_exist_product=1 and the same uuid it created the product with.

    What you get: existing products are found by uuid and updated. Prices of products with “Fixed Price” stay as the manager set them, products with “Do not update” keep their fields and attributes, and an empty field in the batch doesn't wipe a filled-in one (except quantity, status and other fields where zero means an action — list above).

    What won't happen: there is no protection if you send the same change through api/scope/update — there “Fixed Price” and “Do not update” don't protect product fields, and the price gets overwritten.

    Site orders without duplicates on retry

    Task: the site sends orders to Elbuz and repeats the request after a network failure — a second identical order must not appear.

    What to turn on: api/scope/add with scope=document and type_id; the site's order number in a document field, and that field's name in check_unique_field_name.

    What you get: the document gets the status “New” and a number from its type's numbering. A retry with the same number returns “Document already exists” with the document_id of the first one; no second document is created.

    What won't happen: stock and reservations won't change unless you pass is_sign=1 — without it, the document stays unposted, and you post it in the app.

    An initial catalog load you can undo

    Task: load the catalog from accounting so you can retry after a break-off and find and delete a failed run.

    What to turn on: api/scope/add with item_list, source_code=my_erp, and for each product its own uuid and a path in category_name_full.

    What you get: created products have my_erp in “Source - Code”. A product goes to the deepest path category found by name; if no part of the path exists, the chain is created. A retry after a break-off finds created products by uuid without duplicating them. Find a failed run by filtering “Source - Code” — how to do it.

    What won't happen: a retry won't add photos to products created before the break-off, and after api/scope/update the source mark changes to api.

    What to do when the result is wrong

    What you seeWhyWhat to do
    total_item_add is lower than the number of rows sentthe batch skips rows without a name and new products without a category, without an errorgive every row a name and a category (which rows are skipped)
    A price sent through the API changed a day latercatalog update from price lists or markups overwrote itpass flag_fix_price=1 with the price (whose price stays)
    A manager's manual price was wipedapi/scope/update ignores “Fixed Price”send add with update_exist_product=1 or don't pass the price (details)
    Integration products aren't found by their source_codea batch update overwrote “Source - Code” with apisearch by date_added or uuid
    After a batch retry, products have no photosphotos are written only to newly created productssend photos through api/scope/update with image_list

    FAQ

    Can I undo a bad update?

    No: the request doesn't save previous values. Restore the data with another update carrying the correct values from your system (rollback).

    A product disappeared from my system — why is it still in Elbuz?

    Elbuz doesn't delete anything for you: add and update don't touch such a product. Delete it with an explicit api/scope/delete with its product_id (details).

    Why didn't a site order reduce stock?

    A document from the API is posted only with is_sign=1. Without it, the document stays unposted, and stock and reservations don't change (documents).

    Can existing products be found without my own uuid?

    Yes: without a uuid, a product is matched by mpn, name and ext_url together. But once the name changes, the match is lost, and a retry creates a new product (batch retry).

    I added a product through the API — why isn't it on the site?

    The API doesn't export anything by itself: the product goes out with the next tunnel or export run. In “Only export new data” mode, a change to text fields only won't go out without flag_exported=0 (details).

    Where this is and who has access

    There is no separate window: the rules apply to every write through API v1, and you see the results in the app.

    Key
    a v1 key without “Read only” (key fields)
    Where you see the result
    the base catalog product table, the “Source - Code” column
    Log
    work log, operations of type “api”

    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