Orders FBS Module

The Orders FBS (Fulfillment by Seller) module provides comprehensive order management for sellers who process and ship orders from their own warehouses to Wildberries offices. This module handles the complete FBS workflow: order retrieval, supply management, shipping label generation, metadata attachment, and warehouse pass management.

---

Overview

Module Name: ordersFBSSource: Generated from wildberries_api_doc/03-orders-fbs.yamlBase URL: https://marketplace-api.wildberries.ruTotal Methods: 39 methods across 7 functional areas

FBS vs FBW

Feature	FBS (Fulfillment by Seller)	FBW (Fulfillment by Wildberries)
Stock Location	Seller's warehouse	Wildberries warehouse
Order Processing	Seller packs & ships	WB handles logistics
Shipping Labels	Seller generates	Not applicable
Delivery Target	WB pickup points/offices	Direct from WB
Module	sdk.ordersFBS	sdk.ordersFBW

---

Installation and Setup

Accessing the Module

The Orders FBS module is automatically available when you initialize the SDK:

import { WildberriesSDK } from 'wb-api-sdk';

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

// Access the Orders FBS module
const ordersFBS = sdk.ordersFBS;

Required Permissions

Ensure your API key has the following permissions enabled:

• Order management (read/write)
• Supply management (read/write)
• Sticker generation (read)
• Metadata management (read/write)

---

Methods Reference

Orders (6 methods)

Method	Description	Rate Limit
getOrdersNew()	Get all new orders awaiting processing	300 req/min
orders(options?)	Get orders with pagination and date filters	300 req/min
getOrderStatuses(data)	Get statuses for multiple orders (bulk)	300 req/min
updateOrdersCancel(orderId)	Cancel an order	100 req/min
getOrdersReshipment()	Get orders requiring reshipment	300 req/min
createOrdersStatu(data)	@deprecated Use getOrderStatuses()	300 req/min

Supplies (10 methods)

Method	Description	Rate Limit
createSupply(data)	Create a new supply	300 req/min
supplies(options?)	List supplies with pagination	300 req/min
getSupply(supplyId)	Get supply details	300 req/min
deleteSupply(supplyId)	Delete an empty supply	300 req/min
updateSuppliesDeliver(supplyId)	Transfer supply to delivery	300 req/min
getSuppliesBarcode(supplyId, options?)	Get supply QR code	300 req/min
addOrdersToSupply(supplyId, data)	Add multiple orders to supply (bulk)	300 req/min
getSupplyOrderIds(supplyId)	Get order IDs in a supply	300 req/min
updateSuppliesOrder(supplyId, orderId)	@deprecated Use addOrdersToSupply()	1000 req/min
getSuppliesOrder(supplyId)	@deprecated Use getSupplyOrderIds()	300 req/min

Passes (5 methods)

Method	Description	Rate Limit
getPassesOffices()	List warehouses requiring passes	300 req/min
passes()	List seller passes	300 req/min
createPass(data)	Create a seller pass	1 req/10min
updatePass(passId, data)	Update a seller pass	300 req/min
deletePass(passId)	Delete a seller pass	300 req/min

Metadata (8 methods)

Method	Description	Rate Limit
getOrdersMetaBulk(data)	Get metadata for multiple orders (bulk)	1000 req/min
deleteOrdersMeta(orderId, options?)	Delete order metadata by key	300 req/min
updateMetaSgtin(orderId, data)	Attach SGTIN marking codes	1000 req/min
updateMetaUin(orderId, data)	Attach UIN code	1000 req/min
updateMetaImei(orderId, data)	Attach IMEI code	1000 req/min
updateMetaGtin(orderId, data)	Attach GTIN code	1000 req/min
updateMetaExpiration(orderId, data)	Set expiration date	1000 req/min
setCustomsDeclaration(orderId, data)	Set customs declaration number	1000 req/min
getOrdersMeta(orderId)	@deprecated Use getOrdersMetaBulk()	300 req/min

