WB API Digest — July 2025

WB API Updates Digest for July 2025

In July, we introduced a number of important updates to the API. In this edition of our monthly digest, we’ve compiled the key innovations of the month and explained the practical benefits you’ll gain from using them.

---

Customer Communication

Access Full Order Context in Customer Requests

The Chat List method now includes a new goodCard object, which enhances customer request handling. Each chat is now automatically enriched with full order context:

• date — order date
• needRefund — whether a refund was requested
• nmID — WB SKU
• price — actual price with all discounts applied
• priceCurrency — currency
• rid — unique order ID
• size — product size
• statusID — product status

Practical business benefits:

Imagine a typical situation: a customer writes «I have an issue with my order.» Previously, a manager had to ask for the order number, then search for it in the system, clarify details, and only then proceed. Now all information is available immediately when the request arrives. This shortens resolution time, benefiting both the seller and the customer.

Opportunities for developers:

The new fields enable advanced automation systems:

1. Automatic categorization. Use needRefund to automatically route refund-related chats to the right department or specialists.
2. CRM integration. Transfer complete order context into your CRM, creating tickets with pre-filled fields.
3. Chatbot development. Build intelligent bots that provide personalized responses based on order status and product price.
4. Product quality analytics. Collect statistics by nmID to identify products generating the most customer complaints.

---

DBS & Click & Collect

New Sandbox Features

The sandbox for DBS and Click & Collect models now includes important fields for handling international sales:

For DBS and Click & Collect:

• finalPrice — price in sale currency including all discounts × 100
• convertedFinalPrice — price in seller’s country currency including all discounts × 100

Additional for Click & Collect:

• convertedPrice — price in seller’s country currency including all discounts except WB Wallet discount × 100
• convertedCurrencyCode — seller’s country currency code

Affected methods:

• Get list of new assembly tasks (DBS)
• Get completed assembly tasks (DBS)
• Get list of new assembly tasks (Click & Collect)
• Get completed assembly tasks (Click & Collect)

Practical business benefits:

For companies operating in international Wildberries markets, these fields solve key financial accounting challenges. Example: a Russian company sells goods in Kazakhstan. The buyer pays in tenge, but accounting is done in rubles. The new fields allow:

1. Accurate revenue calculation. Automatically receive converted sums without tracking exchange rates at transaction time.
2. Discount efficiency analysis. convertedPrice (for Click & Collect) shows the price excluding WB Wallet discounts, allowing precise evaluation of loyalty program impact on margins.
3. Safe testing. All fields are available in sandbox mode, enabling full debugging of financial integrations without risking real data.

Opportunities for developers:

1. Automated accounting. Directly integrate with 1C or ERP systems by transmitting converted sums, removing the need for manual currency conversion.
2. Multi-currency dashboards. Create reporting systems that show revenue in both sales currency and company base currency without extra calculations.

---

Documents & Accounting

Transparent Loyalty Program in Financial Reports

The weekly sales report details now include two key fields:

• cashback_amount — amount withheld for accrued loyalty points
• cashback_discount — compensation of loyalty program discount

Practical business benefits:

Wildberries loyalty programs are a powerful tool for customer acquisition. These fields bring clarity:

1. Precise unit economics. Calculate acquisition and retention costs accurately. Example: if cashback_amount equals 5% of revenue and repeat purchases increased by 15%, ROI becomes more transparent.
2. Pricing optimization. Knowing exact compensations helps adjust base product prices to maintain target margins even with cashback.
3. Tax optimization. Clear separation of withholdings and compensations simplifies tax accounting and reporting.

Opportunities for developers:

1. Automated financial analytics. Integrate new fields into BI systems for automatic reports on loyalty program profitability.
2. Predictive analytics. Use historical cashback data to forecast future program expenses.
3. ERP integration. Automatically transfer cashback data into accounting systems for correct financial reporting.

---

Reports

Full Return Management Cycle

The Returns & Transfers Report now includes five new fields:

• reason — return reason
• orderId — assembly task number
• readyToReturnDt — date and time when return became ready for pickup
• expiredDt — expiration date and time of return storage
• completedDt — date and time return was issued back to seller

Practical business benefits:

Returns are a valuable source of data on product quality and customer satisfaction. These fields transform return management:

