Commands
Every store mutation is a typed, permission-scoped, audit-logged command on POST /v1/commands (ADR 0005). The admin UI, the CLI, extensions, and agents call the SAME commands 1:1: there is no privileged side channel. GET /v1/commands returns this list with JSON Schemas (scope-filtered for authenticated callers).
Envelope: { command, storeId, payload, idempotencyKey (26-char ULID), dryRun?, deferBump? }. Replays with the same key and payload return the original outcome; a different payload is an idempotency_conflict.
scope agents:admin
| command | summary | flags |
|---|---|---|
token.mint | Mint an access token for this store (Ajan = propose-only, Geliştirici = direct). Owner sessions only; the plaintext is returned once by POST /v1/tokens, never audited. | |
token.revoke | Revoke an access token immediately (its open proposal is withdrawn by the API layer). | destructive |
workspace.create | Create a named workspace (an agent's own hidden draft; optionally a hosted sandbox container). | |
workspace.archive | Archive a workspace: its tokens are revoked and (optionally) its draft discarded. Open proposals stay reviewable. | destructive |
scope catalog:write
| command | summary | flags |
|---|---|---|
catalog.category.create | Create a category (flat compliance taxonomy; taksitCap = BDDK installment cap). | |
catalog.category.update | Update a category's name, installment cap, or position. | |
catalog.category.archive | Archive a category (products keep their assignment; hidden from active lists). | destructive |
catalog.product.create | Create a product. price/compareAt in kuruş; stock null = untracked; handle derived from title when omitted. | bumps generation |
catalog.product.update | Patch product fields. Price and stock are NOT here: use catalog.price.set / catalog.stock.set. | bumps generation |
catalog.product.archive | Archive a product: removed from the storefront, history kept. | bumps generation, destructive |
catalog.price.set | Set the price (kuruş) of a product (prd_) or variant (var_). compareAt only on products; null clears it. Variant price null = inherit product price. | bumps generation |
catalog.stock.adjust | Adjust stock by a ± delta (receiving, stocktake, connector sync). Fails on untracked items; expectedStock = compare-and-set. | |
catalog.stock.set | Set stock of a product (prd_) or variant (var_). null = untracked (always available). | |
catalog.digital.codes.add | Add e-pin codes to a pooled digital product (sealed at rest; duplicates skipped). | |
catalog.digital.codes.void | Void unused pool codes (oldest first): they can never be allocated; nothing is deleted. | destructive |
catalog.product.setVariants | Wholesale-replace a product's variant STRUCTURE (order = array order). Existing variants update title/sku only; initial price/stock allowed solely for new variants. | bumps generation |
catalog.product.setMedia | Wholesale-replace a product's media list (order = array order; alt is per-usage). | bumps generation |
catalog.collection.create | Create a collection (handle derived from title when omitted). | bumps generation |
catalog.collection.update | Patch collection fields. | bumps generation |
catalog.collection.archive | Archive a collection: its page 404s; product memberships are kept. | bumps generation, destructive |
catalog.collection.setProducts | Wholesale-replace a collection's product list (order = array order = manual sort). | bumps generation |
catalog.media.commit | Commit a staged upload into the media library (variants generated async). | |
catalog.media.delete | Permanently delete an UNUSED media file (refused while referenced by catalog, live design, or the draft). | destructive |
channel.listing.set | Create/update marketplace listings for products or variants on a channel: enable, price/list overrides, price lock, buffer, mapping fields (bulk ≤500). | |
catalog.product.setDigital | Set a product's digital/shipping posture: requiresShipping, delivered digital content, withdrawal exception. | |
metafield.set | Set a metafield value on a product, variant, collection, or the store. | |
metafield.unset | Remove a metafield value. |
scope checkout
| command | summary | flags |
|---|---|---|
order.return.request | Open a return/withdrawal (shopper from the order page, or merchant recording a phone/e-mail notice). | |
order.return.cancel | Shopper withdraws their return request (only before the goods are received). | |
customer.identity.attach | Attach an order's customer to a Mozaik ID (explicit, shopper-initiated). | |
order.create | Create an order from a completed checkout session (server-internal; shopper actor). |
scope design:write
| command | summary | flags |
|---|---|---|
design.publish | Publish the current draft as the next live version (validates strictly; flips the live pointer). | |
design.rollback | Point the live site back at an earlier version (creates a new version entry; the draft is untouched). | destructive |
design.migrate | Republish the live version with its body migrated to the current bundle schema (new Sürümler entry; no content change). No-op when already current. | |
theme.install | Install a theme version for this store (first-party or a visible pack). Does not change the live look until a switch is published: except a newer first-party version re-pins the kit stylesheet the live site links (V1 S2). | bumps generation |
theme.uninstall | Remove an installed theme version. Refused while the live version, any draft/workspace or an open proposal references it. | destructive |
theme.switch | Switch the workspace draft to another installed theme (keep-layout or theme-skeleton): lossless: settings kept by id, sections parked never deleted; returns the Geçiş raporu. | |
theme.preset.apply | Apply one of the active theme's presets (Varyasyon) to the workspace draft: only the values the preset names change. | |
theme.page.reset | Replace one page (or header/footer) in the workspace draft with the active theme's skeleton for it. | destructive |
design.zone.place | Place (or reconfigure) an installed extension's storefront block in a zone of the workspace draft: the owner-driven 'Yerleştir'. | |
design.zone.remove | Remove an extension block from a storefront zone of the workspace draft. | |
design.extpage.add | Add an installed extension's page to the workspace draft under /ek/{slug} (owner-changeable path); the page renders the extension's composite through the active theme. | |
design.extpage.remove | Remove an extension page from the workspace draft (menu links to it are dropped). | destructive |
theme.push | Push a store-private SKIN theme (manifest + linted CSS + variables + presets + skeleton) from the CLI/sandbox: records the immutable pack, stores its stylesheet, installs the version. | |
theme.upgrade | Move the workspace draft to a newer version of its active theme: installs the version (kit css pin), applies the pack's migrations (renames) and the new defaults only to values the owner never touched, keeps everything else; returns the Geçiş raporu. Publishing stays a separate step. | bumps generation |
scope orders:write
| command | summary | flags |
|---|---|---|
order.ship | Create a shipment for an order's shippable lines (a cargo extension or a manual carrier): writes the VUK 509 forward fields. | |
order.shipment.track | Record a carrier state transition (webhook/poll/manual) and aggregate the order's fulfillment status. | |
order.shipment.cancel | Cancel a shipment before carrier handoff completes: resets the order to unfulfilled when nothing else is active. | destructive |
order.cod.collect | Record that the carrier's COD cash for a shipped/delivered order reached the merchant: order becomes paid. | |
order.note.add | Append a merchant note to an order's timeline. | |
order.return.approve | Approve a return: issues the instructions the shopper sees (snapshotted as evidence). | |
order.return.reject | Reject a return with a stated reason (the shopper mail carries the THH/consumer-court recourse). | destructive |
order.return.receive | Record the returned goods arriving: per-line condition; saleable lines restock (ledgered). | |
order.return.settle | Flip a return to refunded when its completed refunds cover the total (honest no-op otherwise). | |
order.line.epin.fulfill | Allocate newly-added pool codes to a paid order line that was left short (sweep-driven). | |
customer.identity.unlink | Clear a Mozaik ID pointer from this store's customers (revoke/erasure healing). | |
customer.anonymize | Anonymize a customer row (KVKK request): order snapshots stay under the statutory retention. | destructive |
order.import | Import a marketplace order (one per external order number) with its packages: paid, never refused for stock (oversold instead). | |
channel.package.upsert | Mirror a marketplace package (status, cargo, invoice, estimate/actual, supersession) onto its Mozaik order: runtime-issued. | |
order.transfer.confirm | Confirm a bank-transfer payment arrived: order becomes paid; digital content is released. | |
order.cancel | Cancel an unpaid order (pending_cod/awaiting_transfer): restocks lines. reason 'marketplace' cancels a paid marketplace order (the marketplace refunded the buyer); restock=false skips the restock. | destructive |
order.refund.request | Reserve a refund amount on a paid order (intent row = the PSP conversation anchor). | |
order.refund.record | Finalize a refund intent after the PSP call (ok releases/settles the reservation). |
scope proposals:approve
| command | summary | flags |
|---|---|---|
proposal.approve | Approve a submitted proposal and start applying its items in order (store owner only). | |
proposal.reject | Reject a proposal without applying anything (store owner only). | |
proposal.item.skip | Skip one item of a paused proposal (store owner only) so the rest can continue. |
scope proposals:write
| command | summary | flags |
|---|---|---|
proposal.submit | Submit an open proposal for the store owner's review (the owner is mailed a link). The proposalId comes from your first recorded mutation's response: or proposals.list. | |
proposal.withdraw | Withdraw a proposal that has not been applied. |
scope secrets:write
| command | summary | flags |
|---|---|---|
secret.set | Store or rotate a write-only credential (PSP keys). Values are never readable back. | |
secret.delete | Delete a stored credential. Extensions requiring it will refuse to enable until re-set. | destructive |
scope store:admin
| command | summary | flags |
|---|---|---|
store.syncKv | Re-project store state (t:, l:, live b:, g:) from Postgres to KV; bumps generation once. | bumps generation |
store.generation.set | Pin the store to a storefront generation (platform-driven after a MAJOR; the old generation keeps serving until then). Reversible: the pin routes, it never rewrites content. | bumps generation |
settings.store.update | Update store settings (display name). Projected to KV tenant records. | |
settings.identity.update | Set the legal merchant identity (6563 m.3): complete rows only; rendered live in the footer. | bumps generation |
settings.flag.set | Set or clear a store readiness flag (ETBİS beyanı, rehber kartları). | |
extension.install | Install an extension for this store (disabled until configured + enabled). Grants the manifest's scopes. | |
extension.uninstall | Uninstall a disabled extension. Config is archived in the audit row; secrets and data are kept. | bumps generation, destructive |
extension.upgrade | Upgrade an installed extension to the platform's current manifest version: re-validates (or migrates) the stored config; permission growth (new scopes / PII / required secrets) needs consent: true from the owner: the reconcile sweep applies only additive upgrades by itself. | bumps generation |
extension.enable | Enable an installed extension. Requires its secrets set and config valid. | bumps generation |
extension.disable | Disable an extension. Its payment method / hooks / panels stop immediately. Channel extensions with listings must state disconnect: 'zero' (push 0 everywhere first) or 'freeze' (leave marketplace stock as is). | bumps generation |
extension.configure | Set an extension's configuration (validated against its schema). Does not enable it. | bumps generation |
extension.hook.deactivate | Deactivate (or reactivate) an extension's hooks without disabling the extension. | |
settings.checkout.update | Update checkout legal settings: delivery estimate, return-cargo carrier/cost disclosure. | |
settings.stock.update | Update store-wide stock policy: default marketplace buffer, untracked quantity, restock-on-cancel/return, zero-when-archived. | |
settings.channel.update | Update one marketplace channel's policy: push/pull switches, price rule, buffer, resend window, disconnect and buyer-mail policy. | |
metafield.definition.create | Define a typed custom field on products, variants, collections, or the store. | |
metafield.definition.update | Update a metafield definition's label, description, or validations (type/key are immutable). | |
metafield.definition.delete | Delete a metafield definition AND every value stored under it. | bumps generation, destructive |
Generated from the live platform registries at build time: reference pages cannot go stale. Markdown variant: /reference/commands.md