Wildberries API TypeScript SDK v5.0.0

Wildberries API TypeScript SDK Main entry point

Modules

Module	Description
<internal>	-

Classes

Class	Description
BaseClient	Base HTTP client for all Wildberries API modules
AuthenticationError	Authentication error thrown when API key is invalid or lacks permissions.
WBAPIError	Base error class for all Wildberries SDK errors.
BidOutOfRangeError	Error thrown when WB rejects a bid for being out of the accepted range.
CustomsDeclarationIsRequiredError	Error thrown when WB returns HTTP 409 with body code: 'CustomsDeclarationIsRequired' — at least one assembly order in the request lacks a required customs-declaration (ДТ, декларация на товары) number.
PickupOrderNotFoundError	Error thrown when a pickup order is not found
InvalidOrderStateError	Error thrown when an order state transition is invalid
CustomerVerificationError	Error thrown when customer identity verification fails
MetadataValidationError	Error thrown when product metadata validation fails
MetaValidationFailError	Error thrown when PATCH /api/v3/supplies/{supplyId}/deliver returns HTTP 409 with marking-code validation failures in the metaDetails response array.
NetworkError	Network error thrown for connection failures, timeouts, and server errors.
CampaignNotFoundError	Error thrown when a campaign is not found by its ID.
InvalidBidError	Error thrown when bid amount is invalid or below minimum.
BudgetExceededError	Error thrown when campaign budget is exceeded or insufficient.
InvalidCampaignStateError	Error thrown when attempting invalid campaign state transitions.
RateLimitError	Rate limit error thrown when API rate limits are exceeded.
ValidationError	Validation error thrown when request data fails validation.
WarehouseStocksUpdateBlockError	Error thrown when WB returns HTTP 406 WarehouseStocksUpdateBlock on inventory updates.
WildberriesSDK	Main SDK class providing access to all Wildberries API modules.
AnalyticsModule	-
CommunicationsModule	-
FinancesModule	-
GeneralModule	-
InStorePickupModule	-
OrdersDbsModule	Orders DBS Module for managing Delivery by Seller orders
OrdersFbsModule	-
OrdersFbwModule	-
ProductsModule	-
PromotionModule	-
ReportsModule	-
ReturnsModule	Returns aggregator module — combines FBO, FBS, and Finance sources into a unified ReturnItem[] with full partial-failure tolerance.
TariffsModule	-
UserManagementModule	-

Interfaces

