Skip to content
platform
EN PT

Use cases

Complex retail and B2B2C: the typical path through the API

Scenario

A chain sells to businesses and to end consumers at the same time, with stores in several regions, a counter, field sales reps and local inventory. From the outside it looks like retail; inside there are customer groups, invoiced credit and prices that change by region.

The unit that organizes the integration is the warehouse. The same product can have a different price and quantity in each warehouse, shipping starts from the address of the origin warehouse, and each warehouse decides who sees its products.

The channels coexist instead of competing. The counter and the field sales rep serve inside the portal, on the customer's terms, and a sale made outside the platform can generate cashback for use in the digital channel, which brings the counter customer to the company's own portal.

The pains that lead to this integration

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.

I use four or five systems for a single complex sale

How it shows up

"To close a complex order I open five systems."

Why it happens

The operation is fragmented across ERP, catalog, portal, credit and tax, with no unified orchestration.

We simplified pricing because the system cannot handle it

How it shows up

"We flattened the price list because keeping a different price per branch and per customer became impossible to manage."

Why it happens

The source system cannot sustain price by warehouse crossed with the price of each customer, each category and each condition, and the company flattens the policy to be able to manage it.

What is usually integrated

EntityDirectionTypical frequencyEndpoints and events
Inventory and price by store and warehouse The warehouse is created before price and quantity, and each product and warehouse pair has its own stock record. Your system to CWS Platform Continuous, in small batches
Customers and customer groups The group is what separates the reseller from the end consumer in the same portal: price rules and payment terms use the group as a criterion. Both directions Initial load and on every registration change
Price rules by group and by region A rule can be eligible by customer type, by ICMS taxpayer status and by the pair of warehouse state and recipient state. Your system to CWS Platform When commercial policy changes
Business customer credit limit The credit limit can be combined with card or with bank slip in the same order. Your system to CWS Platform On every financial event that changes the limit
Counter and field sales reps Your system to CWS Platform When the team or the portfolio changes
Cashback from sales made outside the platform Your system reports who bought, the order number and the items; the program calculates how much each item earns. The release date is programmable, and the credit can be canceled while it has not been released. Depends on activation. Your system to CWS Platform On every counter sale that generates cashback
Orders CWS Platform to your system Per event (webhook) or by periodic polling
Status, invoice and tracking The platform does not issue the invoice: it receives the data and the XML of the invoice already issued. The status flow is one-way. Your system to CWS Platform On every order stage change
Store pickup, shipping and pay at the register Each pickup address is linked to the warehouses that supply it, and shipping tables are per carrier and warehouse. The knowledge base also describes managing pay at the register through the API: this is not in the public collection. Configured in the panel At rollout and when the operation 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 inventory and price by warehouse

    Your system sends each warehouse's inventory and price, in batches of 1 to 50 items. When a head office integrates on behalf of the stores, the store goes in the path.

  3. 3

    Load customers and groups

    Your system creates the customers, creates the groups that separate the audiences and links each customer to their group.

  4. 4

    Publish the price rules

    Price rules are sent with the criteria for each audience and each region. Among non-cumulative rules the highest-priority one applies, and cumulative rules are applied on top of the result.

  5. 5

    Report the business customer's credit

    Your system reports the credit limit of whoever buys on invoice. An order with enough balance is approved automatically.

  6. 6

    Register the sales reps

    Your system registers the counter and field sales reps and links each one's customers. When serving, the customer's addresses, credit limit, contract prices and price rules apply.

  7. 7

    Receive the order and report progress

    An order with items from different stores or warehouses splits into one order per store and per warehouse, each with its own shipping and invoice. The platform notifies by webhook, and your system reports the status of each one.

  8. 8

    Record the sale made outside the platform

    When the cashback program is active, your system reports the counter sale and the program records the customer's credit, for use on the portal. If the sale is undone, your system cancels the grant while it has not been released.

Variations

Regional price, inventory from elsewhere

The platform can charge the price of the store closest to the delivery address even when the order ships from a distribution center, with recalculation and an alert when the customer changes the address. It is configuration, with no API route.

One store or one warehouse per order

Depends on activation

The store can restrict each order to a single warehouse or a single store, for cases where credit and invoicing must go out on one invoice. With the restriction, the integration receives a single order.

Pay at the register

Depends on activation

When paying at the register the customer splits the amount across several methods and terms. The order is created with its own initial status for in-store payment, generated by the platform, and payment approval is done by the store.

Head office with stores

When a head office integrates on behalf of the stores, each store's contracts have their own routes, with the store in the path. Customer groups created at the head office can be used by the branches in their rules.

Third-party marketplaces as a channel

Depends on activation

The store can generate a catalog feed for marketplaces and other third-party channels, and use them as a demand channel. This is not in the public collection.

Taxes calculated in the ERP

Depends on activation

When the tax rule lives in the ERP, the platform calls the ERP's tax endpoint before closing the order and uses the returned values, per item. It is a synchronous call, and its response time becomes part of the cart's time.

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.