Commerce MCP tools

Registered when the server starts with COMMERCE_API_URL set. 159 tools, listed with the description the server sends in tools/list.

Tool	Description
commerce_activate_campaign	Start DELIVERY of a published (paused) campaign — this is the moment real ad spend begins. HARD RULES: ask the merchant the exact amount and whether it is per day or a total with an end date, echo it back in the ad account’s currency, and get an explicit yes in THIS conversation; then pass exactly that amount. The server re-reads the live ad set and refuses with budget_mismatch when the two differ — never retry with a different number the merchant did not confirm. Refusals name the cause: no_funding_source (the ad account has no payment method), account_inactive, not_published (publish it first).
commerce_activate_inventory	Workspace admins only: explicitly activate Inventory after physical counts, product/variant mappings and existing orders have been reconciled. Call only with the merchant’s explicit activation request and reconciliation reference; never invent it. The physical count must include paid/COD unshipped allocations. Activation queues these in Inventory and returns inventory_pending while setup remains disabled; retry after allocations are confirmed. Resolve unpaid, ambiguous and already-shipped historical orders first. Does not import stock. Preflight and mapping are not consent.
commerce_add_campaign_ad	Add one more creative to a campaign, from a Drive file. Whether it is an image or a video is read from the file itself, not declared here.
commerce_add_storefront_domain	Point one of the merchant’s own domains at their shop. It does not serve traffic until DNS is in place — check with commerce_check_storefront_domain and tell the merchant what record to create.
commerce_alert_contacts_list	List a Commerce workspace’s business-alert contact book. Business alerts go ONLY through Telegram; WhatsApp is reserved for talking to buyers. A channel=‘whatsapp’ entry is a retired destination (status ‘revoked’): it never receives anything and can only be removed with commerce_alert_contacts_remove. Every entry carries a masked address, never the full phone number or chat id — do not ask for or relay the unmasked value. To add a destination, link a Telegram chat: commerce_telegram_accounts_list, then commerce_telegram_account_link.
commerce_alert_contacts_remove	Remove a business-alert contact. Refused with 422 category_requires_contact if it is the workspace’s only contact routed to payment_question.
commerce_alert_contacts_update	Rename an alert destination (a linked Telegram chat). Business alerts go only through Telegram; a retired WhatsApp destination is not edited, only removed with commerce_alert_contacts_remove. The label may never be blank (422 label_required).
commerce_alert_deliveries_list	List recent alert-delivery outcomes (one row per destination per notification): status, channel, masked address, and failure reason if any.
commerce_alert_routing_get	Get a Commerce workspace’s alert routing: which contacts receive each of the five categories (sales, shipping, balance, human, payment_question), plus which categories require at least one contact.
commerce_alert_routing_set	Replace the ENTIRE contact list routed to one alert category — this is a full replace, not an append: any contact not included in contact_ids stops receiving this category. Categories: sales, shipping, balance, human, payment_question. ‘payment_question’ (the bank-transfer confirmation that marks an order paid) refuses to be emptied (422 category_requires_contact if contact_ids is empty) and refuses a contact that cannot answer back (422 contact_cannot_answer — needs a linked Telegram chat; a retired WhatsApp destination never qualifies). On either refusal, explain it to the user instead of retrying with different ids.
commerce_archive_campaign	Archive a campaign — take it off the merchant’s list without destroying it. The row is KEPT: it is what attributes existing conversations and orders, and its ref-code link may still be live inside an ad someone already paid for. Only a draft, publish_failed, cancelled or failed campaign can be archived; a live one must be paused on the network first. NEVER tell the merchant the campaign was deleted.
commerce_boost_campaign	Turn an organic post that is already live into a paid ad on the same creative. It creates the paid campaign PAUSED — no delivery and no spend until commerce_activate_campaign. Use it when a post is doing well on its own and the merchant asks to put money behind it.
commerce_campaign_insights	Ad-spend numbers across the workspace’s campaigns for a window. Fail-soft by design: it answers {connected:false} rather than an error when the ad network is not connected, so a disconnected workspace reads as ‘nothing to show’, never as a broken tool.
commerce_cancel_image_job	Cancel a render that has not started yet. Once it is running the credential is being spent either way, so cancelling is refused — report that plainly rather than implying a refund.
commerce_cancel_order	Cancel an order and release its stock reservations. Only legal from draft/pending_payment/cod_pending/payment_failed — ‘paid’ and ‘fulfilled’ orders cannot be cancelled this way.
commerce_cancel_post	Cancel a not-yet-published organic post (draft, scheduled or pending review). An already-published post cannot be cancelled.
commerce_care_templates_list	List the shop’s reusable care templates — one per MATERIAL (‘Algodón peinado’, ‘Lino’), each holding wash/care instructions and default composition for every product made of it. Editing a template corrects every product linked to it, which is why linking beats repeating. Call this before creating one so you reuse rather than mint a near-duplicate.
commerce_carrier_status	Which carrier account this workspace ships on (its own, or Destesi’s) plus balance, cap and spend headroom when Destesi covers it. Never fails hard — it is the readiness probe to read BEFORE promising the merchant a guia.
commerce_check_storefront_domain	Re-check a custom domain’s DNS now. Use it after telling the merchant to create the record, instead of asking them to wait blindly.
commerce_confirm_web_order	Confirm — on the customer’s behalf — a contra-entrega order placed on the public shop, so its shipping label (guía) can be bought. Those orders come from an anonymous browser with only a typed phone number, so the shop asks the customer on WhatsApp and the label purchase is refused with awaiting_buyer_confirmation until they answer. Pass confirmed=false to record that the customer does NOT want it, which CANCELS the order and restores its stock. Refuses with buyer_denied if the customer already said it was not them (cancel the order instead), and with confirmation_not_applicable for any order that is not a shop contra-entrega sale.
commerce_connect_inbox	Workspace admins only: announce Commerce to Inbox as this workspace’s sales agent. Idempotent, and it never overrides an explicit people-only choice made in Inbox. Use it when the connection card says Commerce is not registered.
commerce_connect_status	Which third-party connections this workspace has through Connect, as Commerce sees them. Connect owns the connections; this is Commerce’s view of what it can therefore do.
commerce_create_audience	Create a saved Meta or TikTok audience. Provider is immutable. Meta fields live at targeting root; TikTok fields live under targeting.tiktok_ads.
commerce_create_campaign	Create a DRAFT campaign — nothing is published and nothing is spent. For a paid ad (campaign_type omitted or ‘paid_ad’): product_id, channel and budget_cents, where budget_kind is ‘daily’ (per day, the default) or ‘lifetime’ (the total for the whole run, which needs ends_at). For an organic post (campaign_type=‘organic_post’): product_id, channels and caption. BUDGETS ARE IN THE AD ACCOUNT’S CURRENCY, which is frequently not the currency the shop sells in — read it from commerce_list_meta_ad_accounts and say it out loud when they differ, because publish REFUSES a budget stated in another currency. Requesting several channels creates one campaign row per channel.
commerce_create_care_template	Create a reusable care template for one MATERIAL. care_codes must come from this market’s own set (read commerce_spec_schema first); a code from another market is rejected. NEVER invent a composition or a wash instruction — fill this only from what the merchant stated.
commerce_create_carrier_webhook	Mint or ROTATE the workspace’s carrier webhook token and secret, for a merchant on their own carrier account. Rotating invalidates the previous registration, so the carrier dashboard must be updated with the new URL or tracking updates stop arriving. 409 carrier_mode_not_byo when Destesi’s account is the one in use — there is nothing to register.
commerce_create_category	Create one shop category from the MERCHANT’s own word for it (‘Bota recta’, ‘Tablazzo’, ‘Tacones’). This is what a buyer reads as a section of the shop, so use their wording, not a tidied-up version of it. Do NOT put who the product is for in the name (‘Blusa dama’) — that is the product’s audience. Do NOT pass the MARKET here (‘Prendas de vestir’, ‘Calzado’): the market is one setting on the business profile. Idempotent on the normalized name — creating a section the shop already has returns the existing one.
commerce_create_content_set	Create a LAUNCH KIT: one content set (its motive and the shared brief) plus one draft piece per placement, each with its OWN ref code, so the merchant can tell afterwards which placement actually brought the conversations. Every piece is about the STORE, not a product — use commerce_create_post when the post is about one item. Placements may name channels Commerce cannot publish for the merchant (‘bio_link’, the link in the Instagram bio; ‘whatsapp_status’, a WhatsApp Status image): those come back with status ‘manual’, meaning the merchant posts them by hand, and their ref code works the same. Publishable placements (‘instagram’, ‘threads’, ‘facebook’) come back as drafts — publish each one with commerce_publish_post.
commerce_create_order	Create a Commerce order and queue its Inventory reservation. Inventory setup and exact mappings are required; read the order to verify its hold. Does not charge payment — call commerce_create_payment_link afterward.
commerce_create_payment_link	Mint a real payment link (Wompi checkout or bank-transfer instructions) for an order. This creates a real, chargeable payment reference.
commerce_create_post	Create a DRAFT organic social post for a Commerce product, on one or more connected channels. Nothing is published until commerce_publish_post is called (or scheduled_at arrives). content_format says what the post IS: ‘image’ (feed photo), ‘video’ (feed video), ‘reels’, ‘stories’ or ‘carousel’. Channels differ — Instagram takes all five; Facebook takes image, video and stories (VIDEO only, it has no image story); Threads takes only image and video — and the server refuses an impossible pair, naming what that channel supports. A carousel needs 2-10 items and no single creative; every other format needs exactly one, via image_drive_file_id or video_drive_file_id. Stories carry NO caption on any channel. Requesting several channels creates one post per channel, grouped.
commerce_create_shipment	Create the shipment row for an order (idempotent — calling it twice returns the same shipment). Package weight is computed from the order lines. Allowed before payment as well as after: shipping is quoted and priced before the buyer pays.
commerce_create_telegram_pairing	Mint a one-time link the merchant opens to bind a Telegram chat to this workspace for business alerts. Hand them the link; whichever chat redeems it is the one that gets bound.
commerce_delete_audience	Delete a saved audience. Campaigns already created keep their targeting snapshot.
commerce_delete_care_template	Delete one care template. Products linked to it stay sellable — they simply lose the shared sheet, so nothing in the catalog breaks. Say that plainly to the merchant instead of warning them off.
commerce_delete_category	Delete one shop category. Products in it are NOT deleted and NOT blocked — they fall back to uncategorized automatically, so deleting a section never loses products. Safe to reassure the merchant of that.
commerce_delete_telegram_pairing	Cancel an unredeemed Telegram pairing link. Already-bound chats are unaffected — remove those with commerce_alert_contacts_remove.
commerce_diagnose_campaign	Grade ONE campaign against real channel data. Signals carry a colour ONLY where a colour source exists: ratio metrics colour from the per-channel benchmark, money metrics ONLY against the merchant’s saved ad targets (commerce_get_ad_targets). A signal with benchmarked=false has NO colour — report the number without judging it, and never substitute an industry benchmark of your own. low_volume=true means there is too little data to judge; say so rather than grading noise.
commerce_dispatch_queue	Every paid order still waiting to be dispatched. This is the merchant’s work list for today; answer ‘what do I have to send?’ from here, not from the order list.
commerce_fulfill_order	Mark an order fulfilled. Only legal from the ‘paid’ status (409 illegal_transition otherwise) — this is a real order/payment state change.
commerce_get_ad_targets	The merchant’s stated advertising objectives for ONE channel: target ROAS, target cost per conversation, target cost per lead. A null target means the merchant NEVER stated it — before judging any campaign’s cost you must either read a real target here or ask for one. Objectives are per channel because attribution differs between networks; never quote Meta’s target while discussing Google.
commerce_get_business_profile	The merchant’s company details: name, tax id, contact, the agent’s name, the shop’s operating currency and its MARKET. The market decides which product types the pickers offer and which size scale the whole catalog wears — it is not cosmetic.
commerce_get_carrier_webhook	The workspace’s own carrier webhook registration (bring-your-own carrier accounts only): whether one exists and where it points.
commerce_get_catalog_source	Inventory owns all products and stock. Returns the canonical Inventory source and optional Shopify import provider. Commerce stores commercial settings only. Carries the Shopify admin_url when linked.
commerce_get_content_set	Read one launch kit back: the set and every piece, with each piece’s status, caption and ref-code link. Use it after commerce_create_content_set, and before commerce_write_content_set_captions to see which pieces still have no copy.
commerce_get_content_set_results	What a launch actually produced. Returns, PER PLACEMENT: link opens (hits on that piece’s own /r/ link), attributed conversations and orders, and paid revenue — plus the totals, and separately an unattributed row for the conversations and orders that carried NO code at all. Three things to carry into any answer. (1) The window is in the response and every number obeys it; by default it opens when the launch was created. (2) Attribution is FIRST-TOUCH EVIDENCE — someone arrived carrying that piece’s code — never proof that the piece caused the sale. (3) The unattributed row stays OUTSIDE the totals: it is word of mouth and forwarded screenshots, and folding it in would credit the launch with what it cannot claim. Read measurement: a metric whose state is not ‘measured’ must be reported as unavailable WITH its reason, never as zero. A link open proves the link was opened, not that the post was seen.
commerce_get_image_job	Check a render. Returns its status (queued | running | succeeded | failed | cancelled) and a PHASE LABEL — there is no percentage, because a render has no measurable progress and a number would be invented. On success it carries output_drive_file_id, which is the image; applying it is a separate, deliberate step. On failure, last_error is a code that can be acted on.
commerce_get_image_settings	The workspace’s image-generation model and quality, the valid options with their approximate per-image price, whether the merchant’s own OpenAI account is connected, and this month’s image usage. Read it when the merchant asks what images cost.
commerce_get_inbox_connection	Is Commerce’s sales agent set up as this workspace’s answerer in Inbox: available (this deployment has Inbox), registered (Commerce is set up there) and answering (it is the one replying). Available to workspace members.
commerce_get_inventory_configuration	Read Commerce Inventory setup readiness, integration identity, verified mappings and last refresh. Available to workspace members; no credentials returned.
commerce_get_order	Get one Commerce order’s details (status, totals, buyer, payment, delivery).
commerce_get_order_confirmation_mode	How contra-entrega orders get the customer’s WhatsApp confirmation question. mode “auto”: shop and Shopify orders are asked automatically and an unanswered question is re-sent after 4 business hours, up to 3 asks. “manual”: nothing is sent automatically. “” (never chosen): shop orders are asked at checkout, Shopify orders wait for the merchant, no re-send. effective = {storefront, shopify} each auto|manual; auto_resend. Late orders raise alerts in every mode.
commerce_get_order_confirmation_template	Which WhatsApp template asks shop customers to confirm a contra-entrega order, plus every candidate with status, body, buttons, variables and compatible/reason. Compatible = APPROVED, exactly two quick-reply buttons (first confirms, second cancels) and body variables {{1}}..{{n}} with n <= 7, filled in this order: order ref, items, subtotal, shipping, total, address, email. is_default marks Destesi’s own template. Templates are created in Inbox (inbox_create_template), not here.
commerce_get_order_timeline	Everything that happened to one order in order: created, paid, shipped, delivered, plus the alerts that went out. This is the answer to ‘what happened with this sale?’.
commerce_get_origin	The workspace’s shipping origin — the address every carrier quote departs from. Empty means no origin is configured, which is why quotes answer 422 origin_not_set.
commerce_get_payment_settings	The workspace’s payment configuration: preferred method, bank-transfer details, Bre-B key and the per-method enable flags. commerce_get_payment_status answers what actually WORKS; this is what is stored.
commerce_get_payment_status	How this workspace can charge RIGHT NOW: the effective settlement mode, which methods are enabled, and whether anything is missing. Read it before promising a buyer a payment link.
commerce_get_pickup_coverage	The date and time windows the carrier can collect this order’s parcel in. Answers 409 shipping_manual with no carrier, and 422 pickup_not_supported when the resolved provider cannot do pickups — a false answer here is a real limit, not an error to retry.
commerce_get_post_publish_settings	Whether this workspace stages autonomous organic posts for review instead of publishing them live.
commerce_get_product	Get one Commerce product’s details (price, stock, category, images).
commerce_get_product_activity	The audit trail of one product: what changed, when, and through which surface. Use it to answer ‘who changed this price?’.
commerce_get_product_stats	Sales numbers for one product: units sold, revenue and how it converts (a restricted member needs finance.manage). Use it before advising on price, stock or which product to advertise.
commerce_get_return	The state of an order’s return leg: whether one was quoted or bought, its label and its tracking.
commerce_get_shipment	One order’s shipment: carrier, tracking, parcel dimensions, cost and pickup state. 404 when the order has no shipment yet — create one with commerce_create_shipment.
commerce_get_shipping_settings	How this workspace ships: carrier or manual mode, its provider, the preferred and fallback carriers, and the manual flat/free-over prices. Every workspace has an answer here — no preference simply means ‘cheapest overall’.
commerce_get_shopify_product	What Shopify says right now about one imported product: vendor, type, tags, status, collections, every photo, every variant with price, compare-at, SKU, barcode, stock and stock per location, plus admin_url and online_store_url. Read live from the linked store. 404 not_imported for a product that did not come from Shopify.
commerce_get_storefront	The workspace’s PUBLIC online catalog: whether it is published, its slug and public URL, its branding and its hero category. configured=false means one was never created — say so plainly rather than reporting draft defaults as live. enabled=false means it exists but no buyer can reach it, which is a normal state.
commerce_get_storefront_domain	The merchant’s own domain for the shop, if any, and the DNS state of its verification.
commerce_get_strategy_limits	The guardrails every autonomous play runs inside: maximum discount, messages per buyer per week, the hours outbound nudges may be sent, the monthly coupon cap and the discount above which a human must approve. These bounds are what make autonomy safe — quote them whenever proposing a play that messages buyers or discounts prices.
commerce_get_wallet	The managed-ads wallet: whether this workspace has the grant, its balance and its movement history. Topping it up moves the merchant’s real money to Destesi and is deliberately an operator-console action only.
commerce_inventory_preflight	Workspace admins only: read-only reconciliation evidence for historical Commerce stock evidence, variants, held reservations and paid/COD allocations. This report does not switch Commerce to Inventory; use get_inventory_configuration for the current activation state. Manual reconciliation is required. Quantities are exact strings, not physical stock. ready_for_cutover is always false; this never authorizes import, edits or cutover. Check truncated_sections for incomplete detail lists.
commerce_link_ad_account	Choose which account of one ad provider Commerce publishes into. The connection belongs to Connect; this names the account this product acts through.
commerce_link_shopify_store	Workspace admins only: link one connected Shopify store (single choice, replaces a previous link). Linking DOES the whole thing: Inventory loads the store’s catalog (products, photos, prices, and opening stock for the items it creates) and Commerce brings the last 60 days of orders. The answer carries load and orders; load_error means the store is linked but the catalog could not be read, which a retry or Inventory’s apply_shopify_import fixes. Nothing to ask first: no parcel, no warehouse.
commerce_list_ad_accounts	The ad accounts of ONE provider linked to this workspace — the provider-generic twin of commerce_list_meta_ad_accounts, for Google and TikTok.
commerce_list_ad_channels	Every ad channel this workspace could advertise on and what shape each is in. ‘unknown’ is a real answer — it means the probe could not tell, NOT that the channel is disconnected; never collapse the two when reporting it.
commerce_list_audiences	List saved Commerce ad audiences. Meta and TikTok audiences are separate resources; optionally filter by provider.
commerce_list_campaign_events	The campaign TIMELINE: what happened to one campaign and WHO did it — created, updated (which fields), published / publish_failed (with the reason), activated, paused, budget_changed (from/to), archived, boosted, post_published… newest first. actor_kind names the door: ‘web’ (the merchant in the panel), ‘pat’ (this MCP server or the dst CLI), ‘assistant’ (the in-product chat, with the tool in via), ‘system’ (the scheduler). Read it before answering what happened to a campaign or why it is not running.
commerce_list_campaigns	List ad campaigns in a Commerce workspace.
commerce_list_carriers	The carriers the workspace’s shipping provider quotes in its origin country — the choices behind the preferred/fallback carrier settings.
commerce_list_categories	List a Commerce shop’s categories — the sections a buyer reads — plus the workspace’s market. There is no catalog of offered categories to choose from: they are whatever the merchant calls them.
commerce_list_content_sets	The launch kits in this workspace — each one a motive plus its per-placement pieces, every piece carrying its own ref code so the merchant can tell afterwards which placement actually brought conversations.
commerce_list_customers	The customer directory: one row per person who left an order, with the name, ID number (cédula), address, phone and email their orders carried, how many orders they bought / have open / lost / had returned, what they have paid, and a segment (returned = a parcel came back, repeat = 2+ bought, bought, pending = an order still open, none = never bought). The response also counts every segment under the same search. Search by any of those; a person’s orders are commerce_list_orders with their id as buyer_id. A restricted member without orders.manage or shipping.manage gets the row without the contact fields, and one without finance.manage without the money. The buyer’s CHATS are not here — they live in the Inbox product (inbox_list_contacts / inbox_list_conversations).
commerce_list_image_jobs	Every image render in the workspace and where each one got to. A render takes about two minutes, so this is how you find a job the merchant started earlier instead of starting another one.
commerce_list_meta_ad_accounts	The Meta ad accounts linked to this workspace, with the currency each one bills in. Read the currency before asking the merchant for any budget: it is the account that charges them, and it is frequently not the currency the shop sells in.
commerce_list_orders	List orders in a Commerce workspace, newest first, 100 a page; pass the returned next_cursor as before for older ones. Pass buyer_id (a customer id from commerce_list_customers) for one person’s orders.
commerce_list_product_variants	The stock breakdown by variant attributes (color, talla) for one product, plus its total stock_qty. Variants are read-only here; manage them in Inventory.
commerce_list_products	List products in a Destesi Commerce workspace.
commerce_list_promotions	The workspace’s automatic quantity promotions: per category, every every_n units (any size of that category) one unit is discount_cents cheaper; groups repeat. Commerce applies them to every shop, WhatsApp and web order on its own.
commerce_list_recent_campaign_events	The workspace’s most recent campaign events across EVERY campaign, newest first, each naming its campaign — the answer to ‘qué ha pasado con mis campañas hoy’. Same rows and actor vocabulary as commerce_list_campaign_events.
commerce_list_shipments	Every shipment in the workspace, optionally filtered by status. This is the ‘in transit’ / ‘delivered’ view — use commerce_dispatch_queue for what still needs to go out.
commerce_list_shopify_stores	The Shopify stores connected in Destesi Connect for this workspace and which one is linked as an Inventory import provider. A connected store is never adopted automatically; the merchant links one with commerce_link_shopify_store. Empty = connect a store in Connect first.
commerce_list_strategies	The sales-strategy plays the product knows, each with its honest status: ‘active’ (something really runs it, and it can be switched), ‘measurable’ (the opportunity is sized but nothing executes it), ‘diagnostic’ (a measurement with nothing to automate) or ‘blocked’, with the money each one moves (money figures are omitted for a restricted member without finance.manage). Never imply a measurable play can be turned on, and never present an opportunity sizing as revenue a play earned.
commerce_mark_delivered	Report an order as delivered. On a cash-on-delivery sale this is what SETTLES the money — the parcel reaching the buyer is the payment — and in manual mode it is the only delivery report there will ever be, since no carrier webhook exists to settle it later.
commerce_mark_placement	Record that the MERCHANT published a placement by hand — the Instagram bio link, a WhatsApp Status — the ones Commerce cannot publish for them. It is their own word: kept apart from a platform-confirmed publication, and never counted as a result. Only a ‘manual’ placement can be marked; a piece Commerce publishes itself is refused, because commerce_publish_post is what records that one. Marking twice is harmless and keeps the first timestamp.
commerce_mark_shipped	Report an order as dispatched: the shipment goes to ‘shipped’ and the order paid -> fulfilled, atomically. Needs dispatch data first (carrier always; a tracking number too unless the workspace ships manually) — 422 missing_dispatch otherwise, which means call commerce_update_shipment first.
commerce_orders_awaiting_confirmation	The contra-entrega orders still waiting for the customer to confirm them on WhatsApp — shop orders, and Shopify orders not yet dispatched — each with its confirmation block (asked, ask_count) and delivery phone. Send or re-send the question with commerce_resend_order_confirmation, or answer for the customer with commerce_confirm_web_order.
commerce_orders_awaiting_confirmation_summary	Counts of contra-entrega orders waiting for the customer’s confirmation: pending (all), late (never asked after 2 business hours, or no reply 4 business hours after the last ask) and urgent (24 business hours since the order, or all 3 asks spent and 4 business hours silent). late and urgent do not overlap; business hours are 08:00-20:00 Bogotá. Each open order in commerce_orders_awaiting_confirmation carries the same aging and waiting_since.
commerce_pause_campaign	Pause a live campaign now — delivery and spend stop. Always safe; do it the moment the merchant asks to stop, no confirmation needed. The campaign keeps its ad chain and can be activated again later.
commerce_post_insights	How one published organic post performed on its channel — reach, engagement and the rest of what the network reports for it.
commerce_preview_order_confirmation	What the WhatsApp confirmation question would tell the customer of a contra-entrega order: the products, the subtotal, the shipping quoted live as cash on delivery (the merchant’s preferred carrier, then the fallback, then the cheapest; the flat rate in manual mode), the total and the delivery address. Sends nothing and stores nothing. Fails with carrier_disabled, origin_not_set, address_not_set, weight_incomplete or dimensions_incomplete when the shipping cannot be quoted.
commerce_publish_campaign	Publish a draft campaign as a real but PAUSED ad on the network. It builds the whole ad chain under the merchant’s account and spends nothing — delivery only begins with commerce_activate_campaign, against a budget the merchant literally confirmed. Needs the workspace’s ad account and Page set (commerce_list_meta_ad_accounts / commerce_set_meta_ad_account) and the campaign to carry a creative.
commerce_publish_campaign_group	Publish every campaign in one multi-channel group at once, each as a real but PAUSED ad. Same rules and same non-spending posture as commerce_publish_campaign, applied to the whole group the merchant created together.
commerce_publish_post	Publish a draft organic post to its channel now. This puts real content on the merchant’s public account under their name; it cannot be un-posted from here. If the workspace has post review enabled, the post is staged for the merchant instead of published.
commerce_quote_return	Quote the return leg (buyer back to the shop) for a fulfilled order — the Ley 1480 retracto path. Read-only at the carrier. 409 return_not_ready before the order is fulfilled.
commerce_quote_shipment	Ask the carrier for live rates on an order. Read-only at the carrier — nothing is bought. Needs a configured origin (422 origin_not_set), a resolvable parcel weight (422 weight_incomplete) and the order’s delivery address. Answers 409 shipping_manual when the workspace dispatches by hand. Returns a quotation_id plus rate ids for commerce_select_shipping.
commerce_record_inventory_return	Needs shipping.manage: record an explicitly verified PHYSICAL return against this order’s original Inventory fulfillment movement. Returned units enter quarantine, never usable stock. Shipping return labels do not prove physical receipt. Generate one operation_id UUID before the first call and preserve it and ALL inputs for every retry or ambiguous response. queued=true does not prove completion.
commerce_refresh_inventory	Workspace admins only: refresh Commerce’s displayed availability from verified Inventory. Does not adjust stock or activate Inventory; checkout uses Inventory reservations.
commerce_remove_campaign_ad	Remove one creative from a campaign. The campaign itself is untouched.
commerce_remove_promotion	Delete an automatic quantity promotion by id (from commerce_list_promotions). Orders already placed keep their discount. Admin only.
commerce_remove_storefront_domain	Detach a custom domain from the shop. Buyers holding that URL stop reaching the store, so confirm before removing a domain that is already live.
commerce_rename_category	Rename one shop category, KEEPING every product attached to it. This is the way to fix a badly named section (a market like ‘Prendas de vestir’ sitting where a section belongs) without detaching its products. To move products between categories use the merchant console or the product tools, not this.
commerce_resend_order_confirmation	Send a shop order’s confirmation question to the customer again over WhatsApp. Use it when the order’s confirmation block reports asked:false — the first send never reached them, which is a delivery failure on our side rather than the customer ignoring us. It never opens a second question: the same one is re-delivered. Refuses with confirmation_already_resolved once the customer has answered, and with confirmation_ask_limit once the question was delivered 3 times (confirm on the customer’s behalf after reaching them another way, or cancel). The question is always built from the order: to fix what the customer mistyped, save it with commerce_set_shipping first.
commerce_retry_inventory_order	Needs orders.manage: queue durable Inventory synchronization for one order after investigating its reconciliation issue. queued=true does not prove reservation or fulfillment. Read the order afterwards; do not create a replacement order.
commerce_route_coverage	List the carriers the workspace’s shipping provider can quote, with per-carrier capability flags where the provider reports them (has_pickup, multi_package). source is ‘live’ (the provider’s own catalog) or ‘static’ (the built-in fallback when the live read is unavailable). A false capability flag means unknown-or-unsupported — never report it as a refusal. Fails with 409 shipping_manual when the workspace dispatches by hand (no carrier).
commerce_search_audience_targeting	Resolve Meta or TikTok location/interest names to provider-native ids before creating an audience.
commerce_select_shipping	Pick one quoted rate and price the order’s shipping from it — the server re-reads the rate from the quotation, so no price a caller supplies is ever trusted. Refused once the order is paid (409 order_already_paid): shipping is frozen at charge time. Re-selecting while still unpaid simply overwrites the choice.
commerce_set_ad_targets	Save the merchant’s advertising objectives for ONE channel. Only the fields you pass change, and an explicit 0 CLEARS a target. Save only numbers the merchant literally stated or agreed to — never one you derived silently, because these are what every later cost judgement is measured against.
commerce_set_business_profile	Write the merchant’s company details. Omitting store_category PRESERVES the stored market — never send an empty one to ‘clear’ it, because the market reinterprets the size scale of the entire catalog. Currency is the shop’s operating currency, which is separate from the ad account’s.
commerce_set_catalog_source	Workspace admins only: record Inventory as the canonical catalog source. Optional Shopify imports are configured through commerce_link_shopify_store and create items in Inventory.
commerce_set_image_settings	Change the image model and quality for future renders. ‘high’ costs about four times ‘medium’ and needs the merchant’s own OpenAI account connected and paying — without one it is refused (high_requires_own_key), and when Destesi covers this workspace’s images it is refused too (high_unavailable_under_grant). State the new per-image price after changing it.
commerce_set_inventory_mapping	Workspace admins only: map an exact Commerce product/variant to an existing verified Inventory item and location. Does not create stock or activate Inventory. Never infer a variant from matching labels.
commerce_set_meta_ad_account	Choose which Meta ad account Commerce publishes into. This is the LINK, not the connection: the connection itself belongs to Connect, and this only says which of the connected accounts this product acts through.
commerce_set_order_confirmation_mode	Set contra-entrega confirmations to “auto” or “manual” (workspace admins; anything else is 422 invalid_mode). Confirm with the merchant before choosing auto: it messages new customers on WhatsApp on its own.
commerce_set_order_confirmation_template	Choose the approved WhatsApp template that asks customers to confirm contra-entrega orders (workspace admins). Pick a compatible candidate from commerce_get_order_confirmation_template; an incompatible one answers 422 with its reason (not_approved, needs_two_buttons, too_many_variables, unsupported_variables, not_found). name “” resets to Destesi’s default. A send that fails on the chosen template falls back to the default, then plain text.
commerce_set_origin	Set the workspace’s shipping origin. FULL replace: send every field, because this is the address the carrier collects from and a half-written one produces quotes from the wrong place.
commerce_set_payment_settings	Write the workspace’s payment configuration. This is a FULL replace of the payment block — read commerce_get_payment_settings first and send back every field the merchant wants to keep. preferred_method is only the tie-break for an unattended mint, never an exclusive selection: the *_enabled flags are what turn a method on.
commerce_set_post_publish_settings	Turn the review gate for autonomous organic posts on or off. With require_review=true nothing the agent writes reaches the merchant’s audience until a human approves it.
commerce_set_product_sheet	Set what a product is MADE OF, how to CARE for it, and what the merchant RECOMMENDS. Every field is optional and an OMITTED field is left unchanged — send only what you were actually told, never a full replacement rebuilt from memory. Prefer care_template_id (from commerce_care_templates_list) over repeating the same care on every product. specs keys and care_codes must belong to this market (commerce_spec_schema) or the call is rejected naming the field. NEVER infer a fabric, a wash temperature or a fit from a product’s name or photo: if the merchant did not state it, leave it unset.
commerce_set_promotion	Create or replace the automatic quantity promotion of ONE category (one per category). Example: 3 skinny for $198.000 at $80.000 each is every_n 3, discount_cents 4200000 (COP cents = pesos x 100). active=false pauses it. Admin only. It changes what every buyer pays.
commerce_set_shipment_packages	Declare the parcels an order ships in. An empty list means one parcel, which is the default. Locked once the guia is bought — declare the split before buying, not after.
commerce_set_shipping_address	Set an order’s delivery destination. name, phone, document, address and city are all required by the carrier — an incomplete address is refused (address_incomplete / customer_info_incomplete) rather than saved half-written, because a guia bought against it cannot be undone for free.
commerce_set_shipping_settings	Change how the workspace ships. Read commerce_get_shipping_settings first and send back what should stay: mode and carrier_provider are preserved when omitted, but the carrier codes and manual prices are a full replace. Moving a workspace to ‘manual’ turns off every carrier quote; moving it back needs a connected carrier account.
commerce_set_storefront	Create or update the public catalog. The slug is global across merchants and can come back slug_taken; an unreadable brand_color comes back low_contrast. enabled=true PUBLISHES the shop to the open internet — confirm with the merchant before the first publication. Read commerce_get_storefront first: this write replaces the block.
commerce_set_strategy_limits	Change the autonomy guardrails. Only the fields you pass change. LOOSENING one (a bigger discount, more messages, wider hours) deserves an explicit confirmation from the merchant first; tightening needs none. Echo the new values back after saving.
commerce_set_strategy_state	Turn an ACTIVE strategy play on or off. Reversible and spends nothing — but confirm before DISABLING a play that is currently recovering revenue. A measurable, diagnostic or blocked play is refused with play_not_switchable: there is nothing running to toggle.
commerce_settle_imported_order	Close an order IMPORTED from the merchant’s previous store (source ‘shopify’) with what actually happened: outcome ‘delivered’ (courier delivered and collected — the order becomes fulfilled and counts as a sale) or ‘not_delivered’ (refused or returned — cancelled). Shopify never marks a cash-on-delivery order paid, so this is how those sales end here. Moves no stock. The ONLY write an imported order accepts; commerce_cancel_order and the shipping tools answer imported_order for it. 409 not_imported for an order Commerce placed itself; illegal_transition once already settled.
commerce_setup_readiness	What this workspace still needs before it can sell, derived server-side. Read it before proposing a next step so you never suggest something the shop cannot do yet, and so you can name the ONE thing that unblocks it.
commerce_spec_schema	Read which spec-sheet fields and care codes this shop’s MARKET asks for. The catalog is closed and market-specific: an apparel shop is asked for composition, fabric and fit with ISO textile care codes, a jewellery shop for material and hypoallergenic with its own care set, a consumables shop for ingredients, allergens and a REQUIRED mode of use. Call this BEFORE commerce_set_product_sheet or commerce_create_care_template so you send keys and codes this market accepts — anything else is rejected. Answers 404 market_not_set when the shop has not chosen a market; do not guess one, it also decides the size scale.
commerce_start_image_job	Start generating an image and get a JOB back — it takes about two minutes, so nothing waits for it here. Poll it with commerce_get_image_job. The job produces an image and NEVER overwrites anything: the product’s or campaign’s current picture stays as it is until someone applies the new one, so there is no moment where the merchant has neither. A real reference photo is REQUIRED — pass reference_drive_file_id, or a product_id whose product has a photo; there is no text-only generation in this product. Pass the same idempotency_key to retry safely: a repeat reaches the SAME job (created=false) rather than paying for a second render.
commerce_suggest_product_description	Write a catalog description FROM THE PRODUCT’S REAL PHOTO. Pass product_id (an existing product — its stored photo is used) or image_drive_file_id (a photo not yet attached to a product). Returns the suggested text ONLY; nothing is saved. Save accepted catalog descriptions in Inventory.
commerce_sync_shopify_orders	Bring the linked Shopify store’s last 60 days of orders into Commerce without touching the catalog (no parcel, no Inventory write). Creates new orders and refreshes existing ones as read-only rows (source ‘shopify’) visible in commerce_list_orders. Answers seen/created/updated/status_changed/skipped/truncated. 409 catalog_source_not_shopify = link a store first.
commerce_telegram_account_link	Make Commerce send its business alerts to one already-connected Telegram chat. Takes an account_id from commerce_telegram_accounts_list and nothing else — the chat and its name are re-read from Connect, so an id invented here is refused (404 account_not_found) rather than acted on. 409 account_not_active means Connect no longer has it live. This CANNOT connect a new chat: connecting happens in Connect, and there is no pairing link to hand out. To stop using one, commerce_alert_contacts_remove — that unlinks it in Commerce and leaves it connected in Connect.
commerce_telegram_accounts_list	List the Telegram chats this Commerce workspace can send business alerts to. Each row says whether Commerce already uses it (linked:true), whether it is merely available in Connect, or whether it is BROKEN (linked here but no longer connected in Connect — alerts to it are going nowhere). Connect owns the connection; linking is what makes Commerce use one. When connect_available is false we could not reach Connect: say so, never that the workspace has no chats.
commerce_unarchive_campaign	Put an archived campaign back on the merchant’s normal list. Find the id with commerce_list_campaigns(archived=true).
commerce_unlink_ad_account	Unlink one ad account from Commerce. It stays connected in Connect; Commerce simply stops publishing into it.
commerce_unlink_meta_ad_account	Unlink a Meta ad account from Commerce. The account stays connected in Connect — this only stops Commerce publishing into it, and a workspace with no linked account cannot publish paid ads at all.
commerce_unlink_shopify_store	Workspace admins only: stop imports from the linked Shopify store. Inventory remains the catalog authority; its items and the Connect connection stay.
commerce_unmark_placement	Undo commerce_mark_placement — the merchant had not published that placement after all.
commerce_update_audience	Replace a saved audience’s name and targeting. Its provider cannot change, and existing campaigns keep their snapshot.
commerce_update_campaign	Update a DRAFT campaign. PARTIAL: only the fields you pass change. Covers every merchant-editable field, including the organic post’s caption and schedule. A campaign that is already published on the network is not edited here — its live budget is an ad-network operation the operator console owns.
commerce_update_campaign_budget	Change what a PUBLISHED campaign spends. Writes the live ad set on the network first and the campaign row only after the provider accepted. Same HARD RULES as activation: pass only an amount the merchant literally confirmed in this conversation, in the ad account’s currency; a lifetime budget needs ends_at. For a DRAFT use commerce_update_campaign instead.
commerce_update_care_template	Update one reusable care template. PARTIAL: only the fields you pass change. Correcting a template fixes every product linked to it at once, which is the point of templates — care_codes must come from this workspace’s market catalog (commerce_spec_schema), and a wrong wash instruction ruins the garment the buyer just received, so change these only from what the merchant told you.
commerce_update_product	Update Commerce pricing, shipping and merchandising for an Inventory product. Inventory owns product identities, names, descriptions, photos, variants and stock. Only supplied commercial fields change.
commerce_update_products_bulk	Re-file several products at once: move them to a category, or set who they are for. Only the fields you pass change, and they change on EVERY id you list — this is the tool for tidying a catalog, not for editing one product (use commerce_update_product).
commerce_update_shipment	Set an order’s dispatch data by hand: carrier, tracking number and URL, parcel overrides, shipping cost. PARTIAL — only the fields you pass change. This is the manual-dispatch path (the merchant delivering themselves, or handing the parcel to a courier off-platform); it never talks to a carrier.
commerce_write_content_set_captions	Write the copy for a whole launch in ONE pass, from the set’s brief, so the pieces answer each other instead of reading as separate posts. By default it fills only the pieces with NO caption yet — anything already written belongs to the merchant and is left alone, and asking again when they are all written is not an error, it reports captions_written 0. Pass overwrite=true only when the merchant asks for a rewrite. Pieces that carry no text are skipped: the bio link, and stories on any channel.