Commerce

Tools in the commerce scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants commerce.

add_job_date

Scope: commerce:write

Put a date on the job: a delivery (a window between on_date and end_date), an appointment (a slot: at_time–end_time), or something else. firmness estimated|confirmed. where_address/where_details say where; needs says what the person going must bring. visible_to_client false keeps it to our side. step_index pins it to one of the steps; assigned_participant_id to one of our people.

add_job_note

Scope: commerce:write

A private note on the job — our side only, the client never sees it. Pin it to a date or a stage, or leave it on the job.

add_job_person

Scope: commerce:write

Add a person to a job. side 'business' (default) = one of ours — a driver, a technician — who sees the work and can post updates but never a figure; side 'client' = someone on the client's side who sees the figures and can pay. They get their own link.

add_job_stage

Scope: commerce:write

Add a money stage. On a draft it is simply added; on a sent job it is PROPOSED and needs the client's agreement before it can be paid.

answer_product_question

Scope: commerce:write

Answer (or re-answer) a buyer's question on a listing. The answer is PUBLIC on the listing's Q&A tab, under the business — short, honest, no promises the listing doesn't make. question_id from list_product_questions.

apply_email_theme

Scope: commerce:write

Dress every buyer email in one of the house designs in a single move: 'studio_white' (editorial stationery), 'dark_signal' (premium night), 'bold_banner' (poster energy), 'default' (the platform frame), or 'custom' (put this store's OWN designs back on). Covers the receipt family, the invoice AND its printable document; the store's live logo and accent flow in automatically. Switching is always reversible — designs you authored with set_commerce_email_template are kept on their own shelf, never overwritten by a theme. A theme is an ordinary token design — restyle it afterwards with set_commerce_email_template. The owner previews and switches on Commerce → Settings.

cancel_job

Scope: commerce:write

Cancel a job on which no money has moved. If money has, refund from Sales and close it instead.

cancel_job_stage

Scope: commerce:write

Withdraw an unpaid stage (pending, proposed or payable). A paid stage cannot be cancelled — refund from Sales.

check_purchase

Scope: commerce:read

Has the person you are talking with bought this listing? Answers from their own Wakato orders (never by name): { bought, times, test_only, refunded, latest_order, answer }. Works in a one-to-one chat — with someone who has you, or your own DM. A TEST order (no money moved) is reported as test_only, not bought.

close_job

Scope: commerce:write

Close an active or delivered job once nothing is held on it.

control_subscription

Scope: commerce:write

Cancel or resume a customer's subscription. action: 'cancel_at_period_end' (graceful — keeps access until the period ends), 'cancel_now' (immediate — access revoked at once), or 'resume' (undo a scheduled cancel). subscription_id from list_subscriptions. Access grants are revoked automatically.

create_discount

Scope: commerce:write

Create a promo code buyers type at checkout. Set exactly ONE of percent_off (1–100) or amount_off_cents. Applies to the merchandise subtotal, never shipping; validated server-side; a redemption counts only when the order settles. Scope with product_ids and/or tags (product must carry ANY listed tag — e.g. tags:["men"] for a menswear sale); omit both for storewide. Optional: min_subtotal_cents, max_redemptions, per_buyer_limit, starts_at/expires_at (ISO).

create_invoice

Scope: commerce:write

Create an invoice from the connected commerce account. line_items amounts are in CENTS (unit_amount_cents: 15000 = $150.00). Defaults to a draft; pass send:true to immediately number it and email the recipient (gapless INV-#### numbering, payment link auto-created). If the space configured a billing email address, it sends from that address.

create_job

Scope: commerce:write

Start a job for one client. A CUSTOM OFFER: pass product_id (one of the store's service listings) and the listing's title, what's included, steps and price fill whatever you leave blank — then name your own price in stages or your own scope, and only this client sees it; the listing never changes. Without product_id it is a standalone job. Stages are the money, in whole currency units: [{label:'Deposit', amount:50, due_rule:'on_accept'}, {label:'Balance', amount:70, due_rule:'on_delivery'}] (due_rule on_accept|on_checkpoint|on_delivery|on_date|manual; hold_until_delivery default true). Steps are the plain-words checkpoints the work moves through. Saved as a draft unless send:true.

create_payment_link

Scope: commerce:write

Create a shareable checkout link for the connected commerce account. amount_cents is in CENTS (1999 = $19.99). link_type one_time (default) or subscription (needs billing_interval). Returns pay_url to share. Requires the seller's Stripe payouts to be enabled.

create_product

Scope: commerce:write

Create a product in the connected commerce account (starts as an unpublished draft). price is in whole currency units (e.g. 19.99). Set product_type:'physical' for shippable goods (then set inventory_quantity + shipping_fee_cents); default 'digital' has no stock/shipping. For size/color options use set_product_variants after creating. Go live with update_product {status:'active', is_published:true}.

delete_product

Scope: commerce:write

Delete a listing (with its packages, resources, variants, files, questions and reviews). If any order references it, it is ARCHIVED instead (off sale everywhere, history kept). confirm_title must match the listing's title exactly. Prefer update_product {status:'archived'} for a pause.

duplicate_product

Scope: commerce:write

Copy a listing as a new unpublished draft with the same details, packages, resources, variants and deliverable files (questions and reviews are not copied). Optional title; defaults to '<title> (copy)'. Then edit and go live.

fulfill_order

Scope: commerce:write

Mark a physical order shipped with tracking — notifies the buyer and starts the payout release window. order_id from list_orders; carrier e.g. USPS/UPS/FedEx/DHL.

get_checkout_design

Scope: commerce:read

Read how THIS space's storefront is designed: the checkout brand tokens, the product-card template and the product detail-page templates (checkout_shell_html is a retired layout — it is not drawn). Use before changing them.

get_commerce_email_design

Scope: commerce:read

Read the buyer-email design for this space's store: the receipt / invoice / shipped email frames (null = default Wakato frame carrying the store's name + checkout branding) and the sender identity buyers see. Buyers ALWAYS get these emails automatically at payment/shipping — design only changes the frame.

get_commerce_feed

Scope: commerce:read

Get the PUBLIC agentic-commerce product-feed URLs for this space (JSON for AI shopping agents, XML for Google Merchant) plus how many products are currently discoverable. Share these so external AI agents (ChatGPT, Google) can find and sell the space's opted-in products. A product only appears when agent_discoverable is on AND it is active + published.

get_commerce_policies

Scope: commerce:read

Read the business's canonical policies — terms & conditions, refund policy, shipping policy. THE source of truth: quote these verbatim when a buyer asks; never improvise a policy that isn't written here. Buyers also see them on payment pages and printed invoice documents. null = not written yet (ask the seller, then save with set_commerce_policies).

get_commerce_report

Scope: commerce:read

How the store is doing: orders, revenue, average order, refunds, open disputes for a period (7d | 30d | 90d | 12m | all, or from/to ISO dates), top products, a per-day series, sales by source (direct / community / referral), plus what needs attention — unanswered questions, active subscriptions, low stock.

get_commerce_status

Scope: commerce:read

Check whether THIS space is set up to take payments, in plain terms — read this BEFORE telling anyone how to 'set up' or 'connect' payments. Returns stage (not_set_up | pending | ready), a summary to relay, and a next_step (null when ready). If it's already ready, there is nothing to set up. Never describe payment setup from memory, and never name the underlying payment provider — Wakato white-labels it.

get_conversation

Scope: commerce:read

A conversation with a buyer, oldest message first, with what it is about (product_id / order_id in each message's context).

get_job

Scope: commerce:read

Read one job in full: the engagement, its stages (with pay links where payable), people, dates, private notes, requirements, and the listing it was started from (title + listed price) when it is a custom offer.

get_order

Scope: commerce:read

Get one order from the connected commerce account.

get_product

Scope: commerce:read

Get one product from the connected commerce account.

get_storefront_sdk_reference

Scope: commerce:read

How to build a storefront ENTIRELY in the seller's own design and still sell through Wakato: the Storefront SDK every served page carries. Bind a listing's facts (title, price, photos, options, stock, shipping) with data-wakato-listing / data-wakato-field marks or Wakato.store — they stay live when the seller edits the listing, never hard-code them — and build your own checkout form with Wakato.checkout.quote (Wakato's own arithmetic: shipping, discount, tax, total), Wakato.checkout.paymentField (Wakato's secure card field inside your design) and Wakato.checkout.pay (charges exactly the quote). Read this before designing a product page or a checkout your own way. Free.

get_test_kit

Scope: commerce:read

The shop's TEST KIT: what to type to rehearse a listing before it goes live — a test buyer, addresses (one per country the shop ships to, one it does NOT cover, one with no postal code), test promo codes, and the platform's test cards (each number = one outcome). Nothing in it is real. Then place_test_order. Read this before rehearsing; never invent a card or an address.

list_after_purchase_targets

Scope: commerce:read

The store owner's PM groups, communities and active Wakato Pass templates — the ids an automation on commerce_order_paid uses to let a buyer in (add_buyer_to_group, add_buyer_to_community, enroll_in_pass). After a sale is an automation, not a listing setting.

list_buyers

Scope: commerce:read

Aggregated buyers of the connected commerce account: payment-link/invoice payers grouped by email with payment count and total. Payout balances are never exposed.

list_conversations

Scope: commerce:read

The store's Inbox: conversations buyers opened from a listing, the business profile or an order (filter: all | waiting — unread on the store's side | orders | closed). This is where 'Message us' lands; it is the same list the seller sees in Commerce → Inbox and the space sees in its Commerce.

list_discounts

Scope: commerce:read

List the seller's promo codes (code, percent/fixed amount, scope, redemption count, active/expiry). A code with is_test true belongs to the test kit and works only on a test order.

list_disputes

Scope: commerce:read

Disputes buyers opened on the store's orders, with your response and the admin's resolution. status filter: open | resolved.

list_invoices

Scope: commerce:read

List the connected commerce account's invoices (status: draft|sent|viewed|paid|overdue|void).

list_jobs

Scope: commerce:read

List the connected store's jobs (engagements): a scoped piece of work for one client, paid in stages, with steps, dates, people and a thread. kind is custom_offer (started from a listing by hand), bought_as_listed (a sale opened it) or standalone. Filter by status (draft|sent|active|delivered|closed|declined|cancelled) or client_email.

list_marketplace_categories

Scope: commerce:read

The Wakato Marketplace's categories (id, name, parent). Set a listing's with update_product { marketplace_category_id } before or when submitting it (marketplace_enabled:true).

list_orders

Scope: commerce:read

List the connected commerce account's marketplace orders (amount, status, fulfillment, product).

list_payment_links

Scope: commerce:read

List the connected commerce account's payment links with their public pay_url.

list_product_deliverable_files

Scope: commerce:read

List the paid files a digital product delivers after purchase (private; buyers get signed download links).

list_product_questions

Scope: commerce:read

Buyer questions on the store's listings (newest first; unanswered_only to see what is waiting). Buyers wait on these — answer with answer_product_question. Omit product_id for every listing.

list_product_resources

Scope: commerce:read

List a product's public Resources (learn-more videos, articles, files shown in the listing's Resources tab).

list_product_variants

Scope: commerce:read

Read a product's option axes (e.g. Size, Color) and its concrete variants (each with price override + stock).

list_products

Scope: commerce:read

List the connected commerce account's products (title, price, status), newest first, archived ones left out unless you pass status:'archived'. The answer says how many there are (total, has_more): to find one listing by name pass search — never conclude a listing does not exist from one page of results. Every LIVE one is on this space's storefront pages automatically. Requires a commerce account connected to this space.

list_reviews

Scope: commerce:read

Reviews on the store's listings (rating, title, comment, your reply). unreplied_only to see what still has no reply. Omit product_id for every listing.

list_subscriptions

Scope: commerce:read

List the commerce account's recurring subscriptions (id, buyer, source, status, period end, cancel-at-period-end). Filter by status (active|past_due|canceled).

mark_invoice_paid

Scope: commerce:write

Mark a SENT invoice as paid — for payments taken outside Wakato (cash, bank transfer, etc.). Fires the invoice-paid automation. The invoice must have been sent (not a draft) and not already paid/void. invoice_id from list_invoices.

mark_job_delivered

Scope: commerce:write

Say the work is done. The client is asked to confirm; whatever is held releases when they do.

mark_job_stage_paid_outside

Scope: commerce:write

Record that a stage was paid outside Wakato (cash, bank transfer, mobile money). Wakato did not hold or process that money and the receipt says so. Only on an accepted job.

message_buyer

Scope: commerce:write

Write to the buyer of an order AS THE BUSINESS: an email to the address that paid (replies reach the store's mail) and, for Wakato buyers, the same note in their Wakato PM from the seller's account. OUTBOUND — keep it about their order. order_id from list_orders.

offer_listing

Scope: commerce:read

Put one of your shop's listings in the chat you are answering, as a card with a Buy button — THE way someone pays you: call it whenever they ask to buy, ask the price of, or need the work of a listing (for themselves or anyone else), instead of explaining how to pay. Use it when the person needs something your instructions say is paid (a tagged listing, [listing:<id>]); in a chat with someone who has you, ONLY the listings tagged in your instructions may be offered. Say in a line what it covers, then offer it; don't start the paid part until it's bought. When they buy, a line lands in this chat saying so — that is your go (check_purchase answers any time). Returns { offered, message_id, listing }.

offer_payment_link

Scope: commerce:read

Charge the person you are talking to for THIS job: makes a one-time payment link for the amount you and they agreed and puts it in this chat as a card with a Pay button. Only that person can pay it, and it closes once paid. Use it when the work isn't one of your listings or needs its own price ("a 30-second ad with 2 revisions: $49"); for a tagged listing use offer_listing. Say in a line what the payment covers, then send it; don't start the paid part until it's paid. When they pay, a line lands in this chat saying so — that is your go. Only in a one-to-one chat. Returns { offered, message_id, pay_url, amount_cents, currency }.

open_commerce_account

Scope: commerce:write

Open a commerce account (a shop) FOR THIS SPACE when get_commerce_status says not_set_up. The shop is owned by the SPACE OWNER, named after the space unless you pass a name, and connected to this space in the same step — after it succeeds every other commerce tool works (products, invoices, payment links). Only allowed when the owner has switched on 'the agent may open a commerce account' for the space; otherwise the error says so — relay it and ask the owner. The new shop cannot collect money until the owner picks which verified business it pays out through (Account Management → Commerce accounts); say that plainly and build the catalog as drafts meanwhile. Never name the underlying payment provider.

place_test_order

Scope: commerce:write

Rehearse a purchase of a listing (a DRAFT, or LIVE bought as a test) exactly as a buyer would: the real checkout, the shop's test kit for the buyer and address, a test card for the outcome. 'pays' places a test order (no money, no stock, counts toward nothing — emails, the job and automations run for real); 'declined' answers with the decline; 'needs_verification' walks the bank challenge then pays. Pick a 'not_covered' address to rehearse the shipping refusal; pass a promo code to rehearse it. A live listing may be rehearsed too — it stays on sale and the order is still a test. Never a real purchase.

post_job_update

Scope: commerce:write

Post into the job's thread as the business. Either a text update (body), or a TRACKING NUMBER (tracking: {carrier, number, url}) — that one also lands at the top of the job for the client. A sent job only.

refund_order

Scope: commerce:write

Refund a marketplace order to the buyer via the original payment (full, or partial with amount_cents in CENTS). ⚠️ Money leaves the business and can't be un-refunded. The order/payout status updates automatically once the refund settles. order_id from list_orders.

remove_job_date

Scope: commerce:write

Take a date off the job.

remove_job_note

Scope: commerce:write

Remove a private note (note_id from get_job).

remove_job_person

Scope: commerce:write

Take a person off a job (participant_id from get_job).

reply_conversation

Scope: commerce:write

Reply to a buyer in the store's Inbox AS THE BUSINESS. They see it on their order page / the listing and by email. Keep it about their question; say when you don't know. close:true marks the conversation done.

reply_to_review

Scope: commerce:write

Reply to a review as the business — PUBLIC under the review. Thank a good one briefly; address a bad one plainly and say what you'll do. Pass reply:null to remove a reply. review_id from list_reviews.

request_job_stage

Scope: commerce:write

Ask the client for a stage now (stage_id from get_job): they get the invoice and a pay link. The job must be active or delivered.

respond_to_dispute

Scope: commerce:write

Respond to an open dispute for the admin who resolves it: what was delivered, when, and any evidence (tracking, links, dates). Read the order first (get_order). dispute_id from list_disputes.

send_invoice

Scope: commerce:write

Send (or re-send) an invoice: assigns the gapless number on first send, creates/reprices its payment link, emails the recipient, returns the pay_url.

send_job

Scope: commerce:write

Send a draft job to its client. They get a link (and Messages, if they have an account), accept, and pay the first stage; the job goes active when they do.

set_checkout_branding

Scope: commerce:write

Color THIS space's checkout — the sheet that opens over your pages when someone buys: its Pay button and the secure payment field take your colors, font and corner radius. Colors are hex (#RRGGBB); logoUrl must be https. Your cards, product pages and Buy buttons are designed on the page itself (set_product_card_template, set_product_page_template). Pass clear:true to revert to the default theme.

set_checkout_layout

Scope: commerce:write

RETIRED — the checkout is no longer wrapped in a layout: it opens as a sheet over your own page. Design the page instead (set_product_card_template, set_product_page_template, your own Buy buttons carrying data-wakato-checkout="<product id>" or calling Wakato.checkout(id)) and color the checkout with set_checkout_branding. Only clear:true still works (it empties an old layout).

set_commerce_email_template

Scope: commerce:write

Design a buyer email END TO END — same grammar as product cards/pages: the platform fills facts into your layout. SIX independently designable kinds: 'receipt' (order receipts, and the fallback for the others), 'payment_link' (payment-link receipts), 'invoice' (the pay-me document), 'invoice_paid' (the settled receipt), 'shipped' (the shipping notice), 'refund' (the refund confirmation). payment_link/invoice_paid/shipped/refund fall back to the receipt design when unset, so one design can still cover everything. TWO modes: (a) BLOCK — include one <div data-wakato-receipt-slot></div> and the whole facts block mounts there; (b) TOKEN — lay everything out yourself with {{items}} (items+totals table) + for receipts/shipped {{actions}} (the buyer's download/track/review buttons + notes) + {{statement_line}} (card-statement facts), or for invoices {{pay_button}}; those are MANDATORY and enforced at save — buyers lose downloads or the pay link without them. Optional everywhere: {{store_name}} {{buyer_name}} {{reference}} {{date}} {{total}}; invoice also has {{bill_to}} {{from}} {{legal}} (the business's legal name/address/tax id — fill them via update_business_details) {{notes}} {{due_date}} {{issued_date}} {{reminder}} {{pay_qr}} (a scannable brand-tinted pay-QR image) {{document_link}} (the recipient's view/print/save-as-PDF link — the emailed invoice is also a printable DOCUMENT). Logos/photos: any https <img> works. Inline style= only; no scripts/forms. clear:true reverts a kind to the default. The owner previews every email on Commerce → Settings.

set_commerce_policies

Scope: commerce:write

Write the business's policies (terms & conditions / refund / shipping) — plain text, saved on the BUSINESS so they hold across every space it operates in. They render to buyers on every payment page and in the terms section of printable invoice documents, and agents answer from them. Partial update: only keys you pass change; empty string clears one. These are real commitments the seller is bound by — save what the seller actually decided, don't author policy on their behalf.

set_job_step

Scope: commerce:write

Move a running job to a step (0-based index into its steps), optionally with a note the client reads. Stages due on that step become payable.

set_job_steps

Scope: commerce:write

Replace the job's steps (the full ordered list). Steps already passed can be renamed, not removed.

set_product_after_purchase

Scope: commerce:write

Set or clear the LINK a buyer gets after paying for this product (link_url + link_label — a Discord/WhatsApp/Telegram invite, a course platform, a booking page), shown on the thank-you page, the receipt and their order; it never forces a Wakato sign-in. Everything else after a sale is an AUTOMATION: create an automation on commerce_order_paid with trigger_config.product_id and add_buyer_to_group / add_buyer_to_community / enroll_in_pass / agent_message_buyer — group_id, community_id and pass_template_id here are refused.

set_product_card_template

Scope: commerce:write

Design the product CARD every listed product renders into on this space's storefront pages (grids + single cards). It is YOUR design: any HTML, <style>, classes and <script> (put shared CSS/JS on the page once rather than in every card). Tokens (escaped — safe in text or inside an attribute): {{id}} {{title}} {{price}} (formatted: "$28", "From $40", "$9/month") {{price_amount}} {{currency}} {{description}} {{image}} (first photo as an <img>) {{image_url}} {{images}} (swipeable strip of every photo) {{rating}} (★ fragment, empty until reviewed) {{rating_avg}} {{rating_count}} {{url}} (the product's live detail page) {{available}} ("true"/"false"; the card's wrapper also carries data-available) {{buy_label}} (Buy now / Book now / Subscribe / Sold out…) {{buy_url}} (the checkout's address — a plain link that works even with no script) {{checkout_attrs}} {{buy}}. BUY BUTTON: use the ready-made {{buy}}, or design your own — any element carrying {{checkout_attrs}} (= data-wakato-checkout="<id>") opens the platform checkout OVER the page on click, e.g. <button {{checkout_attrs}} class="buy">{{buy_label}}</button> ({{checkout_attrs}} is empty when sold out or for a quote). The checkout itself — fields, card, payment — is the platform's; color it with set_checkout_branding. To design EVERYTHING yourself — the product page and the checkout form too — bind the listing with the Storefront SDK (data-wakato-listing / data-wakato-field marks, Wakato.store, Wakato.checkout.quote / paymentField / pay): read get_storefront_sdk_reference first. clear:true reverts to the default card.

set_product_deliverable_files

Scope: commerce:write

REPLACE the paid files a digital product delivers after purchase (stored privately; buyers download through signed links on their order page and receipt). Each file: asset_id (a document in this space's asset library — upload_asset first) OR file_name + data_base64 (+ mime_type). Max 20 files, 50 MB each. Attaching files sets deliverable_type to 'download'. [] clears.

set_product_packages

Scope: commerce:write

SERVICES: offer tiered pricing (Basic / Standard / Premium) instead of one flat price — REPLACES the product's packages with this list (max 5, in order). Each: name, price (whole currency units), optional delivery_days, revisions, description, features[]. The listing then reads 'Packages from' the cheapest tier and buyers pick one at checkout. Pass [] to go back to a single price (then set price with update_product).

set_product_page_template

Scope: commerce:write

Design the product DETAIL PAGE. Every listed product automatically has a live page at /product/<product_id> (cards link to it with {{url}}) — this is the template it renders through: a full HTML document that is entirely YOURS (any <style>, classes, <script>, fonts, your site's own nav and footer). Same tokens as the card ({{id}} {{title}} {{price}} {{price_amount}} {{currency}} {{short_description}} {{image}} {{image_url}} {{rating}} {{rating_avg}} {{rating_count}} {{available}} {{buy_label}} {{buy_url}} {{checkout_attrs}} {{buy}}) plus {{description}} (the long description), {{images}} (full gallery), {{reviews}} (the review list) and {{product_json}} — every fact as JSON, variants included [{id, options, price, available, image_url}], for your own script: <script type="application/json" id="product">{{product_json}}</script>. Omit a token and that field doesn't show. BUYING: {{buy}}, your own element carrying {{checkout_attrs}} (add data-wakato-variant="<variant id>" for an option picked in your own picker), or from script Wakato.checkout("<id>", { variantId }). The checkout opens over the page, never a new tab; your page hears window events wakato:checkout-open, wakato:checkout-close and wakato:checkout-paid (detail.orderId). Pass tags to scope a layout to a CATEGORY (products carrying ALL those tags — e.g. tags:["men"]); no tags sets the space default. clear:true removes the default (or, with tags, that category's template). Without any template a clean built-in page renders. To design EVERYTHING yourself — the product page and the checkout form too — bind the listing with the Storefront SDK (data-wakato-listing / data-wakato-field marks, Wakato.store, Wakato.checkout.quote / paymentField / pay): read get_storefront_sdk_reference first.

set_product_profiles

Scope: commerce:write

Choose which of the business's Wakato profiles a product appears on (the profile page IS the storefront — a listing is live once attached to at least one public profile). REPLACE-SET: after this call the product shows on exactly profile_ids; [] detaches it everywhere and reverts it to draft. Profile ids from list_business_profiles.

set_product_resources

Scope: commerce:write

REPLACE a product's public Resources — the learn-more material in the listing's Resources tab (not the paid deliverable). Each: url (YouTube/Vimeo/mp4 → video, pdf/zip/image → file, else link; auto-detected unless resource_type is given), optional title and thumbnail_url (YouTube thumbnails and image URLs are picked up automatically). Upload files first with upload_asset and pass the returned URL. Max 30; [] clears.

set_product_variants

Scope: commerce:write

Define a product's options (e.g. Size, Color) and REPLACE its variants in one call. option_types is the axes [{name, values[]}]; variants is one entry per combination with options {axis:value}, inventory_quantity (null = untracked), sku, image_url, description (one line on what makes it different). A variant prices itself ONE of three ways: price (its own number in whole currency units — does NOT follow the base price), OR price_adjustment_kind 'amount'|'percent' + price_adjustment (base + that; FOLLOWS the base, so raising the listing price moves it too — prefer this for 'Large is $3 more'), OR neither (the base price). Both at once is refused. Send the FULL desired set each time (it replaces existing). Pass empty variants + null option_types to clear.

submit_community_product

Scope: commerce:write

List one of the business's products on a community's Products shelf. The seller must be an approved member of that community with listing rights (Sellers role or can_list_products); the submission lands pending and the community's own approval rules decide when it shows.

update_discount

Scope: commerce:write

Adjust a promo code: activate/deactivate (is_active), expiry, redemption caps, minimum. The amount itself is immutable — create a new code for a different discount so past redemptions stay truthful.

update_job

Scope: commerce:write

Edit a DRAFT job — same fields as create_job (client, title, scope, steps, stages, product_id). Once sent, use add_job_stage / set_job_steps / add_job_date instead.

update_job_date

Scope: commerce:write

Change a date on the job (date_id from get_job) — same fields as add_job_date.

update_payment_link

Scope: commerce:write

Edit a payment link's title/description/status (active|inactive|archived — inactive stops accepting money).

update_product

Scope: commerce:write

Edit a product: title, descriptions, price, images, tags, stock (inventory_quantity), shipping_fee_cents, status (draft|active|paused|archived) and is_published. To sell on this space's pages a product needs status:'active' AND is_published:true. A DRAFT is where the whole purchase is rehearsed (place_test_order) before anyone else can reach it — see the status field.

update_store_profile

Scope: commerce:write

Edit the store's business details: business_email (where buyer replies and receipts route), business_phone, business_address, business_description, business_website. Store name/logo/description shown on the storefront are update_store_presentation. Payouts, Stripe and verification are never reachable.

void_invoice

Scope: commerce:write

Void an unpaid invoice and deactivate its pay link so it stops accepting money.