> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zuba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel an order

> Cancels an order that has not yet been approved for execution and returns any held funds to your balance. Once the desk has approved execution the order can no longer be cancelled. Retrying a successful cancel returns the cancelled order.



## OpenAPI

````yaml /openapi.json post /v1/orders/{id}/cancel
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Comprehensive payment platform API supporting fiat and crypto payments,
    currency conversion, and compliance management
  title: Zuba Payment Platform API
  version: '1.0'
servers: []
security: []
tags:
  - description: Manage M2M API keys and credentials
    name: API Keys
  - description: Internal ledger accounts and transactions
    name: Ledger
  - description: Handle incoming payments and deposits
    name: Pay-ins
  - description: Manage payouts, beneficiaries, and SEPA transfers
    name: Payouts
  - description: Manage outbound webhook endpoints and deliveries
    name: Webhooks
paths:
  /v1/orders/{id}/cancel:
    post:
      tags:
        - Orders
      summary: Cancel an order
      description: >-
        Cancels an order that has not yet been approved for execution and
        returns any held funds to your balance. Once the desk has approved
        execution the order can no longer be cancelled. Retrying a successful
        cancel returns the cancelled order.
      operationId: OrderController_cancelOrder
      parameters:
        - description: Order id
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseDto'
          description: The cancelled order
        '401':
          description: Missing or invalid auth token
        '403':
          description: insufficient_scope (missing create:orders)
        '404':
          description: Order not found
        '409':
          description: Order is already executing or terminal
      security:
        - bearer: []
components:
  schemas:
    OrderResponseDto:
      properties:
        beneficiaryId:
          description: Beneficiary id
          format: uuid
          type: string
        clientRef:
          description: Client-supplied reference
          type: string
        completedAt:
          description: When the order completed (ISO 8601)
          type: string
        createdAt:
          description: Creation time (ISO 8601)
          type: string
        executionDeadlineAt:
          description: Desk execution deadline, set when funds are received (ISO 8601)
          type: string
        failureReason:
          description: Fixed failure code; present only when status is failed
          enum:
            - execution_failed
            - review_expired
          type: string
        fromAmount:
          description: Total source debit, in fromCurrency (decimal string)
          example: '1006.5000'
          type: string
        fromCurrency:
          description: Funded (source) currency
          example: USDT
          type: string
        fundedAt:
          description: When funds were received (ISO 8601)
          type: string
        fundingDeadlineAt:
          description: >-
            Deadline for funds to be attributed to the order before it expires
            (ISO 8601)
          type: string
        id:
          description: Order id
          format: uuid
          type: string
        purpose:
          description: Free-text purpose
          type: string
        quoteId:
          description: Consumed quote id
          format: uuid
          type: string
        rate:
          description: 'All-in rate: fromCurrency per 1 toCurrency'
          example: '0.00067100'
          type: string
        status:
          description: >-
            Order lifecycle status. Orders are executed manually by the trade
            desk: funds_received means the order is queued for execution,
            executing means execution is approved and in flight, completed means
            delivered.
          enum:
            - created
            - awaiting_funds
            - funds_received
            - executing
            - completed
            - failed
            - expired
            - cancelled
          example: funds_received
          type: string
        toAmount:
          description: Amount delivered, in toCurrency (decimal string)
          example: '1500000.0000'
          type: string
        toCurrency:
          description: Delivered (target) currency
          example: NGN
          type: string
        uetr:
          description: >-
            Outbound wire reference (UETR); present once the order completes
            over a wire rail
          type: string
        updatedAt:
          description: Last update time (ISO 8601)
          type: string
        settlement:
          allOf:
            - $ref: '#/components/schemas/OrderSettlementDto'
          description: >-
            Funding instructions for an order created without sufficient
            balance; present while the order awaits funds and after matching
      required:
        - id
        - quoteId
        - beneficiaryId
        - status
        - fromCurrency
        - toCurrency
        - fromAmount
        - toAmount
        - rate
        - fundingDeadlineAt
        - createdAt
        - updatedAt
      type: object
    OrderSettlementDto:
      properties:
        settlementId:
          description: Settlement id
          format: uuid
          type: string
        method:
          description: >-
            Funding method: bank transfer to the account in the instructions, or
            a crypto transfer to your deposit address
          enum:
            - virtual_account
            - wallet_address
          type: string
        requiredAmount:
          description: >-
            Exact amount to transfer, in currency (decimal string). Transfers
            carrying the settlement reference attribute at any amount: a short
            payment sits on your balance until topped up, an overpayment
            attributes with the excess left on your balance. Without the
            reference, only a transfer of exactly this amount auto-matches;
            others are credited to your balance for manual attribution.
          example: '1006.5000'
          type: string
        currency:
          description: Currency of the transfer
          example: XOF
          type: string
        reference:
          description: >-
            Settlement reference; include it on the transfer narration where the
            rail supports one and the payment attributes to this order
            automatically
          example: SETTLE-4F7A2C91B0
          type: string
        status:
          description: Settlement state
          enum:
            - open
            - matched
            - expired
          type: string
        instructions:
          additionalProperties: true
          description: >-
            Funding instructions: bank account fields (virtual_account) or
            deposit addresses per network (wallet_address)
          type: object
        expiresAt:
          description: When the funding window closes (ISO 8601)
          type: string
      required:
        - settlementId
        - method
        - requiredAmount
        - currency
        - reference
        - status
        - instructions
        - expiresAt
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: Enter Auth0 JWT token
      scheme: bearer
      type: http

````