Skip to content
platform
EN PT

Use cases

B2B marketplace: the typical path through the API

Scenario

An operator brings several stores together in the same portal: its own branches, franchises or invited sellers. Each store sells with its own inventory, price, shipping and payment, within the general criteria set by the portal owner.

A marketplace is usually the consequence of digitizing an operation that already exists. The stores and the inventories are already there, and it is each store's integration that puts them in the channel. That is why the quality of the data each store sends (inventory, price and order progress) is one of the conditions the operation depends on.

The API has two roles. The store integrates what is its own: it sends inventory and price and fulfills the orders in which it is the supplier. The order's store of origin, which in a marketplace is the operator, queries the orders that originated in it through its own routes. The customer order splits into one order per store, and also per warehouse of the same store.

The pains that lead to this integration

I lose sales for lack of assortment and cannot expand without buying inventory

How it shows up

"The customer asks, we do not have it, and they buy from a competitor. The item exists at my supplier, but I have no way to sell it."

Why it happens

The portal and the ERP assume you only sell what is in your own inventory. Selling third-party inventory requires the partner to configure price, shipping and availability within the company's rules, and the layer that allows this without giving up governance is missing.

Each customer's negotiated price does not fit in the portal

How it shows up

"Every customer has their own price, and nobody can get that onto the site."

Why it happens

A B2B transaction moves five variables at once (price, delivery, payment, quantity and composition), and ecommerce platforms treat them as static form fields.

The portal shows inventory and prices that differ from the ERP

How it shows up

"The portal shows inventory that no longer exists."

Why it happens

The ERP works in processing windows, and the truth of the system of record does not reach the sales channel at the pace the customer buys.

The same product shows three different prices across channels

How it shows up

"The same product shows three different prices: on my portal, in my direct sales and on the marketplace."

Why it happens

Several channels (manufacturer, distributor, sales rep, store, marketplace and direct sales) compete for the same customer and the same product without price and commission governance.

What is usually integrated

EntityDirectionTypical frequencyEndpoints and events
Each store's inventory and price The same store can sell the same product from different warehouses, with different price and quantity, and shipping is calculated from the address of the origin warehouse. Your system to CWS Platform Continuous, in small batches
Customers The marketplace can hide the customer's email and phone from sellers; in that case the API returns the data masked. Depends on activation. Both directions Initial load and on every registration change
Contracts and price rules per store A contract can be limited by marketplace, by destination state and by branches. Your system to CWS Platform Per contract term and when policy changes
Credit limit The limit can apply per store or to the whole head office. In the second case the customer uses the limit at any branch, and each store receives its debit separately for reconciliation. Your system to CWS Platform On every financial event that changes the limit
Supplier store orders CWS Platform to your system Per event (webhook) or by periodic polling
Status, invoice and item tracking Each store order has its own products, amount, shipping, preparation time and invoice. Your system to CWS Platform On every order stage change
Orders originated in the marketplace This is the view of the store of origin: the orders its customers placed, including those fulfilled by other stores. CWS Platform to your system By periodic polling
Cashback balance The cashback program depends on activation. The routes return the consolidated balance, the balance per customer and one customer's statement. CWS Platform to your system By query, for reconciliation
Commission and payment split Each store's contract sets the marketplace percentage per sales scenario, and the order amount is split by store. This is not in the public collection. Configured in the panel In each store's contract with the marketplace
Each store's products and shipping Each store maintains its own products and its own shipping tables in the panel. The knowledge base also describes product creation through the API: this is not in the public collection. Configured in the panel When the store joins and when the assortment changes

Typical flow

  1. 1

    Authenticate

    The integrator gets the access token with the store's integration user and sends it as Bearer on every other call. The token lasts 12 hours; when it expires the response is 401 and you simply authenticate again.

  2. 2

    Send each store's inventory and price

    Each store sends its own inventory and price, by warehouse, in batches of 1 to 50 items. A head office can send on behalf of the branches linked to it, with the branch in the path.

  3. 3

    Publish each store's commercial terms

    Contracts and price rules are sent per store. The contract fixes the item price for the linked customers and can be limited by marketplace, by destination state and by branches.

  4. 4

    Receive each store's order

    Items from different stores sit in the same cart, each store with its own shipping options. Once the purchase is closed, the customer order splits into one order per store, and the platform notifies each store by webhook. The store fetches the detail of the order in which it is the supplier.

  5. 5

    Report progress per store

    The supplier store moves its own order: ready to ship, shipped with tracking, and the invoice already issued. Each store order has its own invoice.

  6. 6

    Follow the whole

    The operator lists the orders originated in the marketplace and, from the customer order, sees the store orders it was split into.

  7. 7

    Reconcile

    Periodic polling of the listing by update date checks that each store has everything the platform generated, and recovers what the webhook did not deliver.

Variations

The store of origin moves the order

Depends on activation

The collection has routes for the store of origin to update the status, attach the invoice and report item tracking for an order that originated in it. Updates by the store of origin depend on a setting of the store itself, enabled by CWS Platform; without it the response is 422.

Cancellation by the supplier store

When the order originated in another store, cancellation by the supplier depends on the store of origin having enabled that permission. Until it does, the cancellation returns 422, and the store of origin is the one that cancels.

The same product in several stores

Depends on activation

When several stores sell the same product, the page shows a main offer and the other offers. The main offer goes to the lowest price or to the store closest to the customer, according to the marketplace configuration. Nothing changes for the integration: each store keeps sending its own inventory and price.

Head office with branches

When the marketplace is a head office with branches, each branch's contracts have their own routes, with the branch in the path. The branch must be linked to the token's head office; without the link the response is 403.

Quote answered by the store

Depends on activation

With quoting active in the marketplace, each store lists the pending requests for the products it sells and answers with price and lead time, or declines. A decline cannot be undone.

No webhook, polling only

A store that does not yet have an endpoint to receive webhooks integrates orders by polling only: list orders by status and by update date and fetch the detail of each one.

Range of possibilities

This is a common path, not the only one.

CWS Platform reaches the same goal through configuration, through the API or through a combination of the two, and the best approach depends on your operation, your ERP and your rules. Talk to a CWS Platform architect to design the integration for your case.

Talk to an architect

Platform modules involved

Generated from the public API collection, published on 2026-09-04: api-docs.cws.digital.