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

# Cancel shipment

> Cancels a shipment. Use the `cancel` payload to mark the shipment as unscheduled so it can be re-shipped via another carrier or a manual method. Use the `cancel-and-refund` payload to cancel and simultaneously initiate a refund to the original payment instrument or a customer bank account.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-admin.json post /shipping/shipments/{reference_number}/cancel
openapi: 3.1.0
info:
  title: CE Admin APIs
  version: '1.0'
  summary: Comprehensive admin interface for managing your e-commerce platform
  description: >-
    Complete administrative API suite for Commerce Engine, providing powerful
    tools to manage products, orders, customers, inventory, analytics, and
    system configuration. Designed for administrators and backend integrations
    requiring full platform control.
  license:
    name: All Rights Reserved
    url: https://www.commercengine.io/contact-us
  contact:
    email: support@commercengine.io
    url: https://www.commercengine.io/contact-us
    name: Support
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/admin
    description: Staging Server
    variables:
      store_id:
        default: store_id
        description: Store ID
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/admin
    description: Prod Server
    variables:
      store_id:
        default: store_id
        description: Store ID
security:
  - Authorization: []
tags:
  - name: Analytics
    description: Analytics
  - name: Catalog
    description: Catalog
  - name: Coupons & promotions
    description: Coupons & promotions
  - name: Customers
    description: Customers
  - name: Filter Options
    description: Filter Options
  - name: Inventories
    description: Inventories
  - name: Marketplace
    description: Marketplace
  - name: Marketplace Catalog
    description: Marketplace Catalog
  - name: Media Gallery
    description: Media Gallery
  - name: Metrics
    description: Metrics
  - name: Orders
    description: Orders
  - name: Payments
    description: Payments
  - name: Payouts
    description: Payouts
  - name: POS
    description: POS
  - name: POSAdmin
    description: Admin endpoints to be used as proxy in pos
  - name: Segments
    description: Segments
  - name: Shipping
    description: Shipping
  - name: SSE
    description: SSE
  - name: Store
    description: Store
  - name: Webhooks
    description: Webhooks
paths:
  /shipping/shipments/{reference_number}/cancel:
    parameters:
      - name: reference_number
        in: path
        description: Shipment reference number
        required: true
        schema:
          type: string
    post:
      tags:
        - Shipping
      summary: Cancel shipment
      description: >-
        Cancels a shipment. Use the `cancel` payload to mark the shipment as
        unscheduled so it can be re-shipped via another carrier or a manual
        method. Use the `cancel-and-refund` payload to cancel and simultaneously
        initiate a refund to the original payment instrument or a customer bank
        account.
      operationId: cancel-shipment
      requestBody:
        content:
          application/json:
            schema:
              discriminator:
                propertyName: action
                mapping:
                  cancel:
                    $ref: '#/components/schemas/CancelShipment'
                  cancel-and-refund:
                    $ref: '#/components/schemas/CancelAndRefundShipment'
              oneOf:
                - $ref: '#/components/schemas/CancelShipment'
                - $ref: '#/components/schemas/CancelAndRefundShipment'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
components:
  schemas:
    CancelShipment:
      title: CancelShipment
      description: >-
        Cancel payload used when no refund is required. The shipment is marked
        as unscheduled and can be rescheduled with another carrier or fulfilled
        manually.
      type: object
      required:
        - action
        - reason
      properties:
        action:
          description: Set to `cancel` to cancel the shipment without issuing a refund.
          type: string
          const: cancel
        reason:
          description: >-
            Reason recorded against the cancellation for audit and customer
            communication.
          type: string
      x-tags:
        - Shipping
    CancelAndRefundShipment:
      title: CancelAndRefundShipment
      description: >-
        Cancel payload used when the shipment's payment must be refunded as part
        of the cancellation. The shipment is cancelled and a refund is initiated
        in the selected mode.
      type: object
      required:
        - action
        - refund_mode
      properties:
        action:
          description: >-
            Set to `cancel-and-refund` to cancel the shipment and initiate a
            refund.
          type: string
          const: cancel-and-refund
        reason:
          description: >-
            Reason recorded against the cancellation for audit and customer
            communication.
          type: string
        refund_amount:
          description: >-
            Optional partial refund amount. Omit to refund the full shipment
            amount.
          type: number
        refund_mode:
          description: >-
            How the refund is issued. Use `original-payment-mode` to refund back
            to the customer's original payment instrument, or `bank-transfer` to
            refund to a saved customer bank account.
          type: string
          enum:
            - original-payment-mode
            - bank-transfer
        bank_account_id:
          description: >-
            The customer bank account to credit. Required when `refund_mode` is
            `bank-transfer`; omit or set to `null` for `original-payment`.
          type:
            - string
            - 'null'
      x-tags:
        - Shipping
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````