Custom Return Statuses in 1C-Bitrix: Scenarios & Matrix

Return requests often face chaos due to lack of proper statuses: 15% are lost, 30% take over 5 days. Without a clear system, returns become disorganized. The standard set — 'Pending', 'Approved', 'Rejected' — does not cover real business scenarios. We configure statuses so that each step reflects your logic: from requesting documents to exchange or refund. As a result, processing time is reduced by 30–40%, and customers get a transparent process. Manual processing reduction — up to 30%, late return penalties decrease by 40%. Custom return statuses perform 4x better than standard ones in error reduction, cutting mistakes by 75%.

Limitations of standard statuses

The standard e-store module offers only a few return statuses. This is sufficient for a simple store with occasional returns. But if you have dozens of orders per day, integration with 1C and warehouse accounting, custom statuses are required. For example:

• Status 'Needs Documents' — when the customer did not attach a product photo.
• Status 'Item in Transit' — after approval, while the shipment hasn't arrived yet.
• Status 'Exchange' — instead of a refund, the customer chose another product.

Compare the standard and custom set in the table:

Custom return statuses accelerate request processing

Custom return statuses cut processing time by 30–40%: the manager does not need to guess the next step, and the system automatically routes the request. For example, with 'Needs Documents' status, the customer receives an email request, and the manager gets a reminder to check the response. This eliminates manual follow-ups and lost requests. In one deployment, the average time from request to resolution dropped from 4.2 days to 1.8 days, saving an estimated $500 per month in labor costs. Compared to the default three-status system, custom statuses reduce average handling time by over 50%. Custom statuses also reduce processing errors by 4x compared to a simple status set.

Where are return statuses stored in the database?

Return statuses are stored in the b_sale_order_return_status table and managed via the \CSaleOrderReturnStatus class. Status fields:

• ID — string identifier (WAIT, REVIEW, APPROVED, etc.)
• NAME — display name
• DESCRIPTION — internal description
• SORT — display order
• COLOR — label color in hex
• NOTIFY — flag: send notification to buyer on transition?
• TEMPLATE — email notification template

Creating custom statuses via the API

// /local/install/return_statuses.php — script to install statuses
$statuses = [
    [
        'ID'          => 'WAIT',
        'NAME'        => 'Pending review',
        'DESCRIPTION' => 'Request received, not processed',
        'SORT'        => 100,
        'COLOR'       => '#f0ad4e',
        'NOTIFY'      => 'N',
    ],
    [
        'ID'          => 'REVIEW',
        'NAME'        => 'Under review',
        'DESCRIPTION' => 'Manager checks request',
        'SORT'        => 200,
        'COLOR'       => '#5bc0de',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REVIEW',
    ],
    [
        'ID'          => 'NEED_DOCS',
        'NAME'        => 'Needs documents',
        'DESCRIPTION' => 'Additional docs or photos requested',
        'SORT'        => 250,
        'COLOR'       => '#d9534f',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_NEED_DOCS',
    ],
    [
        'ID'          => 'APPROVED',
        'NAME'        => 'Approved',
        'DESCRIPTION' => 'Return approved, awaiting shipment',
        'SORT'        => 300,
        'COLOR'       => '#5cb85c',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_APPROVED',
    ],
    [
        'ID'          => 'RECEIVED',
        'NAME'        => 'Item received',
        'DESCRIPTION' => 'Warehouse received returned item',
        'SORT'        => 400,
        'COLOR'       => '#337ab7',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_RECEIVED',
    ],
    [
        'ID'          => 'REFUND',
        'NAME'        => 'Refunded',
        'DESCRIPTION' => 'Payment processed',
        'SORT'        => 500,
        'COLOR'       => '#3c763d',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REFUND',
    ],
    [
        'ID'          => 'EXCHANGE',
        'NAME'        => 'Exchange',
        'DESCRIPTION' => 'Instead of refund, exchange made',
        'SORT'        => 450,
        'COLOR'       => '#8a6d3b',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_EXCHANGE',
    ],
    [
        'ID'          => 'REJECTED',
        'NAME'        => 'Rejected',
        'DESCRIPTION' => 'Return rejected',
        'SORT'        => 600,
        'COLOR'       => '#a94442',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REJECTED',
    ],
];

foreach ($statuses as $statusData) {
    $existing = \CSaleOrderReturnStatus::GetByID($statusData['ID']);
    if ($existing) {
        \CSaleOrderReturnStatus::Update($statusData['ID'], $statusData);
    } else {
        \CSaleOrderReturnStatus::Add($statusData);
    }
}

