Bidirectional Return Integration Between 1C and Bitrix

Full‑Cycle Return Integration Between 1C and Bitrix

We develop and integrate return processing systems that automate the exchange between Bitrix and 1C. When a customer initiates a return on the site, the back‑office must create several linked documents: a reversal of the sale, a discrepancy report, and an adjusting invoice. If Bitrix and 1C work independently—all this is done manually, and the probability of stock and settlement discrepancies grows every week, impacting profitability.

We implement return integration as a separate circuit within the 1C–Bitrix exchange, because the standard sale module exchanges orders, not corrective documents. Those must be described separately and explicitly. With over 10 years of experience, we have delivered hundreds of such integrations for stores of various sizes.

How a Return Works in Bitrix

A return in Bitrix is an object of the class \Bitrix\Sale\Payment\PaymentReturn in the context of a payment or \Bitrix\Sale\Shipment\ShipmentReturn in the context of a shipment. From the database perspective, records are stored in:

• b_sale_order_return — return request
• b_sale_order_return_item — return items
• b_sale_order_return_shipment — relation to shipment

Return statuses (RETURN_STATUS): NEW, PROCESSED, COMPLETED, REJECTED. The trigger for transfer to 1C should be the transition to COMPLETED—data may change before that.

Exchange Schema

The standard bitrix.1c module transfers orders via sale.order in CommerceML 2. Returns are not described in CommerceML—this is a custom node that must be added to the schema yourself.

Bitrix: return becomes COMPLETED → OnSaleReturnComplete event handler → Build XML node <Возврат> → Write to exchange queue (b_agent / custom table) → Next exchange session with 1C → 1C creates document "Return of goods from buyer" → Confirmation from 1C → return status updated 

Use the OnSaleReturnComplete event from the sale module:

\Bitrix\Main\EventManager::getInstance()->addEventHandler( 'sale', 'OnSaleReturnComplete', function (\Bitrix\Main\Event $event) { $return = $event->getParameter('ENTITY'); ReturnExchangeQueue::push($return->getId()); } ); 

XML Structure for Transfer to 1C

1C works with CommerceML, but it is more convenient to transmit returns as a separate node inside <КоммерческаяИнформация>:

<Возврат> <Ид>RETURN-{return_id}</Ид> <НомерДокумента>R-{return_id}</НомерДокумента> <Дата>{date}</Дата> <ЗаказИд>{order_id}</ЗаказИд> <Контрагент> <Ид>{user_id}</Ид> <Наименование>{user_name}</Наименование> </Контрагент> <Товары> <Товар> <Ид>{product_id}</Ид> <Наименование>{product_name}</Наименование> <Количество>{qty}</Количество> <ЦенаЗаЕдиницу>{price}</ЦенаЗаЕдиницу> <Сумма>{sum}</Сумма> </Товар> </Товары> <СуммаВозврата>{total}</СуммаВозврата> <Причина>{reason}</Причина> </Возврат> 

On the 1C side, a handler in the configuration reads this node and creates a document “Return of goods from buyer” correctly linked to the original sale via ЗаказИд.

Stock Synchronisation After a Return

After a successful return in 1C, stock is updated. It is important that Bitrix receives this signal and updates b_catalog_store_product. The standard stock exchange (offers.xml) will do this at the next session, but if sessions are infrequent, a separate request is needed:

// 1C calls URL after processing a return ReturnSyncService::updateStocksFromReturn($returnId); 

In updateStocksFromReturn there is a direct update of b_catalog_store_product via \Bitrix\Catalog\StoreProductTable with a call to \Bitrix\Catalog\StoreBatchService if lot recalculation is needed.

Reverse Status Transfer

After creating the document in 1C, a confirmation must be sent back to Bitrix:

Updating the status on the Bitrix side:

$return = \Bitrix\Sale\OrderReturn::load($returnId); $return->setField('STATUS', 'COMPLETED'); $return->setField('COMMENTS', '1C: document #' . $doc1cId); $return->save(); 

Case Study: Wholesale Distributor, 150+ Returns per Month

The client—a distributor of construction chemicals. Returns came via two paths: through the dealer portal on the website and directly from logistics. The problem: the 1C accounting department did not see returns from the site, processed documents manually with a 3–5 day delay. This led to incorrect stock in Bitrix warehouses and conflicts in subsequent orders.

We implemented the following steps:

1. The OnSaleReturnComplete event writes the return to the local_1c_return_queue queue.
2. An agent (every 10 minutes) builds XML and sends it to the 1C endpoint via an HTTP request to the standard exchange handler.
3. 1C processes the document, updates stock, sends confirmation to /api/1c/return-confirm/{returnId}.
4. A webhook in Bitrix updates the return status and recalculates b_catalog_store_product for affected SKUs.

What's Included in the Work

• Analysis of the 1C configuration: document type “Return of goods from buyer”, fields linking to the order
• Development of the XML schema and PHP generator for Bitrix
• OnSaleReturnComplete event handler, exchange queue
• Webhook endpoint for confirmation from 1C
• Stock update in Bitrix after confirmation
• Testing on several scenarios: partial return, return without shipment, return with multiple warehouses

Timeline Estimates

Basic integration (transfer of returns + confirmation) — 3–4 weeks. With real-time stock synchronisation and handling of edge cases — 6–8 weeks. The exact timeline is determined after an audit of your 1C configuration.

Common Pitfalls (Based on Real Projects)

• Forgetting to enable the sale module’s event system for returns—the event OnSaleReturnComplete will never fire if the return process is customised without using the standard API.
• Mixing return documents with order documents in the XML—1C may interpret a return as a new order if the node structure overlaps.
• Assuming stock is updated via the standard offers.xml—that exchange only runs on schedule; for real‑time updates a separate webhook is essential.

Our Approach

Every task requires individual analysis and careful planning. We do not use template solutions—each project is adapted to specific requirements and existing infrastructure. Our team has experience with projects of various scales: from small stores to high‑load platforms processing millions of operations per day.

We guarantee the completed work for 12 months. During this period, we fix any issues free of charge. After the project, we provide full documentation and training for your team. Technical support is available for 30 days after launch—we help resolve any questions and provide consultations.

If your company faces the described challenge, contact us for a free consultation. We will analyse your system and propose an optimal solution. The cost of the project depends on complexity and scope, but for typical solutions we always provide an accurate estimate based on a preliminary requirement analysis.