---
title: "Record an evaluated proposal under the run"
method: POST
path: "/v1/commerce/mcp/agent/runs/{id}/proposals"
---

# Record an evaluated proposal under the run

`POST /v1/commerce/mcp/agent/runs/{id}/proposals`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/commerce/mcp/agent/runs/{id}/proposals`
- Auth: HTTP bearer

A PROCEED must cite a dossier; every cited dossier is read from Core with the caller's credential and must belong to the organization and, where it carries a decision, agree with the recorded outcome. Each recorded proposal consumes one action; a PROCEED with an amount consumes exposure in the budget currency. Out-of-objective, out-of-scope, wrong-currency, expired or over-budget proposals are refused with a reason code, consume nothing, and close the run where a budget is exhausted. Recording never executes the proposal.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string, required

## Request body

- Proposal
  - `run_id` string, uuid, required
  - `action_type` 'PRICE_CHANGE' | 'INVENTORY_MUTATION' | 'ORDER_ACCEPTANCE' | 'FULFILLMENT_ACTION' | 'PROMOTION_CHANGE' | 'REFUND_REQUEST' | 'RETURN_AUTHORIZATION' | 'PAYMENT_RELEASE' | 'VENDOR_BANK_CHANGE' | 'EARLY_PAYMENT_DISCOUNT' | 'CREDIT_HOLD_RELEASE', required
  - `platform` string, required
  - `idempotency_key` string, required
  - `outcome` 'PROCEED' | 'HOLD' | 'ESCALATE' | 'BLOCK', required
  - `dossier_id` string, uuid, nullable, required
  - `amount` number, nullable, required
  - `currency` string, nullable, required
  - `resource_id` string
  - `cost` object
    - `provider` string
    - `model` string
    - `input_tokens` integer
    - `output_tokens` integer
    - `amount` number, nullable, required
    - `currency` string, nullable, required
  - `confirmation` unknown, required

## Response `200`

Validated bounded response; private, no-store

- ProposalReceipt
  - `version` 'commerce-agent-run-v1', required
  - `run_id` string, uuid, required
  - `proposal_id` string, uuid, nullable, required
  - `accepted` boolean, required
  - `replayed` boolean, required
  - `reason_code` 'RECORDED' | 'AGENT_RUN_NOT_ACTIVE' | 'AGENT_RUN_EXPIRED' | 'AGENT_RUN_ACTIONS_EXHAUSTED' | 'AGENT_RUN_EXPOSURE_EXHAUSTED' | 'AGENT_RUN_SCOPE_DENIED' | 'AGENT_RUN_PLATFORM_DENIED' | 'AGENT_RUN_CURRENCY_MISMATCH' | 'AGENT_RUN_COST_CURRENCY_MISMATCH', required
  - `agent_guidance` string, required
  - `run` object, required
    - `version` 'commerce-agent-run-v1', required
    - `run_id` string, uuid, required
    - `org_id` string, uuid, required
    - `state` 'active' | 'stopped' | 'exhausted' | 'expired', required
    - `objective` 'hold_margin_floor' | 'hold_inventory_floor' | 'review_orders' | 'review_refunds' | 'review_promotions' | 'release_payments', required
    - `allowed_action_types` string[], required
    - `scope` object, required
      - `platforms` string[], required
      - `skus` string[]
      - `order_ids` string[]
    - `agent` object, required
      - `id` string, required
    - `budget` object, required
      - `actions` object, required
        - `granted` integer, required
        - `used` integer, required
        - `remaining` integer, required
      - `exposure` object, required
        - `granted` number, required
        - `used` number, required
        - `remaining` number, required
        - `currency` string, required
    - `horizon` object, required
      - `started_at` string, date-time, required
      - `ends_at` string, date-time, required
    - `proposals` object, required
      - `count` integer, required
      - `by_outcome` object, required
        - `PROCEED` integer, required
        - `HOLD` integer, required
        - `ESCALATE` integer, required
        - `BLOCK` integer, required
      - `refused` integer, required
      - `recent` object[], required
        - `proposal_id` string, uuid, required
        - `action_type` 'PRICE_CHANGE' | 'INVENTORY_MUTATION' | 'ORDER_ACCEPTANCE' | 'FULFILLMENT_ACTION' | 'PROMOTION_CHANGE' | 'REFUND_REQUEST' | 'RETURN_AUTHORIZATION' | 'PAYMENT_RELEASE' | 'VENDOR_BANK_CHANGE' | 'EARLY_PAYMENT_DISCOUNT' | 'CREDIT_HOLD_RELEASE', required
        - `platform` string, required
        - `outcome` 'PROCEED' | 'HOLD' | 'ESCALATE' | 'BLOCK', required
        - `dossier_id` string, uuid, nullable, required
        - `amount` number, nullable, required
        - `recorded_at` string, date-time, required
    - `stop` object, nullable, required
      - `reason` string, required
      - `stopped_at` string, date-time, required
    - `agent_cost` object, required
      - `proposals` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `amount` number, required
      - `currency` string, nullable, required
    - `durability` 'process_memory' | 'backend_ledger', required
    - `execution_available` unknown, required
    - `no_downstream_action_executed` unknown, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `dossier_verification` 'none' | 'existence' | 'outcome'
  - `execution_available` unknown, required
  - `no_downstream_action_executed` unknown, required

## Other responses

- `400`: Malformed, unconfirmed, mismatched or dossier-less PROCEED input
- `401`: Missing or invalid credential
- `403`: Write scope, role or dossier access denied
- `404`: Feature disabled, run or dossier unavailable to this organization
- `409`: Rebound idempotency key or dossier mismatch; never automatically retry a write
- `413`: Request exceeds route byte limit
- `429`: Durable identity/IP limit exceeded; Retry-After supplied
- `503`: Authority, storage or evidence unavailable; completion may be unconfirmed

---

[API](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/revisions/9fecb7109bf8?raw)