Integrate Your Online Store with Wildberries via API

You launch sales on Wildberries and face an unstable API. Documentation becomes outdated, methods change without warning. Each failure takes an average of 2 hours to debug. An error in nmID mapping leads to duplicate cards. Statistics show that 60% of integration failures are due to incorrect authentication or outdated documentation. According to the marketplace, 80% of sellers encounter problems in the first month.

We have been integrating with marketplaces for 5 years and have developed an approach that minimizes risks across 20+ projects. Instead of rewriting code for new API versions, we created an adaptive layer. It automatically handles changes, reducing errors by 3 times compared to direct API calls. We guarantee stable operation after launch.

How We Bypass Wildberries API Instability

The adaptive integration layer intercepts responses, checks the structure, and transforms data if necessary. If Wildberries changes the field nmID to nmId, the integration does not break—it adapts. This reduces maintenance costs by up to 30%.

Authentication requires tokens issued in the personal account. Different domains need separate tokens: main (content, prices), statistics (statistics), marketplace (marketplace). Example client class:

class WildberriesClient
{
    private string $apiToken;
    private string $statsToken;

    public function request(string $method, string $url, array $data = []): array
    {
        return Http::withHeaders([
            'Authorization' => $this->apiToken,
            'Content-Type'  => 'application/json',
        ])->{strtolower($method)}($url, $data)->json();
    }
}

Why Correct nmID Mapping Matters

Wildberries uses an internal numeric identifier nmID for each product. It differs from vendorCode (SKU). Mapping errors lead to duplicate cards or inability to update. We automatically match nmID with your SKUs during the first upload. For example, for SKU SKU-123, the system remembers nmID 456789 and uses it in subsequent requests. This reduces debugging time by an average of 2 hours per error.

How Integration Is Configured: Step-by-Step Plan

1. Audit of your current accounting system—determine data for synchronization.
2. Token and access rights configuration—obtain keys for each API domain.
3. Development of nmID mapping module—link SKUs with internal Wildberries IDs.
4. Implementation of product, price, stock, and order loading—write code with adaptive layer.
5. Testing and launch—verify synchronization, train your manager. After launch, one month of free support.

What Is Included in the Work

• Integration documentation: description of all endpoints and mappings.
• Access rights and token setup for all API domains.
• Implementation of adaptive layer to handle API changes.
• Training your manager to work with synchronization.
• One month of free support after launch.
• Stable operation guarantee: if something breaks, we fix it within a day.

Wildberries API Domain Comparison

Typical Errors and Their Solutions

Product Upload: How to Avoid Errors

Product cards have a specific structure: subjects (subjectID), characteristics, sizes. We automatically select subjectID by category. Example upload code:

public function createCard(Product $product): void
{
    $payload = [[
        'subjectID'   => $this->getSubjectId($product->category),
        'variants'    => [[
            'vendorCode' => $product->sku,
            'title'      => $product->name,
            'description'=> $product->description,
            'brand'      => $product->brand,
            'dimensions' => [
                'length' => $product->length_cm,
                'width'  => $product->width_cm,
                'height' => $product->height_cm,
                'isValid'=> true,
            ],
            'characteristics' => $this->mapCharacteristics($product),
        ]],
    ]];

    $this->request('POST', 'https://content-api.wildberries.ru/content/v2/cards/upload', $payload);
}

Updating Prices and Stocks

How to Quickly Update Prices and Discounts?

WB separates base price and discount. An error in one request can block all updates. We use batch processing with retries:

public function setPriceAndDiscount(string $sku, int $basePrice, int $discountPercent): void
{
    $this->request('POST', 'https://discounts-prices-api.wildberries.ru/api/v2/upload/task', [
        'data' => [[
            'nmID'  => $this->getNmId($sku),
            'price' => $basePrice,
        ]]
    ]);

    $this->request('POST', 'https://discounts-prices-api.wildberries.ru/api/v2/upload/task', [
        'data' => [[
            'nm'       => $this->getNmId($sku),
            'discount' => $discountPercent,
        ]]
    ]);
}

Updating Stocks (FBS)

public function updateStocks(array $items): void
{
    $this->request('PUT', 'https://marketplace-api.wildberries.ru/api/v3/stocks/{warehouseId}', [
        'stocks' => array_map(fn($item) => [
            'sku'    => $item['sku'],
            'amount' => $item['amount'],
        ], $items)
    ]);
}

Retrieving FBS Orders

public function getOrders(string $since): array
{
    return $this->request('GET', 'https://marketplace-api.wildberries.ru/api/v3/orders', [
        'limit'     => 1000,
        'next'      => 0,
        'dateFrom'  => strtotime($since),
    ])['orders'] ?? [];
}

Results and Timelines

Integration with Wildberries (products + prices + stocks + orders) takes 14–20 business days. Thanks to the adaptive layer, you save up to 40% of time on order processing compared to manual management. In 95% of cases, integration is completed on time. Contact us for a consultation—we will assess the scope of work and offer the optimal solution. Order integration and get stable synchronization with a post-launch performance guarantee.