Stickers (3 methods)

Method	Description	Rate Limit
createOrdersSticker(options?, data?)	Generate order stickers (SVG/PNG/ZPL)	300 req/min
createStickersCrossBorder(data?)	Get cross-border stickers (PDF)	300 req/min
createOrdersExternalSticker(data?)	@deprecated Will be removed	10 req/min

Cross-Border (2 methods)

Method	Description	Rate Limit
createStatusHistory(data?)	Get cross-border status history	300 req/min
createOrdersClient(data)	Get client info for Turkey cross-border	300 req/min

Transport Boxes - TRBX (4 methods)

Method	Description	Rate Limit
getSuppliesTrbx(supplyId)	List boxes in a supply	300 req/min
createSuppliesTrbx(supplyId, data?)	Create boxes for a supply	300 req/min
deleteSuppliesTrbx(supplyId, data?)	Delete boxes from a supply	300 req/min
createTrbxSticker(supplyId, options?, data?)	Get box stickers	300 req/min

---

Usage Examples

Getting New Orders and Checking Status

import { WildberriesSDK } from 'wb-api-sdk';

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

async function processOrders() {
  // 1. Get all new orders awaiting processing
  const { orders: newOrders } = await sdk.ordersFBS.getOrdersNew();
  console.log(`Found ${newOrders?.length ?? 0} new orders`);

  if (!newOrders?.length) return;

  // 2. Display order details
  for (const order of newOrders) {
    console.log(`Order ${order.id}:`);
    console.log(`  Article: ${order.article}`);
    console.log(`  NM ID: ${order.nmId}`);
    console.log(`  Price: ${(order.price ?? 0) / 100} RUB`);
    console.log(`  Cargo Type: ${order.cargoType}`);
    console.log(`  Required Meta: ${order.requiredMeta?.join(', ') || 'None'}`);
  }

  // 3. Check statuses for these orders
  const orderIds = newOrders.map(o => o.id!);
  const statusResponse = await sdk.ordersFBS.getOrderStatuses({ orders: orderIds });

  statusResponse.orders?.forEach(status => {
    console.log(`Order ${status.id}: ${status.supplierStatus} / ${status.wbStatus}`);
  });
}

Complete Supply Workflow

import { WildberriesSDK } from 'wb-api-sdk';
import { writeFileSync } from 'fs';

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

async function createAndProcessSupply() {
  // 1. Create a new supply
  const { id: supplyId } = await sdk.ordersFBS.createSupply({
    name: `Supply ${new Date().toISOString().split('T')[0]}`
  });
  console.log(`Created supply: ${supplyId}`);

  // 2. Get new orders
  const { orders: newOrders } = await sdk.ordersFBS.getOrdersNew();
  if (!newOrders?.length) {
    console.log('No new orders to process');
    await sdk.ordersFBS.deleteSupply(supplyId!);
    return;
  }

  // 3. Add orders to supply (changes status: new -> confirm)
  // Note: Only orders with matching cargoType can be in the same supply
  const orderIds = newOrders.slice(0, 10).map(o => o.id!);
  await sdk.ordersFBS.addOrdersToSupply(supplyId!, { orders: orderIds });
  console.log(`Added ${orderIds.length} orders to supply`);

  // 4. Generate shipping stickers (PNG format, 58x40mm)
  const stickersResponse = await sdk.ordersFBS.createOrdersSticker(
    { type: 'png', width: 58, height: 40 },
    { orders: orderIds }
  );

  // 5. Save stickers to files (base64 decoded)
  stickersResponse.stickers?.forEach(sticker => {
    const buffer = Buffer.from(sticker.file!, 'base64');
    writeFileSync(`sticker-${sticker.orderId}.png`, buffer);
    console.log(`Saved sticker for order ${sticker.orderId}`);
  });

  // 6. Deliver supply (changes status: confirm -> complete)
  await sdk.ordersFBS.updateSuppliesDeliver(supplyId!);
  console.log('Supply delivered');

  // 7. Get supply QR code (only available after delivery)
  const barcode = await sdk.ordersFBS.getSuppliesBarcode(supplyId!, { type: 'png' });
  const qrBuffer = Buffer.from(barcode.file!, 'base64');
  writeFileSync(`supply-${supplyId}.png`, qrBuffer);
  console.log(`Saved supply QR code: ${barcode.barcode}`);
}