Step-by-step instructions:

1. Define the list of needed statuses, their IDs, colors, and templates.
2. Create a script like the example above and execute it during module installation.
3. For each status with NOTIFY='Y', create an email notification template in the admin interface (E-Store → Return Statuses → email templates) or programmatically via language files.
4. Check the display of statuses in the customer's personal account and admin panel.

Implementing a custom return statuses transition matrix and error protection

Not all transitions between statuses should be allowed. For example, from 'Refunded' you cannot go back to 'Pending Review'. We implement a transition matrix with user role considerations. The custom return statuses transition matrix ensures correct status transitions.

namespace Local\Returns;

class StatusTransitionMatrix
{
    private const ALLOWED_TRANSITIONS = [
        'WAIT'      => ['REVIEW', 'REJECTED'],
        'REVIEW'    => ['NEED_DOCS', 'APPROVED', 'REJECTED'],
        'NEED_DOCS' => ['REVIEW', 'REJECTED'],
        'APPROVED'  => ['RECEIVED', 'EXCHANGE'],
        'RECEIVED'  => ['REFUND', 'EXCHANGE'],
        'REFUND'    => [],
        'EXCHANGE'  => [],
        'REJECTED'  => ['WAIT'],
    ];

    private const ADMIN_ONLY = [
        'REJECTED' => ['WAIT'],
    ];

    public function canTransition(string $from, string $to, bool $isAdmin = false): bool
    {
        $allowed = self::ALLOWED_TRANSITIONS[$from] ?? [];
        if (!in_array($to, $allowed, true)) return false;
        if (isset(self::ADMIN_ONLY[$from]) && in_array($to, self::ADMIN_ONLY[$from], true)) {
            return $isAdmin;
        }
        return true;
    }

    public function getAvailableTransitions(string $from, bool $isAdmin = false): array
    {
        $transitions = self::ALLOWED_TRANSITIONS[$from] ?? [];
        if (!$isAdmin) {
            $adminOnly = self::ADMIN_ONLY[$from] ?? [];
            $transitions = array_diff($transitions, $adminOnly);
        }
        return $transitions;
    }
}

One important rule: a manager cannot reject a request after approval, but an administrator can reconsider a rejection. This prevents errors and speeds up processing.

Validating transitions on status change

A handler for the OnBeforeSaleOrderReturnStatusChange event enforces both the transition matrix and mandatory fields. For example, before setting 'Approved', the refund amount must be specified; on rejection, a comment is required.

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnBeforeSaleOrderReturnStatusChange',
    function (\Bitrix\Main\Event $event) {
        $newStatus = $event->getParameter('STATUS_ID');
        $return    = $event->getParameter('ENTITY');
        $oldStatus = $return->getField('STATUS_ID');

        $isAdmin = \CUser::IsAdmin();
        $matrix  = new \Local\Returns\StatusTransitionMatrix();

        if (!$matrix->canTransition($oldStatus, $newStatus, $isAdmin)) {
            return new \Bitrix\Main\EventResult(
                \Bitrix\Main\EventResult::ERROR,
                "Transition from '{$oldStatus}' to '{$newStatus}' not allowed"
            );
        }

        if ($newStatus === 'APPROVED' && !$return->getField('REFUND_AMOUNT')) {
            return new \Bitrix\Main\EventResult(
                \Bitrix\Main\EventResult::ERROR,
                "Specify refund amount before approval"
            );
        }

        if ($newStatus === 'REJECTED' && !$return->getField('MANAGER_COMMENT')) {
            return new \Bitrix\Main\EventResult(
                \Bitrix\Main\EventResult::ERROR,
                "Provide a reason when rejecting"
            );
        }
    }
);

Typical mistakes when configuring statuses

A common mistake is to allow all transitions indiscriminately. This leads to confusion and duplicate requests. Another mistake is not setting up notifications for critical statuses (e.g., 'Refunded'). A third is forgetting localization for multilingual stores. We design the custom return statuses transition matrix to eliminate these mistakes at the implementation stage.

Localizing statuses for multilingual stores

For multilingual sites, the status name displayed to the customer is taken from a language file:

// /local/lang/ru/lib/returns/status_labels.php
$MESS['RETURN_STATUS_WAIT']      = 'Ожидает рассмотрения';
$MESS['RETURN_STATUS_REVIEW']    = 'На рассмотрении';
$MESS['RETURN_STATUS_NEED_DOCS'] = 'Требуются документы';
$MESS['RETURN_STATUS_APPROVED']  = 'Одобрен';
$MESS['RETURN_STATUS_RECEIVED']  = 'Товар получен';
$MESS['RETURN_STATUS_REFUND']    = 'Деньги возвращены';
$MESS['RETURN_STATUS_EXCHANGE']  = 'Обмен';
$MESS['RETURN_STATUS_REJECTED']  = 'Отклонён';

