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
- Updates over manual edits — which fields
updateoverwrites and how to add data without wiping filled-in fields. - A batch breaks off and is retried — a retry doesn't duplicate products; which rows a batch skips silently.
- Whose price stays — , markups or catalog update from price lists.
- When a product reaches the site — the API doesn't export anything by itself.
- Deleted products and rolling back a bad batch — how to find and remove the extras.
- Documents — status, posting and protection against duplicate orders.
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. Noimage_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:
| Situation | What to do |
|---|---|
| A person maintains the field in Elbuz, and the integration must not touch it | don'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 fields | instead 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,shippingand allflag_*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
uuidis empty — by a match of three fields together:mpn, name andext_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 incategory_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 thecategory_list. If none works, the product isn't written. Thecategory_create_by_source=1parameter puts such products in a separate service category with the source code in its name; it's created disabled and excluded from export.
- 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 writes | What it does with the price | What stops it |
|---|---|---|
api/scope/update | writes the price as is and doesn't run markups afterwards | nothing: “Fixed Price” and “Do not update” have no effect |
api/scope/add | writes 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 markups | overwrite 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(withitem_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, passflag_exported=0in 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/getwith the filterfilterdatafield0=source_code,filtercondition0=EQUAL,filtervalue0=my_erpreturns a list of IDs. To narrow it to this particular run, add a second condition ondate_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_idisn'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. Withis_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 anis_signfield.
Document items go in item_list. Elbuz determines the product of each item like this:
product_idis present — the item is linked to that product. If there is no product with thatproduct_idin the database, the item isn't written and gets the statusErrorwith “Item not found” in the response; the rest of the document is created.- no
product_id, butnameis present — Elbuz looks for the product itself: first by theeanbarcode, then by thesku, 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_idnorname— the item isn't written, statusError, “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_idof 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 incheck_unique_field_name_2only 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 see | Why | What to do |
|---|---|---|
total_item_add is lower than the number of rows sent | the batch skips rows without a name and new products without a category, without an error | give every row a name and a category (which rows are skipped) |
| A price sent through the API changed a day later | catalog update from price lists or markups overwrote it | pass flag_fix_price=1 with the price (whose price stays) |
| A manager's manual price was wiped | api/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_code | a batch update overwrote “Source - Code” with api | search by date_added or uuid |
| After a batch retry, products have no photos | photos are written only to newly created products | send 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
- For the big picture and moving to API v2 — legacy API v1: key and migration.
- To look up a request parameter or troubleshoot an error — legacy API v1 reference.
- If markups overwrite the API price — base catalog markups.
- If you're writing a new integration and want no duplicates on retry — Idempotency-Key in API v2.