1. Return reason analysis. reason helps categorize and identify patterns. If 30% of returns for a product are due to size mismatch, that signals the need to adjust size charts or descriptions.
2. Return logistics optimization. Timestamps (readyToReturnDt, expiredDt, completedDt) enable SLA tracking. If average time from ready to completed is 5 days, with a 7-day storage period, logistics efficiency should be reviewed.
3. Loss minimization. Tracking expiredDt helps prevent losses from unclaimed returns. Automated notifications 2–3 days before expiration can save significant costs.

Opportunities for developers:

1. Early warning systems. Configure alerts when expiredDt approaches and integrate with email notifications for fast response.
2. Dashboards. Visualize return reasons by product, category, or supplier to quickly identify problem areas.

---

FBS Orders

Expiration Dates for Products

From July 21, sellers can set product expiration dates in FBS assembly task metadata. This includes:

• Get new assembly tasks — check expiration capability via expiration in requiredMeta
• Set expiration date for assembly task — set expiration date (minimum 30 days from current date, only for status confirm)
• Get assembly task metadata — check expiration

Important restriction: expiration dates cannot be deleted, only updated.

Practical business benefits:

For sellers of food, cosmetics, and supplements, this is a game-changer:

1. Risk reduction. Automated expiration control prevents shipping expired goods, avoiding heavy fines.
2. Product rotation management. Enables FIFO (First In, First Out) at API level, prioritizing older stock automatically.

Opportunities for developers:

1. Automated quality control. Build systems that check for expiration in requiredMeta and block expired shipments.
2. Smart prioritization. Develop algorithms to sort orders by remaining shelf life and optimize assembly sequence.

Warehouse Synchronization to Prevent Logistics Issues

New fields were added to FBS supply and assembly task methods:

1. officeID (WB warehouse ID linked to seller’s warehouse) in:

• Get new assembly tasks
• Get assembly task details

2. destinationOfficeId (destination warehouse ID for supply) in:

• Get supply list
• Get supply details

Important change from September 1, 2025: The add assembly task to supply method will return error 409 if officeID doesn’t match destinationOfficeId.

Practical business benefits:

1. Eliminating cross-warehouse errors. Orders from one warehouse cannot be added to supplies of another, preventing mismatched shipments.
2. Optimized routing. Automatic warehouse validation improves logistics planning and reduces costs.

---

Product Management

Geographic Warehouse Data

The WB warehouses method now includes federalDistrict — the Russian federal district of the warehouse. null indicates warehouses outside Russia or without district data.

Practical business benefits:

1. Regional supply planning. Analyze warehouse distribution by district for optimal stock placement. Example: if 40% of sales are in the Central District but only 20% of warehouses are there, consider reallocation.
2. Reduced logistics costs. Use warehouses in regions close to your main audience, cutting last-mile expenses.

Opportunities for developers:

1. Geo-visualization. Integrate federal district data with mapping tools to build interactive warehouse maps.
2. Automated warehouse selection. Create algorithms to assign the optimal warehouse based on buyer geolocation and stock.

---

FBW Supplies

New Warehouse Flags

The warehouse list method now includes availability flags:

• isActive — warehouse available as a destination
• isTransitActive — warehouse available as a transit hub

Additionally, from July 14 the acceptance options method is limited to 6 requests per minute.

Practical business benefits:

1. Adaptive logistics. During peak periods (Black Friday, New Year, holidays), overloaded warehouses can be bypassed. Flags allow automatic rerouting to available locations.
2. Optimized transit routes. isTransitActive enables building advanced routes through transit warehouses, cutting delivery times by 20–30%.

Opportunities for developers:

1. Graceful degradation. Automatically switch to transit warehouses when main ones are unavailable, ensuring continuous operations.
2. Respect rate limits. Implement exponential backoff and request queues to stay within limits.

---

Implementation Checklist

Readiness

By September 1, 2025 (mandatory):

• Check all integrations for matching officeID and destinationOfficeId.

Recommended soon:

• Update monitoring systems to track new fields
• Adapt reports for new metrics
• Adjust integrations to new rate limits

---

Conclusion

The July WB API updates show a clear platform development path: improved transparency, better quality control, and optimized logistics. Each innovation is not just a technical improvement but a tool for building a more efficient and profitable marketplace business.

The key to success is a comprehensive approach: don’t just add new fields, rethink business processes around the new data.

Stay tuned for API updates and always test changes in the sandbox before applying them to real data. Wishing you a smooth integration!