Attaching Metadata (IMEI, SGTIN)

async function attachOrderMetadata(orderId: number) {
  // Check what metadata is required
  const metaResponse = await sdk.ordersFBS.getOrdersMetaBulk({ orders: [orderId] });
  const orderMeta = metaResponse.orders?.find(o => o.id === orderId);
  console.log('Current metadata:', orderMeta?.meta);

  // Attach IMEI for electronics
  await sdk.ordersFBS.updateMetaImei(orderId, {
    imei: '354567890123456'
  });

  // Attach SGTIN marking codes (for tracked products)
  await sdk.ordersFBS.updateMetaSgtin(orderId, {
    sgtins: ['01046009544741002']
  });

  // Set expiration date (for perishable goods)
  await sdk.ordersFBS.updateMetaExpiration(orderId, {
    expiration: '2025-12-31'
  });

  // Attach customs declaration (for cross-border)
  await sdk.ordersFBS.setCustomsDeclaration(orderId, {
    customsDeclaration: '10129050/010120/0001234'
  });

  console.log('Metadata attached successfully');
}

Managing Warehouse Passes

async function manageWarehousePasses() {
  // 1. Get list of warehouses requiring passes
  const offices = await sdk.ordersFBS.getPassesOffices();
  console.log('Available offices:', offices);

  // 2. Create a pass for a driver
  const { id: passId } = await sdk.ordersFBS.createPass({
    firstName: 'Ivan',
    lastName: 'Petrov',
    carModel: 'GAZelle Next',
    carNumber: 'A123BC77',
    officeId: offices[0]?.id ?? 1
  });
  console.log(`Created pass: ${passId}`);

  // 3. List all passes
  const passes = await sdk.ordersFBS.passes();
  passes.forEach(pass => {
    console.log(`Pass ${pass.id}: ${pass.firstName} ${pass.lastName}`);
    console.log(`  Vehicle: ${pass.carModel} (${pass.carNumber})`);
    console.log(`  Office: ${pass.officeName}`);
    console.log(`  Expires: ${pass.dateEnd}`);
  });

  // 4. Update pass if needed
  await sdk.ordersFBS.updatePass(passId!, {
    firstName: 'Ivan',
    lastName: 'Petrov',
    carModel: 'GAZelle Next',
    carNumber: 'B456DE99',  // Updated car number
    officeId: offices[0]?.id ?? 1
  });

  // 5. Delete pass when no longer needed
  // await sdk.ordersFBS.deletePass(passId!);
}

Paginated Order Retrieval

async function getAllOrdersForPeriod(startDate: Date, endDate: Date) {
  const allOrders = [];
  let nextCursor = 0;

  // Convert dates to Unix timestamps
  const dateFrom = Math.floor(startDate.getTime() / 1000);
  const dateTo = Math.floor(endDate.getTime() / 1000);

  do {
    const response = await sdk.ordersFBS.orders({
      limit: 1000,
      next: nextCursor,
      dateFrom,
      dateTo
    });

    allOrders.push(...(response.orders ?? []));
    nextCursor = response.next ?? 0;

    console.log(`Fetched ${response.orders?.length} orders, total: ${allOrders.length}`);
  } while (nextCursor > 0);

  return allOrders;
}

// Usage: Get orders from last 7 days
const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const orders = await getAllOrdersForPeriod(sevenDaysAgo, new Date());