Interface	Description
RateLimitConfig	Configuration for rate limiting a specific endpoint.
OperationMetadata	Metadata for a single SDK operation
SDKConfig	Configuration options for initializing the Wildberries SDK
RequestOptions	Per-request options that can override SDK defaults
SellerMessageRequest	Request body for CommunicationsModule.createSellerMessage.
CreateTestDbsOrderItem	Product and quantity for one test DBS assembly order.
CreateTestDbsOrdersAddress	Delivery address for test DBS assembly orders.
CreateTestDbsOrdersRequest	Request body for ordersDBS.createTestOrders().
DBSClientInfo	Customer contact information for DBS orders Returned by getClientInfo
MetaValidationDetail	Per-order metadata validation status returned in 409 MetaValidationFail responses. When deliverBulk() returns this for an order, the marking metadata (SGTIN/IMEI) failed WB's validation — fix the metadata before retrying.
GetClientInfoResponse	Response from getClientInfo
OrderMetaResponse	Response containing metadata for a single order
OrdersMetaResponse	Response containing metadata for multiple orders
OrderMetaItem	A single order's metadata entry (used in bulk metadata responses)
MetaDetail	Metadata detail item with validation status Replaces the deprecated meta object. Use with /api/marketplace/v3/orders/meta endpoint.
APIError	API error response (v3 schema) Maps to swagger schema: v3.APIError
APIErrorV2	WB v3 APIErrorV2 envelope -- the newer V2 error shape returned by some v3 endpoints (e.g. 400/403 responses). Maps to swagger schema: v3.APIErrorV2.
DBWDeleteMetaBulkRequest	Request body for bulk deletion of marking metadata from DBW orders. Mirrors DBS DeleteMetaBulkRequest.
DBWDeleteMetaBulkResponse	Response from bulk metadata deletion for DBW orders. Mirrors DBS DeleteMetaBulkResponse.
DBWSetSgtinBulkRequest	Request body for bulk SGTIN code assignment on DBW orders. Mirrors DBS SetSgtinBulkRequest.
DBWSetMetaBulkResponse	Response from bulk metadata set operations for DBW orders. Mirrors DBS SetMetaBulkResponse.
DBWCheckMetaValidationRequest	Request body for OrdersFbwModule.checkMetaValidation.
DBWCheckMetaValidationResponse	Response from OrdersFbwModule.checkMetaValidation. Each item in metaDetails[] reports the validation status of a single order's marking metadata. Use this before calling deliverBulk() to detect orders that would fail with 409 MetaValidationFail.
GetDirectoryTnvedAllOptions	Query parameters for GET /api/content/v2/directory/tnved/all.
GetDirectoryOkpdOptions	Query parameters for GET /api/content/v2/directory/okpd.
GetDirectoryOkpdAllOptions	Query parameters for GET /api/content/v2/directory/okpd/all.
TnvedDirectoryEntry	TN VED entry returned by GET /api/content/v2/directory/tnved/all.
OkpdDirectoryEntry	OKPD2 entry returned by the OKPD2 directory methods.
GetDirectoryTnvedAllResponse	Successful full TN VED directory response.
GetDirectoryOkpdResponse	Successful OKPD2 directory response.
CardDocumentInput	A single product card document in create requests. Used in createCardsUpload() (per variant), createUploadAdd() (per card to add).
CardDocumentsRequest	Documents block of a product card in create requests (createCardsUpload(), createUploadAdd()).
CardUpdateDocumentInput	A single product card document in update requests (createCardsUpdate()).
CardUpdateDocumentsRequest	Documents block of a product card in update requests (createCardsUpdate()).
CardDocumentVerdict	Validation verdict of a single card document. Returned in getCardsList() responses when the document validation is completed.
CardDocumentsOverallVerdict	Overall validation verdict of the card listing documents. Returned in getCardsList() responses when the validation is completed.
CardDocument	A single product card document as returned by getCardsList().
CardDocumentsResponse	Documents block of a product card in getCardsList() responses.
StockItem	A single stock record on a seller warehouse.
StocksRequest	Request body for ProductsModule.getStocks and ProductsModule.deleteStock.
UpdateStockRequest	Request body for ProductsModule.updateStock.
GetStocksResponse	Response from ProductsModule.getStocks.
DeleteCardsFromTrashRequest	Request body for ProductsModule.deleteCardsFromTrash.
DeleteCardsFromTrashResponse	Response from ProductsModule.deleteCardsFromTrash.
ReturnItem	Unified return record across FBO and FBS sources.
ReturnsApiRequest	Request parameters for sdk.returns.getReturns().
PartialFailure	Per-source failure record returned in ReturnsApiResponse.
ReturnsMeta	Per-source telemetry — surfaces what was fetched/skipped.
ReturnsApiResponse	Response from sdk.returns.getReturns().
ReturnByOrderIdParams	Parameters for sdk.returns.getReturnByOrderId(). Date window is required because WB API requires it.
ReturnStatsParams	Parameters for sdk.returns.getReturnStats().
ReturnStatsBucket	Single bucket in a return statistics aggregation.
ReturnStatsResult	Aggregated return statistics returned by sdk.returns.getReturnStats(). Surfaces underlying getReturns() telemetry transparently.
AccessItem	Элемент настройки доступа к разделу профиля продавца
InviteeInfo	Информация о приглашении пользователя
UserInfo	Информация о пользователе профиля продавца
GetUsersResponse	Ответ на запрос списка пользователей
GetUsersParams	Параметры запроса для получения списка пользователей
CreateInviteRequest	Запрос на создание приглашения пользователя
CreateInviteResponse	Ответ на запрос создания приглашения
UserAccess	Настройки доступа для конкретного пользователя
UpdateUserAccessRequest	Запрос на обновление настроек доступа пользователей
UserManagementErrorResponse	Ответ с информацией об ошибке от User Management API
BidRange	Effective accepted bid range for an article, in kopecks.
SupplyCostInput	Input parameters for supply cost calculation
SupplyCostResult	Result of supply cost calculation
FbsStatusEvent	Single FBS status event from order status history. Consumer shapes this from their order_wb_status_history table or SDK call.
CompareTariffsInput	Input parameters for tariff comparison
TariffData	Tariff data from a single source
TariffDifference	Percentage differences between inventory and supply tariffs
TariffComparison	Complete tariff comparison result
WbReturn	Unified return record across FBO and FBS sources.
FbsReturnInput	Minimal FBS return shape — what consumers should pass for FBS returns. The actual FBS return data comes from order status history; consumers shape it into this minimal record before calling enrichReturnsWithType().
MetaValidationFailPayload	Parsed payload extracted from a MetaValidationFailError or a compatible plain object.
AcceptanceDeltaItem	Per-nmId acceptance delta (declared vs accepted).
ReconcileAcceptanceDeltaInput	Input for reconcileAcceptanceDelta.
ReconcileAcceptanceDeltaResult	Aggregated acceptance reconciliation result.
BuyoutInput	Buyout record input — minimal shape derived from sdk.analytics getStocksReportProducts() output. Consumers shape their data into this before calling reconcileBuyoutsAndReturns().
ReconciliationAnomaly	Anomaly detected during reconciliation.
ReconciliationResult	Per-nmId reconciliation summary.
ReconcileOptions	Optional configuration for reconciliation.
ROASResult	Result of computeROAS.
ComputeROASOptions	Options for computeROAS.
MergedCardVariant	A single product variant within a merged card.
MergedCardValidationResult	Result of merged card variant validation.

