Cancel Order

Required scope: order:cancel

Cancels a confirmed order and, when refundAmountMinor is greater than zero, issues a refund against the order’s payments. Preview the financial impact with GetOrderCancellationImpact first. Amounts are integer minor currency units.

expectedVersion is the version the caller last observed; a mismatch is rejected (optimistic concurrency). When a refund is requested, refundRequestId must be a UUID and makes the refund leg idempotent — reusing it returns the original refund rather than issuing a second one. The cancellation itself is a state transition; re-cancelling an order that is not in a cancellable state fails.

Generated Reference

POST /public-api/publicapi.v1.Order/CancelOrder

Cancels an order and optionally issues a refund up to the refundable amount. Guarded by expected_version; the refund leg is idempotent per refund_request_id.

Request CancelOrderRequest

Response CancelOrderResponse

CancelOrderRequest

Field	Type	Description
`order_id`	`string`	Stable identifier of the order to cancel.
`reason`	`string`	Human-readable cancellation reason.
`expected_version`	`int32`	Version the caller last observed, for optimistic concurrency.
`refund_amount_minor`	`optional int64`	Amount to refund in minor currency units. Zero or omitted issues no refund.
`refund_request_id`	`string`	Idempotency key for the refund leg. Required when refund_amount_minor > 0.

CancelOrderResponse

Field	Type	Description
`order`	`Order`	The order after cancellation.
`refunds`	`repeated OrderCancellationRefund`	Refunds issued as part of the cancellation, including any that failed.

Related Types

Order

Field	Type
`id`	`string`
`customer_id`	`string`
`quote_id`	`optional string`
`status`	`OrderStatus`
`reference_number`	`string`
`version`	`int32`
`items`	`repeated OrderItem`
`finalized_at`	`int64`
`created_at`	`int64`
`updated_at`	`int64`
`cancelled_at`	`int64`
`cancel_reason`	`string`
`pricing_country`	`string`
`currency`	`string`

OrderCancellationRefund

Field	Type	Description
`payment_id`	`string`	Payment the refund was issued against.
`refund_id`	`string`	Identifier of the created refund.
`amount_minor`	`int64`	Refunded amount in minor currency units.
`status`	`string`	Provider-neutral refund status.
`failed`	`bool`	True when this refund leg failed.

OrderItem

Field	Type
`product_id`	`string`
`quantity`	`int32`
`line_id`	`string`
`display_name`	`string`
`price_once`	`optional int32`
`price_monthly`	`optional int32`
`price_yearly`	`optional int32`
`currency`	`string`

Request

{
  "orderId": "<order-id>",
  "reason": "Customer withdrew",
  "expectedVersion": 1,
  "refundAmountMinor": "50000",
  "refundRequestId": "<uuid>"
}

Omit refundAmountMinor (or send 0) to cancel without a refund; leave refundRequestId empty in that case.

Response

{
  "order": { "id": "<order-id>", "status": "PUBLIC_ORDER_STATUS_CANCELLED", "version": 2 },
  "refunds": [
    {
      "paymentId": "<payment-id>",
      "refundId": "<refund-id>",
      "amountMinor": "50000",
      "status": "PUBLIC_REFUND_STATUS_PENDING",
      "failed": false
    }
  ]
}