Managing Transport Boxes (TRBX)

async function manageTransportBoxes(supplyId: string) {
  // 1. Create boxes for a supply (for PVZ deliveries)
  const { trbxIds } = await sdk.ordersFBS.createSuppliesTrbx(supplyId, { amount: 5 });
  console.log(`Created ${trbxIds?.length} boxes`);

  // 2. Get list of boxes
  const { trbxes } = await sdk.ordersFBS.getSuppliesTrbx(supplyId);
  console.log('Current boxes:', trbxes);

  // 3. Generate box stickers
  const boxStickers = await sdk.ordersFBS.createTrbxSticker(
    supplyId,
    { type: 'png' },
    { trbxIds: trbxIds ?? [] }
  );

  boxStickers.stickers?.forEach((sticker, index) => {
    const buffer = Buffer.from(sticker.file!, 'base64');
    writeFileSync(`box-${index + 1}.png`, buffer);
  });

  // 4. Delete unused boxes (only while supply is open)
  // await sdk.ordersFBS.deleteSuppliesTrbx(supplyId, { trbxIds: ['box-1'] });
}

---

Types

Key Entity Types

// Order status types
type OrderSupplierStatus = 'new' | 'confirm' | 'complete' | 'cancel';

type OrderWbStatus =
  | 'waiting'
  | 'sorted'
  | 'sold'
  | 'canceled'
  | 'canceled_by_client'
  | 'declined_by_client'
  | 'defect'
  | 'ready_for_pickup'
  | 'postponed_delivery'
  | 'accepted_by_carrier'
  | 'sent_to_carrier';

// Cargo types
type CargoType = 1 | 2 | 3;  // 1=small, 2=oversized, 3=large

// Sticker format
type StickerType = 'svg' | 'zplv' | 'zplh' | 'png';

// Order entity
interface Order {
  id?: number;
  article?: string;
  rid?: string;
  nmId?: number;
  chrtId?: number;
  price?: number;
  cargoType?: CargoType;
  createdAt?: string;
  warehouseId?: number;
  supplyId?: string;
  address?: { fullAddress?: string; longitude?: number; latitude?: number };
  // ... additional fields
}

// New order (includes required metadata)
interface OrderNew extends Order {
  requiredMeta?: string[];
  optionalMeta?: string[];
  salePrice?: number;
  finalPrice?: number;
}

// Supply entity
interface Supply {
  id?: string;
  name?: string;
  done?: boolean;
  createdAt?: string;
  closedAt?: string;
  cargoType?: 0 | 1 | 2 | 3;
  crossBorderType?: 0 | 1 | null;
}

// Order metadata
interface Meta {
  imei?: { value?: string };
  uin?: { value?: string };
  gtin?: { value?: string };
  sgtin?: { value?: string[] };
  expiration?: { value?: string };
  customsDeclaration?: { value?: string };
}

// Seller pass
interface Pass {
  id?: number;
  firstName?: string;
  lastName?: string;
  carModel?: string;
  carNumber?: string;
  officeId?: number;
  officeName?: string;
  officeAddress?: string;
  dateEnd?: string;
}

Request/Response Types

// Pagination parameters
interface GetOrdersParams {
  limit: number;      // 1-1000
  next: number;       // Pagination cursor, 0 for first page
  dateFrom?: number;  // Unix timestamp
  dateTo?: number;    // Unix timestamp
}

// Order status request
interface OrderStatusRequest {
  orders: number[];   // 1-1000 order IDs
}

// Sticker options
interface StickerParams {
  type: StickerType;
  width: 58 | 40;
  height: 40 | 30;
}

// Bulk metadata request
interface GetMetaMultiRequest {
  orders: number[];   // Max 100 order IDs
}

// Add orders to supply request
interface AddOrdersToSupplyRequest {
  orders: number[];
}

---

Error Handling

Common Errors

