Returns Module

The Returns module (sdk.returns) is an aggregator introduced in v3.10.0 that unifies three separate Wildberries data sources — FBO analytics, FBS order history, and Finance reports — into a single ReturnItem[]. It handles deduplication by srid, partial-failure tolerance via Promise.allSettled, per-source telemetry, and automatic reason classification.

---

Overview

Property	Value
Module Name	returns
SDK Namespace	sdk.returns.*
Introduced	v3.10.0
Sources	sdk.reports.getAnalyticsV1GoodsReturn() for both active and archive FBO returns, sdk.ordersFBS status history (FBS — deferred to v3.10.1), sdk.finances.getSalesReportsDetailed() (Finance)
Methods	3
Authentication	Delegates to underlying modules

Purpose

sdk.returns is designed to:

• Unify FBO + Finance return data — single ReturnItem[] with finance enrichment (returnAmount, returnAmountCurrency)
• Classify return reasons — maps free-text Russian WB reasons to stable ReturnReasonCode enum via classifyReturnReason() (called internally)
• Surface partial failures transparently — if one source is unavailable, other sources still return data; failures reported in partialFailures
• Report per-source telemetry — _meta.sources tells you exactly how many records each source fetched, filtered, and whether it was skipped

---

Quick Start

import { WildberriesSDK } from 'daytona-wildberries-typescript-sdk';

const sdk = new WildberriesSDK({ apiKey: process.env.WB_API_KEY! });

// Get all returns for April 2026
const result = await sdk.returns.getReturns({
  dateFrom: '2026-04-01',
  dateTo: '2026-04-30',
});

console.log(`Total returns: ${result.total}`);
console.log(`FBO fetched: ${result._meta.sources.fbo.fetched}`);

result.data.forEach((r) => {
  console.log(r.orderId, r.returnReasonCode, r.returnAmount ?? 'pending');
});

---

Methods

getReturns(params: ReturnsApiRequest): Promise<ReturnsApiResponse>

Primary aggregation method. Fetches FBO returns and Finance enrichment in parallel, merges by srid, applies optional filters, and returns results with full telemetry.

For FBO data the aggregator requests active pages first, then archive pages. Each page uses limit: 1000 and advances offset until WB returns fewer than 1,000 rows. Calls pass through the shared Reports limiter (1 request/minute, burst 1); an HTTP 204 response is treated as an empty page.

Parameters:

Name	Type	Required	Description
dateFrom	string	Yes	ISO date YYYY-MM-DD. Maximum 31-day range.
dateTo	string	Yes	ISO date YYYY-MM-DD.
nmIds	number[]	No	Filter by product article numbers.
orderType	'fbo' | 'fbs'	No	Filter by fulfilment type.
reasonCodes	ReturnReasonCode[]	No	Filter by classified reason code.

See also: Full guide with 4 recipes →

---

getReturnByOrderId(orderId: string, params: ReturnByOrderIdParams): Promise<ReturnItem | null>

Convenience wrapper around getReturns() that filters to a single order. Returns null when no matching record is found in the date window.

Parameters:

Name	Type	Required	Description
orderId	string	Yes	WB order ID (string, BigInt-safe).
params.dateFrom	string	Yes	Same semantics as getReturns().
params.dateTo	string	Yes	Same semantics as getReturns().
params.orderType	'fbo' | 'fbs'	No	Narrows which source to query.

---

getReturnStats(params: ReturnStatsParams): Promise<ReturnStatsResult>

Calls getReturns() once and post-processes all records into aggregation buckets in memory. Useful for dashboard KPIs without building your own grouping logic.

Parameters:

Name	Type	Required	Description
dateFrom	string	Yes	ISO date.
dateTo	string	Yes	ISO date.
groupBy	'nmId' | 'category' | 'orderType'	Yes	Aggregation dimension.
nmIds	number[]	No	Pre-filter passed to getReturns().
orderType	'fbo' | 'fbs'	No	Pre-filter passed to getReturns().

---

Key Types

Type	Kind	Description
ReturnItem	interface	Single unified return record
ReturnStatus	type alias	'initiated' | 'received' | 'processed'
ReturnCategory	type alias	'cancel_before_shipment' | 'refusal_at_pvz' | 'return_after_receipt' | 'unknown'
FbsStatusEvent	interface	FBS status history event used by classifyFbsReturnCategory()
ReturnsApiRequest	interface	Input params for getReturns()
ReturnsApiResponse	interface	Response from getReturns()
PartialFailure	interface	Describes a source that failed during aggregation
ReturnsMeta	interface	Per-source telemetry in every response
ReturnByOrderIdParams	interface	Params for getReturnByOrderId()
ReturnStatsParams	interface	Params for getReturnStats()
ReturnStatsResult	interface	Aggregated stats with buckets
ReturnStatsBucket	interface	Single aggregation bucket (one nmId / category / orderType)

---

Helper Function

classifyFbsReturnCategory(statuses: FbsStatusEvent[]): ReturnCategory

Standalone helper (exported from root index) that analyzes a chronological FBS status event array and maps it to a stable ReturnCategory. Called internally by ReturnsModule for FBS records.

See also: API reference →

---

Known Limitations

Limitation	Details
No webhooks	Poll getReturns() every 5–15 min
No in_transit status	ReturnStatus excludes intermediate states
Free-text reasons	Use returnReasonCode (auto-classified) not returnReason
Weekly finance cadence	returnAmount may be undefined for returns within ~7 days
returnCategory: 'unknown' for FBO	FBS implementation deferred to v3.10.1
31-day max date range	Chunk manually for longer periods
No vendorCode for FBO	Always undefined for FBO records

---

Related Resources

• Returns Module Guide — Mermaid diagram, 4 copy-paste recipes, method reference, telemetry contract
• Buyout & Return Reconciliation — Lower-level helpers from v3.9.3 (classifyReturnReason, enrichReturnsWithType, reconcileBuyoutsAndReturns)
• API Reference: ReturnsModule
• API Reference: classifyFbsReturnCategory