---
title: "Record one tenant-bound commerce action evaluation in Shadow Mode"
method: POST
path: "/v1/protocol/evaluate-decision"
---

# Record one tenant-bound commerce action evaluation in Shadow Mode

`POST /v1/protocol/evaluate-decision`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/protocol/evaluate-decision`
- Auth: HTTP bearer

The Commerce Gate MCP always submits SHADOW and requires the response to confirm SHADOW. `commercegate_evaluate_action` accepts all eleven canonical commerce action types: the seven published families and the four finance families (payment release, vendor bank change, early-payment discount and credit-hold release) of the unreleased commerce-preflight-v2 source candidate, which require a matching backend and never move money. For the live Walmart Marketplace connector, Commerce Evaluation, Price Guard, Order Guard, order interception, margin protection, release, hold, and cancel map to those canonical preflights. Order acceptance and price change use native margin mappings; inventory, fulfillment, promotion, refund, and return are generic Protocol evaluations whose outcome depends on the tenant policy and supplied signals. The unreleased commerce-preflight-v2 opt-in adds sixteen explicit policy checks with a matching backend and a server-owned policy bundle. It binds the result to the action, facts, policy version and idempotency key; missing required facts or unsupported checks hold the proposal. The candidate Commerce /aws facade preserves the original action/result key through its separately authenticated commerce-preflight-transport-v1 retry namespace. Its context.commerce_preflight_transport marker is reserved service metadata, not a tool argument. This does not establish hosted availability. It does not add native execution paths. `commercegate_evaluate_marketplace_offer_submission` accepts a separate, bounded Microsoft Partner Center or AWS Marketplace SaaS offer packet with digest-bound release evidence. Either evaluation can create decision evidence but never executes a marketplace action or submits an offer.

## Headers

- `Idempotency-Key` string, required

## Request body

- union
  - CommerceEvaluationRequest
    - `org_id` string, uuid, nullable, required: Organization bound to configured or privately stored access. The Commerce Gate MCP sends null so the API derives the tenant from that credential.
    - `decision_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
    - `transaction_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
    - `workflow_key` 'commerce_price_change' | 'commerce_inventory_mutation' | 'commerce_order_acceptance' | 'commerce_fulfillment_action' | 'commerce_promotion_change' | 'commerce_refund_request' | 'commerce_return_authorization' | 'commerce_payment_release' | 'commerce_vendor_bank_change' | 'commerce_early_payment_discount' | 'commerce_credit_hold_release', required
    - `amount` number: Monetary action amount. Omitted for non-monetary actions.
    - `channel` 'mcp' | 'repricer' | 'erp' | 'workflow' | 'api', required: Who is asking. The Commerce Gate MCP sends mcp; a repricer, ERP job, workflow or direct API integration names itself so the dossier records the actor.
    - `source` string, required: The tool asking, for the dossier: commercegate-mcp for the MCP, or the name of your repricer, ERP or workflow.
    - `mode` 'SHADOW', required
    - `idempotency_key` string, required
    - `policy_version` string
    - `require_exact_policy_version` true
    - `agent_attribution` object: What the calling agent reported about producing the action. Decionis records it on the Decision Dossier as client-reported and unverified; it is never a policy fact and never changes the answer. Sent only when the agent supplies it.
      - `agent_id` string
      - `provider` string
      - `model` string
      - `input_tokens` integer
      - `output_tokens` integer
      - `reported_cost` object
        - `amount` number, required
        - `currency` string, required
    - `context` object, required: Bounded normalized action, derived commerce facts, and a nested signals object used by Commerce policies (for example signals.net_margin_percent for a price change). Generic Shadow evaluation does not assert that a connected platform can execute the action.
      - `commerce_action` union
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'PRICE_CHANGE', required
          - `payload` object, required
            - `sku` string, required
            - `from_price` number, nullable, required
            - `to_price` number, required
            - `estimated_cost` number, nullable
            - `currency` string
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'INVENTORY_MUTATION', required
          - `payload` object, required
            - `sku` string, required
            - `from` integer, nullable, required
            - `to` integer, required
            - `location_id` string, nullable
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'ORDER_ACCEPTANCE', required
          - `payload` object, required
            - `order_id` string, nullable, required
            - `gross_amount` number, required
            - `discount_amount` number, required
            - `estimated_cost` number, required
            - `currency` string
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'FULFILLMENT_ACTION', required
          - `payload` object, required
            - `order_id` string, required
            - `action` 'acknowledge' | 'ship' | 'cancel' | 'hold', required
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'PROMOTION_CHANGE', required
          - `payload` object, required
            - `promotion_id` string, nullable, required
            - `percentage_fraction` number, nullable, required
            - `ends_at` string, date-time, nullable, required
            - `status` string, nullable, required
            - `combines_with` object, nullable, required
              - …
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'REFUND_REQUEST', required
          - `payload` object, required
            - `order_id` string, required
            - `amount` number, required
            - `currency` string
            - `reason_code` string, nullable
            - `remaining_refundable` number
            - `prior_refund_count` integer
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'RETURN_AUTHORIZATION', required
          - `payload` object, required
            - `order_id` string, required
            - `rma_id` string, nullable
            - `amount` number, nullable
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'PAYMENT_RELEASE', required
          - `payload` object, required
            - `payment_id` string, required
            - `vendor_id` string, required
            - `invoice_id` string
            - `amount` number, required
            - `currency` string, required
            - `due_at` string, date-time
            - `rail` 'ach' | 'wire' | 'card' | 'stablecoin' | 'other'
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'VENDOR_BANK_CHANGE', required
          - `payload` object, required
            - `vendor_id` string, required
            - `change_id` string, required
            - `account_hash` string, required
            - `account_last4` string, required
            - `previous_account_hash` string
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'EARLY_PAYMENT_DISCOUNT', required
          - `payload` object, required
            - `payment_id` string, required
            - `vendor_id` string, required
            - `amount` number, required
            - `currency` string, required
            - `discount_percent` number, required
            - `days_early` integer, required
        - object
          - `actor` object, required
            - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
            - `id` string, required
          - `platform` string, required
          - `idempotency_key` string, required
          - `action_type` 'CREDIT_HOLD_RELEASE', required
          - `payload` object, required
            - `customer_id` string, required
            - `order_id` string
            - `amount` number, required
            - `currency` string, required
            - `exposure_after_release` number
      - `commerce_preflight` CommercePreflightInput
        - `version` 'commerce-preflight-v2', required
        - `facts` object, required
          - `observed_at` string, date-time
          - `source` string
          - `currency` string
          - `pricing` object
            - `gross_amount` number
            - `discount_amount` number
            - `estimated_cost` number
          - `cost_basis` object
            - `source_cost` number
            - `system_of_record_cost` number
          - `inventory` object
            - `source_on_hand` integer
            - `system_on_hand` integer
            - `reserved_quantity` integer
            - `requested_quantity` integer
          - `region` object
            - `country` string
          - `discounts` object
            - `count` integer
            - `sources` string[]
          - `contract` object
            - `account_type` 'retail' | 'b2b'
            - `offered_price` number
            - `contract_price` number
          - `promotion` object
            - `discount_codes` string[]
            - `prior_redemptions` integer
            - `account_age_days` number
            - `identity_hash` string
          - `refund` object
            - `remaining_refundable` number
            - `prior_refund_count` integer
          - `lifecycle` object
            - `current_state` 'created' | 'acknowledged' | 'shipped' | 'delivered' | 'cancelled' | 'refunded' | 'return_authorized' | 'returned'
            - `delivered_at` string, date-time
            - `return_eligible` boolean
          - `payment` object
            - `prior_payment_count` integer
            - `approver_authority_limit` number
          - `beneficiary` object
            - `changed_at` string, date-time, nullable
            - `verification` 'verified' | 'unverified' | 'pending'
          - `treasury` object
            - `cash_position` number
            - `run_total` number
            - `cost_of_funds_percent` number
  - MarketplaceOfferSubmissionPreflightRequest
    - `org_id` string, uuid, nullable, required: Organization bound to configured or privately stored access. The Commerce Gate MCP sends null so the API derives the tenant from that credential.
    - `decision_type` 'MARKETPLACE_OFFER_SUBMISSION', required
    - `transaction_type` 'marketplace_offer_submission', required
    - `workflow_key` 'commerce_marketplace_offer_submission', required
    - `channel` 'mcp', required
    - `source` 'commercegate-mcp', required
    - `mode` 'SHADOW', required
    - `idempotency_key` string, required
    - `policy_version` string
    - `require_exact_policy_version` true
    - `context` object, required: The client records the strict submission packet plus derived facts and signals. The packet carries no credentials and does not grant write access to a marketplace.
      - `submission` MarketplaceOfferSubmissionPacket, required
        - `actor` object, required
          - `type` 'HUMAN' | 'ERP' | 'REPRICER' | 'WORKFLOW' | 'AGENT' | 'UNKNOWN', required
          - `id` string, required
        - `marketplace` 'MICROSOFT_PARTNER_CENTER' | 'AWS_MARKETPLACE', required
        - `publisher_id` string, required
        - `offer_id` string, required
        - `offer_name` string, required
        - `offer_type` 'SAAS', required
        - `idempotency_key` string, required
        - `plans` object[], required
          - `plan_id` string, required
          - `display_name` string, required
          - `billing_term` 'MONTHLY' | 'ANNUAL' | 'ONE_TIME', required
          - `markets` string[], required
        - `landing_page_url` string, uri, required: Public HTTPS URL with no embedded credentials, query parameters, or fragment. The MCP parser enforces those URL restrictions before sending the request.
        - `connection_webhook_url` string, uri, required: Public HTTPS URL with no embedded credentials, query parameters, or fragment. The MCP parser enforces those URL restrictions before sending the request.
        - `support_url` string, uri, required: Public HTTPS URL with no embedded credentials, query parameters, or fragment. The MCP parser enforces those URL restrictions before sending the request.
        - `privacy_policy_url` string, uri, required: Public HTTPS URL with no embedded credentials, query parameters, or fragment. The MCP parser enforces those URL restrictions before sending the request.
        - `terms_of_use_url` string, uri, required: Public HTTPS URL with no embedded credentials, query parameters, or fragment. The MCP parser enforces those URL restrictions before sending the request.
        - `marketplace_identity` union, required: Microsoft Partner Center requires an Entra tenant and application identity. AWS Marketplace requires a Login with Amazon subject linked to the seller AWS account and IAM role with offer-management access. The MCP validates that the identity matches the chosen marketplace and never exchanges its credentials.
          - object
            - `provider` 'MICROSOFT_ENTRA', required
            - `tenant_id` string, uuid, required
            - `application_id` string, uuid, required
          - object
            - `provider` 'LOGIN_WITH_AMAZON', required
            - `subject` string, required
            - `aws_account_id` string, required
            - `aws_iam_role_arn` string, required
            - `seller_offer_access_verified` true, required
        - `business_central_extension` object
          - `app_id` string, uuid, required
          - `version` string, required
        - `release_evidence` MarketplaceOfferReleaseEvidence, required
          - `marketplace_draft_status` 'READY_TO_PUBLISH', required
          - `offer_listing_verified` true, required
          - `technical_configuration_verified` true, required
          - `preview_or_test_verified` true, required
          - `marketplace_identity_verified` true, required
          - `submission_payload_sha256` string, required
          - `release_evidence_sha256` string, required

## Response `200`

Shadow Mode evaluation and evidence references

- CommerceEvaluationResponse
  - `commerce_preflight` CommercePreflightResult
    - `version` 'commerce-preflight-v2', 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
    - `action_digest` string, required
    - `facts_digest` string, required
    - `policy_version` string, required
    - `idempotency_key` string, required
    - `evaluated_at` string, date-time, required
    - `disposition` 'PROCEED' | 'HOLD' | 'BLOCK', required
    - `execution_available` false, required
    - `checks` object[], required
      - `id` 'P01' | 'P02' | 'P03' | 'P04' | 'P05' | 'P06' | 'P07' | 'P08' | 'P09' | 'P10' | 'P11' | 'P12' | 'P13' | 'P14' | 'P15' | 'P16', required
      - `status` 'evaluated' | 'not_applicable' | 'disabled' | 'missing_facts' | 'unsupported', required
      - `verdict` 'PROCEED' | 'HOLD' | 'BLOCK', nullable, required
      - `reason_codes` string[], required
      - `missing_facts` string[], required
      - `measurements` object
  - `policy_evaluation` object
    - `commerce_preflight` CommercePreflightResult
      - `version` 'commerce-preflight-v2', 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
      - `action_digest` string, required
      - `facts_digest` string, required
      - `policy_version` string, required
      - `idempotency_key` string, required
      - `evaluated_at` string, date-time, required
      - `disposition` 'PROCEED' | 'HOLD' | 'BLOCK', required
      - `execution_available` false, required
      - `checks` object[], required
        - `id` 'P01' | 'P02' | 'P03' | 'P04' | 'P05' | 'P06' | 'P07' | 'P08' | 'P09' | 'P10' | 'P11' | 'P12' | 'P13' | 'P14' | 'P15' | 'P16', required
        - `status` 'evaluated' | 'not_applicable' | 'disabled' | 'missing_facts' | 'unsupported', required
        - `verdict` 'PROCEED' | 'HOLD' | 'BLOCK', nullable, required
        - `reason_codes` string[], required
        - `missing_facts` string[], required
        - `measurements` object
  - `mode` 'SHADOW', required
  - `outcome` 'APPROVE' | 'REJECT' | 'REVIEW' | 'ESCALATE', required
  - `confidence` number, required
  - `policy_version` string, required
  - `objective_profile` string, required
  - `dossier_id` string, uuid, required
  - `evaluation_id` string, uuid, required
  - `reason_codes` string[]
  - `fallback_to_legacy` boolean, required
  - `governance_metrics` CommerceGovernanceMetrics, required
    - `override_drift_rate` number, required
    - `governance_tension_index` number, required
    - `boundary_volatility_score` number, required
    - `decision_volume_under_governance` number, required
  - `idempotent_replay` boolean, required

## Other responses

- `400`: Bounded error response
- `401`: Bounded error response
- `403`: Bounded error response
- `409`: Bounded error response
- `422`: Bounded error response
- `429`: Bounded error response
- `500`: Bounded error response
- `503`: Bounded error response

---

[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)