<!-- Extension API v0 — pre-1.0. Interfaces may change without notice until P2 seals the custom-code format. First-party extensions track HEAD. -->

# 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`](/reference/commands/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`](/reference/commands/token.revoke) | Revoke an access token immediately (its open proposal is withdrawn by the API layer). | destructive |
| [`workspace.create`](/reference/commands/workspace.create) | Create a named workspace (an agent's own hidden draft; optionally a hosted sandbox container). |  |
| [`workspace.archive`](/reference/commands/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`](/reference/commands/catalog.category.create) | Create a category (flat compliance taxonomy; taksitCap = BDDK installment cap). |  |
| [`catalog.category.update`](/reference/commands/catalog.category.update) | Update a category's name, installment cap, or position. |  |
| [`catalog.category.archive`](/reference/commands/catalog.category.archive) | Archive a category (products keep their assignment; hidden from active lists). | destructive |
| [`catalog.product.create`](/reference/commands/catalog.product.create) | Create a product. price/compareAt in kuruş; stock null = untracked; handle derived from title when omitted. | bumps generation |
| [`catalog.product.update`](/reference/commands/catalog.product.update) | Patch product fields. Price and stock are NOT here — use catalog.price.set / catalog.stock.set. | bumps generation |
| [`catalog.product.archive`](/reference/commands/catalog.product.archive) | Archive a product — removed from the storefront, history kept. | bumps generation, destructive |
| [`catalog.price.set`](/reference/commands/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`](/reference/commands/catalog.stock.adjust) | Adjust stock by a ± delta (receiving, stocktake, connector sync). Fails on untracked items; expectedStock = compare-and-set. |  |
| [`catalog.stock.set`](/reference/commands/catalog.stock.set) | Set stock of a product (prd_) or variant (var_). null = untracked (always available). |  |
| [`catalog.digital.codes.add`](/reference/commands/catalog.digital.codes.add) | Add e-pin codes to a pooled digital product (sealed at rest; duplicates skipped). |  |
| [`catalog.digital.codes.void`](/reference/commands/catalog.digital.codes.void) | Void unused pool codes (oldest first) — they can never be allocated; nothing is deleted. | destructive |
| [`catalog.product.setVariants`](/reference/commands/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`](/reference/commands/catalog.product.setMedia) | Wholesale-replace a product's media list (order = array order; alt is per-usage). | bumps generation |
| [`catalog.collection.create`](/reference/commands/catalog.collection.create) | Create a collection (handle derived from title when omitted). | bumps generation |
| [`catalog.collection.update`](/reference/commands/catalog.collection.update) | Patch collection fields. | bumps generation |
| [`catalog.collection.archive`](/reference/commands/catalog.collection.archive) | Archive a collection — its page 404s; product memberships are kept. | bumps generation, destructive |
| [`catalog.collection.setProducts`](/reference/commands/catalog.collection.setProducts) | Wholesale-replace a collection's product list (order = array order = manual sort). | bumps generation |
| [`catalog.media.commit`](/reference/commands/catalog.media.commit) | Commit a staged upload into the media library (variants generated async). |  |
| [`catalog.media.delete`](/reference/commands/catalog.media.delete) | Permanently delete an UNUSED media file (refused while referenced by catalog, live design, or the draft). | destructive |
| [`catalog.product.setDigital`](/reference/commands/catalog.product.setDigital) | Set a product's digital/shipping posture: requiresShipping, delivered digital content, withdrawal exception. |  |
| [`metafield.set`](/reference/commands/metafield.set) | Set a metafield value on a product, variant, collection, or the store. | bumps generation |
| [`metafield.unset`](/reference/commands/metafield.unset) | Remove a metafield value. | bumps generation |

## scope `checkout`

| command | summary | flags |
|---|---|---|
| [`order.return.request`](/reference/commands/order.return.request) | Open a return/withdrawal (shopper from the order page, or merchant recording a phone/e-mail notice). |  |
| [`order.return.cancel`](/reference/commands/order.return.cancel) | Shopper withdraws their return request (only before the goods are received). |  |
| [`customer.identity.attach`](/reference/commands/customer.identity.attach) | Attach an order's customer to a Mozaik ID (explicit, shopper-initiated). |  |
| [`order.create`](/reference/commands/order.create) | Create an order from a completed checkout session (server-internal; shopper actor). |  |

## scope `design:write`

| command | summary | flags |
|---|---|---|
| [`design.publish`](/reference/commands/design.publish) | Publish the current draft as the next live version (validates strictly; flips the live pointer). |  |
| [`design.rollback`](/reference/commands/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`](/reference/commands/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`](/reference/commands/order.shipment.track) | Record a carrier state transition (webhook/poll/manual) and aggregate the order's fulfillment status. |  |
| [`order.shipment.cancel`](/reference/commands/order.shipment.cancel) | Cancel a shipment before carrier handoff completes — resets the order to unfulfilled when nothing else is active. | destructive |
| [`order.cod.collect`](/reference/commands/order.cod.collect) | Record that the carrier's COD cash for a shipped/delivered order reached the merchant — order becomes paid. |  |
| [`order.note.add`](/reference/commands/order.note.add) | Append a merchant note to an order's timeline. |  |
| [`order.return.approve`](/reference/commands/order.return.approve) | Approve a return — issues the instructions the shopper sees (snapshotted as evidence). |  |
| [`order.return.reject`](/reference/commands/order.return.reject) | Reject a return with a stated reason (the shopper mail carries the THH/consumer-court recourse). | destructive |
| [`order.return.receive`](/reference/commands/order.return.receive) | Record the returned goods arriving — per-line condition; saleable lines restock (ledgered). |  |
| [`order.return.settle`](/reference/commands/order.return.settle) | Flip a return to refunded when its completed refunds cover the total (honest no-op otherwise). |  |
| [`order.line.epin.fulfill`](/reference/commands/order.line.epin.fulfill) | Allocate newly-added pool codes to a paid order line that was left short (sweep-driven). |  |
| [`customer.identity.unlink`](/reference/commands/customer.identity.unlink) | Clear a Mozaik ID pointer from this store's customers (revoke/erasure healing). |  |
| [`customer.anonymize`](/reference/commands/customer.anonymize) | Anonymize a customer row (KVKK request) — order snapshots stay under the statutory retention. | destructive |
| [`order.transfer.confirm`](/reference/commands/order.transfer.confirm) | Confirm a bank-transfer payment arrived — order becomes paid; digital content is released. |  |
| [`order.cancel`](/reference/commands/order.cancel) | Cancel an unpaid order (pending_cod/awaiting_transfer) — restocks lines. | destructive |
| [`order.refund.request`](/reference/commands/order.refund.request) | Reserve a refund amount on a paid order (intent row = the PSP conversation anchor). |  |
| [`order.refund.record`](/reference/commands/order.refund.record) | Finalize a refund intent after the PSP call (ok releases/settles the reservation). |  |

## scope `proposals:approve`

| command | summary | flags |
|---|---|---|
| [`proposal.approve`](/reference/commands/proposal.approve) | Approve a submitted proposal and start applying its items in order (store owner only). |  |
| [`proposal.reject`](/reference/commands/proposal.reject) | Reject a proposal without applying anything (store owner only). |  |
| [`proposal.item.skip`](/reference/commands/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`](/reference/commands/proposal.submit) | Submit an open proposal for the store owner's review (the owner is mailed a link). |  |
| [`proposal.withdraw`](/reference/commands/proposal.withdraw) | Withdraw a proposal that has not been applied. |  |

## scope `secrets:write`

| command | summary | flags |
|---|---|---|
| [`secret.set`](/reference/commands/secret.set) | Store or rotate a write-only credential (PSP keys). Values are never readable back. |  |
| [`secret.delete`](/reference/commands/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`](/reference/commands/store.syncKv) | Re-project store state (t:, l:, live b:, g:) from Postgres to KV; bumps generation once. | bumps generation |
| [`settings.store.update`](/reference/commands/settings.store.update) | Update store settings (display name). Projected to KV tenant records. |  |
| [`settings.identity.update`](/reference/commands/settings.identity.update) | Set the legal merchant identity (6563 m.3) — complete rows only; rendered live in the footer. | bumps generation |
| [`settings.flag.set`](/reference/commands/settings.flag.set) | Set or clear a store readiness flag (ETBİS beyanı, rehber kartları). |  |
| [`extension.install`](/reference/commands/extension.install) | Install an extension for this store (disabled until configured + enabled). Grants the manifest's scopes. |  |
| [`extension.uninstall`](/reference/commands/extension.uninstall) | Uninstall a disabled extension. Config is archived in the audit row; secrets and data are kept. | bumps generation, destructive |
| [`extension.upgrade`](/reference/commands/extension.upgrade) | Upgrade an installed extension to the platform's current manifest version. | bumps generation |
| [`extension.enable`](/reference/commands/extension.enable) | Enable an installed extension. Requires its secrets set and config valid. | bumps generation |
| [`extension.disable`](/reference/commands/extension.disable) | Disable an extension. Its payment method / hooks / panels stop immediately. | bumps generation |
| [`extension.configure`](/reference/commands/extension.configure) | Set an extension's configuration (validated against its schema). Does not enable it. | bumps generation |
| [`extension.hook.deactivate`](/reference/commands/extension.hook.deactivate) | Deactivate (or reactivate) an extension's hooks without disabling the extension. |  |
| [`settings.checkout.update`](/reference/commands/settings.checkout.update) | Update checkout legal settings: delivery estimate, return-cargo carrier/cost disclosure. |  |
| [`metafield.definition.create`](/reference/commands/metafield.definition.create) | Define a typed custom field on products, variants, collections, or the store. |  |
| [`metafield.definition.update`](/reference/commands/metafield.definition.update) | Update a metafield definition's label, description, or validations (type/key are immutable). |  |
| [`metafield.definition.delete`](/reference/commands/metafield.definition.delete) | Delete a metafield definition AND every value stored under it. | bumps generation, destructive |