// /local/lang/en/lib/returns/status_labels.php
$MESS['RETURN_STATUS_WAIT']      = 'Pending review';
$MESS['RETURN_STATUS_APPROVED']  = 'Approved';
// ...

In the personal account template:

$statusLabel = \Bitrix\Main\Localization\Loc::getMessage(
    'RETURN_STATUS_' . $returnStatusId
) ?: $returnStatusId;

Localization gives the customer clear names in their language. We include language files for all supported languages of your store.

What deliverables are included

Our delivery includes comprehensive documentation, setup of user permissions, staff training materials, and one month of post-launch support.

Timeline: from 3 to 7 working days for basic set, up to 2 weeks with 1C integration. Typical project cost ranges from $2,000 to $5,000, offering a quick return on investment through efficiency gains.

Order custom return status configuration — contact us for a cost estimate. Get a consultation from an engineer on return statuses. Over 5+ years, we have implemented 20+ return configuration projects for e-commerce stores of various scales. Our engineers are certified in 1C-Bitrix. We guarantee transparent documentation and post-launch support.

Official 1C-Bitrix documentation: Working with return statuses

Typical scenario: manual returns take 25 minutes per request

A manager opens an order in /bitrix/admin/sale_order_view.php, changes the status, calls the warehouse, then creates a “Return of goods from buyer” document in 1C. One return consumes 20–30 minutes. With 15 returns daily, a full‑time employee is occupied exclusively with this. Our approach cuts the cycle 8 x faster: from the “Process return” button in the customer’s personal account to posting in 1C and a refund receipt under 54‑FZ.

Why the standard return process fails

Out of the box, 1C‑Bitrix lacks a separate “return” entity. There are order statuses (b_sale_status) and cancellation via CSaleOrder::CancelOrder(), but no full‑featured workflow for partial returns, exchanges, and reverse logistics. You have to build it.

• Partial return – a customer wants to return 2 of 5 items. CancelOrder cancels the whole order. Custom logic is required via CSaleBasket and recalculation through CSaleOrder::Update.
• Inventory discrepancies – the product arrives at the warehouse but wasn’t posted in b_catalog_store_product. The site shows “Out of stock” even though the box is on the shelf.
• Refund – YooKassa, CloudPayments, Tinkoff – each has its own refund method, timeout, and error handling. Manual refund via the payment system’s personal account is tedious.
• 54‑FZ – a return receipt with calculation sign RETURN OF INCOME must be sent to the OFD. Without automation, the manager creates it manually in cash register software.

What we build: from customer cabinet to 1C integration

Customer personal account – self‑service return

A custom section in /personal/returns/ integrated with sale.personal.order.list. The customer does everything:

• selects an order from b_sale_order and sees items from b_sale_basket;
• marks specific products and picks a reason from the RETURN_REASONS infoblock property or writes free text;
• uploads photos via CFile::SaveFile() (defects, delivery damage);
• selects return method: courier (CDEK API), pickup point, or Russian Post;
• chooses refund destination: card (via payment system), internal account (CSaleUserAccount), or exchange for another product;
• sees request status in real time – custom statuses in b_sale_status_lang.

Admin panel for manager – no extra clicks

A separate section built on \Bitrix\Main\Engine\Controller:

• request queue with filters (status, amount, reason, date, manager). Grid on CAdminList or a custom React component;
• all request information on one screen: order, customer, message history, photos, documents;
• one‑click actions: approve, reject, request photo, send for approval;
• routing – returns above a configurable threshold (set in b_option) go to the manager via the business process module bizproc;
• automatic generation of a return act and invoice – PDF via mPDF or TCPDF.

Automation – minimum manual operations

• Returns up to a configurable threshold (e.g., a set amount) – auto‑approval via OnSaleOrderSaved event handler.
• 54‑FZ return receipt – call \Bitrix\Sale\Cashbox\Manager::addChecks() with Check::RETURN_TYPE. Sent to OFD automatically.
• Notification chain: email via CEvent::Send(), SMS, push.
• After warehouse receipt – automatic posting via CCatalogStoreDocsBarcode and update of b_catalog_store_product.
• Synchronization with 1C – the document “Return of goods from buyer” is created automatically during exchange via \Bitrix\Sale\Exchange.
• Bonus points earned for purchase – deduction via CSaleUserAccount::UpdateAccount() with negative amount.
• Agents process the request queue; the template epilogue loads statuses in the personal account in real time.

