Commerce concepts
Commerce is small on purpose. Almost everything it does hangs off four ideas: an order has a lifecycle, payment is a fact you have to prove, stock is defended by reservations, and two different agents talk to two different audiences.
The order lifecycle
Section titled “The order lifecycle”An order is always in exactly one state, and it can only move along paths the system allows. An order that skipped a step is not a bug you can talk it out of — the move is refused.
| State | Meaning |
|---|---|
| draft | Being assembled. Stock is already reserved. |
| pending_payment | The buyer has been asked to pay. |
| cod_pending | Going out for cash on delivery; the carrier collects. |
| paid | Payment is proven. |
| payment_failed | An attempt failed. The buyer can try again. |
| fulfilled | Delivered. Terminal. |
| cancelled | Called off. Terminal. |
| expired | The reservation ran out before payment arrived. Terminal. |
The legal moves:
draft→pending_payment,cancelledpending_payment→paid,payment_failed,cod_pending,expired,cancelledcod_pending→paid,cancelledpayment_failed→pending_payment,cancelledpaid→fulfilled
fulfilled, cancelled, and expired are ends of the line. Anything not in that list is rejected, and the check is enforced at the database — two people acting on the same order at the same moment cannot both win.
Paid is evidence, not a redirect
Section titled “Paid is evidence, not a redirect”A buyer arriving on a success page proves nothing: they can land there by pressing back, by sharing a link, or by never paying at all. Commerce moves an order to paid through exactly three doors, all of them evidence:
- A verified payment webhook. Wompi tells Commerce directly, and the message is checked against a signature before it is believed. Duplicate deliveries are harmless — the same event applied twice changes nothing.
- A confirmed bank transfer. Either Commerce matched a deposit notification in your connected Gmail to the order, or you confirmed it yourself when it asked you on WhatsApp.
- Cash collected on delivery. The carrier reports the package delivered, which is what “the buyer paid” means for cash on delivery.
Stock is defended by reservations
Section titled “Stock is defended by reservations”Creating an order reserves its units in the same instant, in one atomic step: either the stock was there and it is now held, or the order is refused for insufficient stock and nothing changed. There is no window in which two orders can both take the last unit.
A reservation is a hold, not a sale. It expires — 30 minutes by default — and when it does, the units return to available stock and the unpaid order is expired. Draft, pending-payment, and payment-failed orders all still hold their stock; paid, cancelled, and expired ones don’t.
Because reservations expire on their own, you never have to reconcile stock by hand after an abandoned checkout.
Two agents, two audiences
Section titled “Two agents, two audiences”Commerce runs two agents that never share a conversation, a memory, or a toolset.
| Sales agent | Operator chat | |
|---|---|---|
| Talks to | Your buyers, on WhatsApp | You, in the app |
| Can | Show the catalog, answer product questions, check stock, build an order, send a payment link | Run the business — products, stock, orders, campaigns, shipping, messaging |
| Cannot | Change your catalog, spend money, see other conversations | — but seven money-spending tools stop and ask you first |
| Hands off when | It shouldn’t be deciding, or your monthly allowance is spent | Never; it works alongside you |
Keeping them separate is what makes the buyer-facing agent safe to point at strangers: it has no tool that can alter your business, only tools that read it and assemble an order.
The approval gate follows the money
Section titled “The approval gate follows the money”The operator agent asks permission for exactly seven actions: activating a campaign, changing a campaign budget, publishing a campaign, creating a payment link, buying a shipping label, sending a WhatsApp message, and topping up your ads wallet.
Everything else — editing a product, adjusting stock, looking things up, drafting — runs uninterrupted. Gating routine work would train you to click approve without reading, which is exactly what you must not do on the seven that matter.
Buyers are not users
Section titled “Buyers are not users”A buyer is a channel plus an identifier — a WhatsApp number, an Instagram handle — and nothing more. They never create a Destesi account, never sign in, and never belong to your workspace. Checkout and dispatch links carry their own opaque codes instead.
This keeps the workspace model intact: workspace members are your team, and everything Commerce stores is scoped to the workspace, so a link or an id from someone else’s workspace simply doesn’t resolve.
How payment settlement is chosen
Section titled “How payment settlement is chosen”Several ways to get paid can be configured at once. Commerce picks the first one that is actually usable, in this order:
- Your own Wompi account, connected through Connect.
- Destesi’s payment account, if your workspace has been granted that fallback.
- Bank transfer — including a Bre-B QR carrying your llave.
- Cash on delivery.
- Disabled — nothing is configured, and payment links are refused.
Bre-B is not a separate payment method. It is a nicer way to hand over your bank details for a transfer: the buyer scans instead of typing.
Where Commerce meets the rest of the suite
Section titled “Where Commerce meets the rest of the suite”- Connect holds every third-party credential Commerce uses — WhatsApp, Meta Ads, the carrier, Gmail, your payment provider. Commerce never stores a provider token of its own.
- Drive stores what you upload into a conversation with the operator agent.
- Chat is the general-purpose agent; Commerce’s operator chat is the one that knows your catalog and your orders.