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

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, cancelled
• pending_payment → paid, payment_failed, cod_pending, expired, cancelled
• cod_pending → paid, cancelled
• payment_failed → pending_payment, cancelled
• paid → 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

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:

1. 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.
2. 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.
3. Cash collected on delivery. The carrier reports the package delivered, which is what “the buyer paid” means for cash on delivery.

Note

This is why Commerce sometimes lags a buyer’s own sense of having paid. The buyer knows; Commerce waits until it can prove it. That gap is the point — it’s what stops an unpaid order from shipping.

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

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

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

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

Several ways to get paid can be configured at once. Commerce picks the first one that is actually usable, in this order:

1. Your own Wompi account, connected through Connect.
2. Destesi’s payment account, if your workspace has been granted that fallback.
3. Bank transfer — including a Bre-B QR carrying your llave.
4. Cash on delivery.
5. 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 your catalog comes from

Every product comes from Inventory. Inventory owns what a product IS — its name, description, photos, variants and stock — and Commerce keeps only what makes it sellable: price, publication, category and parcel. There is no second, local catalog: an empty Inventory means nothing to sell.

Created in Inventory is the ordinary path.

Imported from a linked Shopify store is the other. You connect the store once in Connect, then link it here — connecting is not linking, and Commerce never adopts a store on its own. The import creates the products in Inventory. A catalog follows exactly one store.

Once a store is linked:

• Preview first. The preview reads the store and reports what an import would do without writing anything: how many products and variants it saw, how many it can bring, and which ones it would skip and why. A product with no photo is skipped — Commerce never creates a product without one — and so is a product whose variants carry different prices, because Commerce prices per product and undercharging a buyer is worse than a missing row.
• The import needs a default parcel. Shopify has no package dimensions, and a product cannot be quoted for shipping without them. You give the typical parcel once; it fills every imported product and can be corrected per product afterwards.
• Running it again is how you sync. Products are matched by their Shopify id, so a second import updates what it created and never duplicates it. Photos are re-hosted in Drive — the first is the cover, the rest the gallery.
• A big store answers in slices. The import replies with what it did and a cursor to continue from; the web keeps calling until it is done. Every call is idempotent, so a repeated one costs nothing but time.

Note

While a store is linked it owns the name, description, price, stock, status, photos and variants of the products it brought — those are read-only here, and editing one is refused with 422 field_managed_by_source. Everything else Commerce keeps on the product is yours: the section, the audience, the spec sheet, the video and the parcel.

Unlinking is not disconnecting. Stop following the store and imports stop: every imported product stays in Inventory, and the connection itself stays in Connect. That is the point — the import is a way to bring your store in, not a mirror you are tied to.

Two more things the store answers while it is linked: what one product looks like right now over there (price per size, stock per location, every photo — read live, never copied), and what it has been selling. A merchant who just arrived has no orders in Commerce and years of them in Shopify, so “no data” would be a lie.

How a shipment is sized

Every carrier quote and every shipping label is priced on one parcel, and Commerce derives it the same way everywhere (Settings → Shipping & carriers → Parcel):

• A product with no measurements of its own counts as the typical item — 3×3×3 cm and 3 g unless you change it. A catalog that comes from Inventory carries no dimensions, so this is what makes its orders quotable at all. Set it to 0 and an unmeasured order refuses to quote instead.
• No parcel goes out smaller than the minimum box — 10×10×10 cm and 1 kg unless you change it. Items stack up to the box’s height and every started box counts whole, in one taller parcel: one to three typical items quote as 10×10×10 cm and 1 kg, four to six as 10×10×20 cm and 2 kg. A product wider than the box keeps its own size and is only raised to the box weight. A 0 in any box field turns it off.

The rule is the same on the web, in the assistant (set_shipping_settings), over MCP (commerce_set_shipping_settings) and in dst commerce.

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.

Related

Quickstart

Reference — API, states, and limits

Troubleshooting

Connect