order.refund

Refund a paid order IN FULL through its payment provider, recording the movement on the ledger in the same transaction. v1 is total-only and post-capture; a provider error fails the command (nothing is recorded). Does NOT change the order status. When honouring a customer cancellation, refund FIRST and cancel after — the reverse order leaves the order cancelled with the money still held.

• Scope: order.write
• System: no
• Reachable from: POST /v1/commands/order.refund (tenant credential) · MCP tool order.refund · SDK client.call('order.refund', …)
• Events: order.refunded

Input (JSON Schema)

{
  "properties": {
    "order_id": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "type": "object"
}

Result (200)

{
  "additionalProperties": false,
  "properties": {
    "authorized": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "captured": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "order_id": {
      "type": "string"
    },
    "payment_status": {
      "enum": [
        "not_paid",
        "partially_authorized",
        "partially_paid",
        "paid",
        "partially_refunded",
        "refunded"
      ],
      "type": "string"
    },
    "refunded": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "total_amount": {
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "transaction_id": {
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "transaction_id",
    "payment_status",
    "captured",
    "authorized",
    "refunded",
    "total_amount"
  ],
  "type": "object"
}

Errors

validation_failed (400) · unauthorized (401) · forbidden (403) · conflict (409) · internal (500)