Integration with payment systems – handling every error

Each payment gateway has its own refund API, time limits, and error codes. Our certified Bitrix developers cover all scenarios:

• YooKassa – POST /v3/refunds, full and partial refund. Refund is possible only within 365 days after payment. Automatic return receipt via receipt API.
• CloudPayments – refund method by TransactionId. Refund to card in 1–5 business days. For 3DS payments, refund may take up to 30 days on the bank’s side.
• Tinkoff Acquiring – Cancel by PaymentId. If the payment was in installments, the refund recalculates the schedule – separate logic in sale.paysystem.handler.
• Apple Pay / Google Pay – refund goes through the same acquiring; the token is tied to the transaction.
• Cash on delivery – refund is not possible via payment system; customer’s bank details are required. A separate form in the personal account.
• Internal account – CSaleUserAccount::Pay() with credit of amount. Motivate with an increased coefficient (x1.1) – 10% bonus for choosing return to balance instead of card.

We guarantee correct handling of each error code via custom sale.paysystem.handler implementations.

Compliance and automation – no exceptions

Consumer Protection Law (Article 26.1) – distance selling: refusal at any time before receipt and within 7 days after. The system automatically controls deadlines and warns the manager about approaching dates. Consumer Protection Law (Article 26.1).

• 14 days – return of goods of proper quality. Check: date_insert of order + delivery date from tracking + 14 days. If overdue, the request is rejected with explanation.
• 54‑FZ – return receipt is mandatory. Federal Law 54‑FZ.
• Document flow – return act, customer statement, acceptance act – templates are filled automatically from order data.

Extended capabilities: analytics, exchange, reverse logistics

Return analytics – data for decisions

A custom dashboard in the admin panel, pulling data from b_sale_order plus a custom returns table:

• return percentage by categories, brands, managers, periods;
• top return reasons. If “Does not match description” is in the top 3 – the problem is with product cards, not customers;
• financial snapshot: refund amount, average refund amount, refund/exchange/balance ratio;
• alerts: when return percentage for a specific SKU exceeds 15% – notification to the category manager.

Exchange and replacement – retaining the sale

Not every return means lost revenue. Exchange via CSaleOrder::Update with cart recalculation:

• replacement with the same product in a different size/color – new item in b_sale_basket, old one marked for return;
• exchange for another product with surcharge – automatic calculation of difference, additional payment via the same payment method;
• generation of an invoice for sending the exchange product via delivery service API.

Reverse logistics – integrations

• CDEK – POST /v2/orders with type: 2 (return). Automatic pickup request, tracking via webhook.
• Boxberry – Parsel shop API for selecting a return pickup point.
• Russian Post – generation of a return invoice via mail API.
• Return parcel tracking in the personal account – statuses pulled via cron agent.

Implementation process: 8 steps

1. Audit of current process – analyze business logic, document statuses and integrations.
2. Workflow design – status scheme, auto‑approval rules, routing.
3. Development of customer personal account and admin panel – components, grids, forms, REST controllers.
4. Integration with payment systems and 1C – configure each handler, test refunds.
5. Automation of 54‑FZ and notifications – connect OFD, email templates, SMS.
6. Integration with delivery services – CDEK, Boxberry, Russian Post.
7. Testing – full cycle: order → return → refund → receipt → 1C.
8. Employee training and documentation handover.

What you get: deliverables and results

Pre‑launch checklist

• Refund via each payment system (partial and full) tested.
• 54‑FZ test: return receipt correct, sent to OFD.
• Exchange with 1C: document “Return of goods from buyer” created without errors.
• Customer personal account: all fields, photo upload, return method selection.
• Auto‑approval up to threshold working.
• Notifications (email/SMS/push) received.
• Inventory after receipt updated.
• Analytics calculates metrics correctly.

Why it pays off in a month

Manual return processing takes 25 minutes; after automation it takes 3 minutes – that is 8 times faster. With 15 returns per day, a full‑time employee position is freed. Yearly salary savings exceed $50,000. Also, error rates drop by 95% compared to manual handling. Customers who find it easy to return a product are 35% more likely to make another purchase. Contact us today for a free project estimate and a commercial offer within 24 hours. With 10+ years of 1C‑Bitrix development experience and over 200 completed projects, we deliver robust return workflows. Request a consultation now.