HTTP Code	Error Type	Description	Resolution
400	ValidationError	Invalid request parameters	Check parameter values and constraints
401/403	AuthenticationError	Invalid or missing API key	Verify API key and permissions
404	NotFoundError	Resource not found	Verify order/supply ID exists
409	ConflictError	Operation conflict	Check status requirements (see below)
429	RateLimitError	Rate limit exceeded	Wait and retry (see rate limits)

409 Conflict Scenarios

Scenario	Cause	Resolution
Cargo type mismatch	Adding order with different cargoType to supply	Create separate supply for different cargo types
Warehouse mismatch	Adding order from different warehouse	Group orders by warehouse
Supply has orders	Attempting to delete non-empty supply	Remove all orders first
UIN not filled	Delivering supply with missing required metadata	Attach all required metadata
Invalid status transition	Canceling a completed order	Check order status before operation
Supply not delivered	Requesting QR code before delivery	Call updateSuppliesDeliver() first

Error Handling Example

import {
  WBAPIError,
  RateLimitError,
  ValidationError
} from 'wb-api-sdk';

try {
  await sdk.ordersFBS.addOrdersToSupply(supplyId, { orders: orderIds });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
    await sleep(error.retryAfter);
    // Retry the request
  } else if (error instanceof ValidationError) {
    console.log('Validation error:', error.message);
    // Check parameters
  } else if (error instanceof WBAPIError && error.statusCode === 409) {
    console.log('Conflict:', error.message);
    // Possible cargo type mismatch
  } else {
    throw error;
  }
}

---

Rate Limits

Rate Limit Tiers

Tier	Limit	Interval	Burst	Endpoints
Standard FBS	300/min	200ms	20	Most FBS endpoints (28 methods)
Cancel Order	100/min	600ms	20	updateOrdersCancel
Meta Attachment	1000/min	60ms	20	Metadata PUT methods (SGTIN, UIN, IMEI, etc.)
Create Pass	1/10min	-	1	createPass

409 Error Penalty

Important: When an operation returns a 409 (Conflict) error, it counts as 10 requests against your rate limit quota instead of 1. This applies to all supply operations.

Rate Limit Handling

import { RateLimiter } from 'wb-api-sdk';

// The SDK handles rate limiting automatically
// But you can implement additional backoff for bulk operations

async function processOrdersBatched(orderIds: number[]) {
  const batchSize = 100;

  for (let i = 0; i < orderIds.length; i += batchSize) {
    const batch = orderIds.slice(i, i + batchSize);

    try {
      await sdk.ordersFBS.getOrderStatuses({ orders: batch });
    } catch (error) {
      if (error instanceof RateLimitError) {
        await sleep(error.retryAfter);
        i -= batchSize; // Retry this batch
      }
    }

    // Optional: add delay between batches to avoid rate limits
    await sleep(250);
  }
}

---

Deprecated Methods

The following methods are deprecated and will be removed in future versions:

Method	Replacement	Reason
createOrdersStatu(data)	getOrderStatuses(data)	Incorrect method name (typo)
getOrdersMeta(orderId)	getOrdersMetaBulk(data)	Single-order endpoint removed; use bulk
updateSuppliesOrder(supplyId, orderId)	addOrdersToSupply(supplyId, data)	Single-order endpoint removed; use bulk
getSuppliesOrder(supplyId)	getSupplyOrderIds(supplyId)	Endpoint changed; returns IDs only
createOrdersExternalSticker(data)	createStickersCrossBorder(data)	Endpoint removed by Wildberries

Migration Examples

// createOrdersStatu() → getOrderStatuses()
// BEFORE (deprecated)
const statuses = await sdk.ordersFBS.createOrdersStatu({ orders: [123, 456] });

// AFTER (recommended)
const statuses = await sdk.ordersFBS.getOrderStatuses({ orders: [123, 456] });