Type Aliases

Type Alias	Description
EndpointLimits	Mapping of endpoint keys to their rate limit configurations.
DbsTestDeliveryType	Delivery model for a test DBS assembly order in the WB sandbox.
DBWBulkStatusChangeResponse	Response shape for DBW bulk status-change operations (alias for BulkStatusChangeResponse). Maintained as a DBW-prefixed alias to preserve API symmetry with DBW request types.
DBWStatusSetResponse	Per-order result item in a DBW bulk status-change response (alias for StatusSetResponse).
DBWMetaValidationDetail	Per-order metadata validation detail (alias for MetaValidationDetail).
TnvedDirectoryLocale	Supported response language for the full TN VED directory.
OkpdDirectoryLocale	Supported response language for the subject-specific OKPD2 directory.
OkpdFullDirectoryLocale	Supported response language for the full OKPD2 directory.
GetDirectoryOkpdAllResponse	Successful full OKPD2 directory response.
CardDocumentType	Product card document type (WB register document kinds).
CardDocumentReason	Reason a card document failed validation. Returned for verdict.status: 2 (validation rejected) in getCardsList() responses.
CardListingValidationReason	Reason a card listing failed validation. Returned for overallVerdict.status: 2 (validation rejected) in getCardsList() responses.
ReturnStatus	Current state of a return.
ReturnCategory	Categorized return type, derived from order fulfillment path and status history.
AccessCode	Код раздела профиля продавца, к которому пользователь получит доступ.
ReturnReasonCode	Standardized return reason codes derived from Wildberries free-text reason strings.
TariffRecommendation	Recommendation based on tariff comparison

Variables

Variable	Description
analyticsRateLimits	-
communicationsRateLimits	-
financesRateLimits	-
generalRateLimits	-
inStorePickupRateLimits	-
operationMetadata	Registry of operation metadata for all SDK operations
ordersDbsRateLimits	-
ordersFbsRateLimits	-
ordersFbwRateLimits	-
productsRateLimits	-
promotionRateLimits	-
ALL_RATE_LIMITS	Aggregated rate limit configuration for all SDK modules.
reportsRateLimits	-
tariffsRateLimits	-
userManagementRateLimits	-
version	SDK version
COMMUNICATIONS_LIMITS	Exported limits for external testability and documentation.
WITH_PHOTO_FILTER	Filter values for ProductsModule.getCardsList data.settings.filter.withPhoto.

Functions

Function	Description
isOperationReadonly	Check if an operation is readonly (safe to retry)
getOperationCategory	Get the API category for an operation
getOperationRateLimitKey	Get the rate limit key for an operation
getOperationMetadata	Get full metadata for an operation
getOperationsByCategory	Get all operations for a specific category
getReadonlyOperations	Get all readonly operations
getWriteOperations	Get all write operations (not readonly)
parseBidOutOfRangeDetail	Parse a WB advert detail string for the bid-out-of-range format.
extractBidRange	Compute the effective bid range for an article from a recommendations response.
validateBid	Validate a desired bid against an article's recommendation range.
clampBid	Clamp a desired bid into an article's recommendation range.
calculateSupplyCost	Calculates the total supply cost including acceptance, storage, and logistics
classifyFbsReturnCategory	Classifies an FBS order's return category by analyzing its status history.
classifyReturnReason	Classifies a Wildberries return reason string into a standardized enum code.
compareTariffs	Compare tariffs between inventory storage (tariffs/box) and supply (acceptance/coefficients) APIs
warnOnce	Emit a deprecation warning for a method, at most once per process.
resetDeprecationWarnings	Reset all deprecation warning flags. Test helper only.
enrichReturnsWithType	Builds a unified WbReturn[] from FBO returns and optional FBS returns (derived from sdk.ordersFBS status history).
parseMetaValidationFail	Extracts marking-code validation failure details from an unknown caught value.
parseMoneyAmount	Parse a money amount string from v1 finance reports to a JavaScript number.
reconcileAcceptanceDelta	Reconciles declared vs accepted quantity per nmId for FBO acceptance.
reconcileBuyoutsAndReturns	Reconciles buyouts and returns per nmId for unified analytics.
computeROAS	Compute ROAS (Return on Ad Spend) from WB fullstats per-day data.
validateMergedCardVariants	Client-side validator for merged product card variants.
validateRequiredCharacteristics	Validates that all mandatory characteristics are present in a card creation request. Returns the list of missing mandatory characteristics.

References

default

Renames and re-exports WildberriesSDK