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 |
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. | bumps generation |
metafield.unset | Remove a metafield value. | bumps generation |
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 |
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.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. | 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). | |
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 |
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. | 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. | 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. | |
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