// createOrdersExternalSticker() → Note: endpoint removed by Wildberries
// This method now throws - use createStickersCrossBorder() for cross-border orders
// BEFORE (deprecated - no longer works)
const stickers = await sdk.ordersFBS.createOrdersExternalSticker({ orders: [123] });

// AFTER (recommended for cross-border)
const stickers = await sdk.ordersFBS.createStickersCrossBorder({ orders: [123] });

// getOrdersMeta() → getOrdersMetaBulk()
// BEFORE (deprecated)
const meta = await sdk.ordersFBS.getOrdersMeta(orderId);

// AFTER (recommended)
const metaResponse = await sdk.ordersFBS.getOrdersMetaBulk({ orders: [orderId] });
const meta = metaResponse.orders?.find(o => o.id === orderId)?.meta;

// updateSuppliesOrder() → addOrdersToSupply()
// BEFORE (deprecated)
await sdk.ordersFBS.updateSuppliesOrder(supplyId, orderId);

// AFTER (recommended - bulk)
await sdk.ordersFBS.addOrdersToSupply(supplyId, { orders: [orderId] });

// getSuppliesOrder() → getSupplyOrderIds()
// BEFORE (deprecated)
const { orders } = await sdk.ordersFBS.getSuppliesOrder(supplyId);

// AFTER (recommended - returns IDs only)
const { orderIds } = await sdk.ordersFBS.getSupplyOrderIds(supplyId);
// Then fetch full order details if needed
const statuses = await sdk.ordersFBS.getOrderStatuses({ orders: orderIds ?? [] });

---

Supply Workflow

Status Transitions

Order Status Flow:
┌─────────┐      addOrdersToSupply()     ┌─────────┐      deliverSupply()      ┌──────────┐
│   new   │ ───────────────────────────> │ confirm │ ────────────────────────> │ complete │
└─────────┘                              └─────────┘                           └──────────┘
     │                                        │
     │ updateOrdersCancel()                   │ updateOrdersCancel()
     v                                        v
┌─────────┐                              ┌─────────┐
│ cancel  │ <──────────────────────────  │ cancel  │
└─────────┘                              └─────────┘

Cargo Type Constraints

A supply can only contain orders of the same cargo type:

• Type 1: Small goods (MGT)
• Type 2: Oversized goods (SGT)
• Type 3: Large goods (KGT+)

The first order added to an empty supply determines its cargo type. Subsequent orders must match.

Complete Workflow Checklist

1. Create supply - createSupply({ name: '...' })
2. Get new orders - getOrdersNew()
3. Group by cargo type - Filter orders by cargoType
4. Add orders to supply - addOrdersToSupply(supplyId, { orders: [...] })
5. Attach required metadata - Check requiredMeta field
6. Generate stickers - createOrdersSticker(options, { orders: [...] })
7. Print and attach stickers to packages
8. Deliver supply - updateSuppliesDeliver(supplyId)
9. Get QR code - getSuppliesBarcode(supplyId, { type: 'png' })
10. Print QR code for warehouse scanning

---

Related Resources

EPICs

• EPIC 22: Orders FBS URL Fixes - Critical URL and endpoint fixes
• EPIC 23: Orders FBS Type Safety - Type improvements and naming cleanup
• EPIC 24: Orders FBS Rate Limits - Rate limit configuration audit
• EPIC 25: Orders FBS Testing - Test coverage improvements

User Stories

• Story 2.5: Order Retrieval and Status
• Story 2.6: Shipping and Supply Management

API Documentation

• Wildberries FBS API Reference
• Wildberries FBS Supplies
• Wildberries FBS Metadata

---

Changelog

Version	Date	Changes
2.8.0	2026-02	Fixed broken endpoints (EPIC 22), added bulk methods
2.7.0	2026-01	Added getOrdersMetaBulk, addOrdersToSupply, getSupplyOrderIds
2.0.0	2025-10	Initial Orders FBS module with 34 methods