How to Avoid Discrepancies in Commission Calculations

Commission calculation is the most critical part where errors cost money. Rule one: never store commission as a derived value, always as a fact. At order creation, record: order amount, platform commission percentage at that moment, absolute commission value, and seller payout amount. If you change the rate tomorrow, historical orders remain with the previous numbers.

Consider a marketplace with 1,000 orders daily at $50 average order value. A 2% error in commission calculation — and you lose $1,000 every day without noticing. Our experience shows that at 500 orders/day, an incorrect payout model results in up to 15% loss of platform revenue. We have solved this for 50+ projects, from niche B2B to horizontal retail. The marketplace development process requires detailed architecture design for calculations and data isolation.

Commission Models (we use one of or combine)

We use Stripe Connect as the baseline standard. Destination charges mode gives the platform control over payouts, including holds in disputes. Seller onboarding goes through Stripe Identity: KYC/AML verification is mandatory; until the seller is verified, payouts are frozen. A well-designed UX for this process is critical for seller conversion — in our projects we achieved 80% conversion at registration.

What commission model suits your marketplace?

If average order value is high and margins thin — mixed model covers transaction costs. For B2B with volume discounts — tiered works best. Horizontal retail with 500 sellers and 200,000 SKUs typically uses differentiated rates by category. The wrong model can cost 3–5% of GMV, which directly hits your bottom line.

Why Multitenancy Architecture Is Critical for Data Isolation

The first step is choosing a multitenancy architecture. In shared-schema mode, all sellers are in the same tables with vendor_id. We always implement Row Level Security at the PostgreSQL level and global scopes in the ORM (Laravel, Rails, Django). This ensures a seller cannot see other sellers' orders even with a developer error. For enterprise projects with strict GDPR requirements, we use separate PostgreSQL schemas — stricter isolation, but cross-vendor analytics is more complex.

How to Handle Inventory Without Race Conditions

Two buyers simultaneously add the last item to their cart. Who gets it? Use optimistic locking when creating the order:

UPDATE inventory 
SET reserved = reserved + 1 
WHERE product_id = ? AND (quantity - reserved) >= 1

Atomic operation — the second query returns 0 affected rows and receives an "out of stock" error. Typical schema for high-traffic marketplaces. Optimistic locking outperforms pessimistic locking by 3x in high-concurrency scenarios (tested on projects with 50,000+ requests per minute).

Comparison of Catalog Approaches

For a niche B2B marketplace, we often choose per-vendor — faster launch. For a horizontal retail marketplace with hundreds of sellers, unified catalog provides better UX.

Moderation Pipeline: Automated and Manual Verification

A marketplace is responsible for seller content. Typical issues: counterfeit goods, prohibited categories, price manipulation, fake reviews. We build a three-tier pipeline:

1. Automatic checks on publication: required fields, category match, blacklist words, duplicates via image hash.
2. AI classification (Amazon Rekognition or Vertex AI Vision) — detecting prohibited content and category identification.
3. Manual review queue for flagged items.

State machine: draft → pending_review → active / rejected → suspended. Each transition is an event with reason and moderator. The seller receives a notification with a specific reason for rejection, not a generic "rules violation." Review verification is mandatory — only after confirmed purchase. Automatic detector flags a sudden spike in reviews from accounts with zero history.

Search and Recommendations

Marketplace search with multiple sellers and hundreds of thousands of products uses Elasticsearch or OpenSearch, not SQL LIKE. Vector search for semantics, faceted filtering via aggregations. Personalized feed based on collaborative filtering. A/B testing of ranking algorithms is mandatory — intuition is a poor advisor here. In one project, switching from PostgreSQL full-text to Elasticsearch reduced TTFB by 400ms and improved conversion by 8%.

Marketplace Development Process

Marketplace development is iterative. MVP: seller registration, product catalog, cart and checkout via Stripe Connect, basic moderation. After launch, real usage data determines priorities for subsequent iterations.

Typical order:

• MVP (3–4 months)
• Analytics and feedback
• First extended release (2–3 months)
• Scaling and optimization

Timeline and Budget

• Marketplace MVP (catalog, checkout, basic seller profiles): 3–5 months.
• Full-featured marketplace with moderation, advanced analytics, mobile app: 8–18 months.
• Adding marketplace functionality to an existing e-commerce: 2–5 months.

Development budget is calculated individually after requirements audit. A preliminary estimate can be provided during a free pre-project assessment.

What's Included

• Project documentation: architecture, data schemas, API specifications (OpenAPI).
• Access to repository, CI/CD, deployment documentation.
• Training for the client's team on platform operation.
• Technical support for the first month after launch.

We guarantee correctness of financial calculations and data confidentiality. Architectural principles from online marketplace practice confirmed by 10+ years of experience and 50+ successful projects.

Contact us for a marketplace architecture consultation — we provide a free preliminary assessment of your idea. Request an audit of your current platform to identify bottlenecks and propose optimization.