---
updatedAt: 2026-07-07T16:22:25.000Z
agentTools:
  projectIndex: https://docs.envia.com/llms.txt
---

# Cancel a Shipment

Cancel an existing shipment and request a label refund from the carrier. The shipment must not have been picked up or entered the carrier network.

**When to use:** Call this endpoint when you need to void a previously generated label — for example, if the order was cancelled, the address is incorrect, or you need to regenerate the label with different details.

**Prerequisites:**
- Valid JWT authentication token (Bearer)
- The carrier identifier (e.g., `fedex`, `dhl`, `ups`)
- The tracking number of the shipment to cancel

**Key behaviors:**
- Returns a confirmation status indicating whether the cancellation was accepted by the carrier
- Refund processing times vary by carrier
- Some carriers only allow cancellation within a limited time window after label generation
- Labels that have already been scanned by the carrier cannot be cancelled

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Envia Shipping API — Complete Documentation",
    "version": "v2.3.0",
    "description": "Shipping API to connect with over 100 couriers worldwide. Shipping made simple for e-commerces and enterprises. Envia's Shipping Web Services offers solutions that applications can use to quote, create labels, request pickups, track packages, cancel shipments and many other logistics operations in USA, Mexico, Colombia, Brazil, India, Canada, Argentina, Chile, Guatemala, Spain, Italy and France. This API is built for e-commerce platforms, logistics teams, and enterprise applications that need a single integration to access multi-carrier shipping capabilities. Core features include real-time rate comparison, label generation, package tracking, pickup scheduling, shipment cancellation, and webhook-based event notifications.\n\n**Important Information:**\n- State codes must be 2 digits\n- Country codes must be 2 digits  \n- Validate the shipping address structure\n- Make sure the zip code or locality are correct\n\n**Custom Keys:** Custom Keys are used when you have a direct account with a carrier. This way you create labels with your rates with an additional small fee for service.",
    "contact": {
      "name": "Envia API Support",
      "url": "https://docs.envia.com/discuss"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.envia.com/terminos-y-condiciones"
    },
    "termsOfService": "https://www.envia.com/terminos-y-condiciones"
  },
  "externalDocs": {
    "description": "Full Envia API Documentation",
    "url": "https://docs.envia.com"
  },
  "servers": [
    {
      "url": "https://api-test.envia.com",
      "description": "Sandbox/Test"
    },
    {
      "url": "https://api.envia.com",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Cancel",
      "description": "Cancel shipments and request refunds"
    }
  ],
  "paths": {
    "/ship/cancel/": {
      "post": {
        "tags": [
          "Cancel"
        ],
        "summary": "Cancel a Shipment",
        "description": "Cancel an existing shipment and request a label refund from the carrier. The shipment must not have been picked up or entered the carrier network.\n\n**When to use:** Call this endpoint when you need to void a previously generated label — for example, if the order was cancelled, the address is incorrect, or you need to regenerate the label with different details.\n\n**Prerequisites:**\n- Valid JWT authentication token (Bearer)\n- The carrier identifier (e.g., `fedex`, `dhl`, `ups`)\n- The tracking number of the shipment to cancel\n\n**Key behaviors:**\n- Returns a confirmation status indicating whether the cancellation was accepted by the carrier\n- Refund processing times vary by carrier\n- Some carriers only allow cancellation within a limited time window after label generation\n- Labels that have already been scanned by the carrier cannot be cancelled",
        "operationId": "cancel-shipment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "carrier",
                  "trackingNumber"
                ],
                "properties": {
                  "carrier": {
                    "type": "string",
                    "description": "Name of the carrier",
                    "example": "fedex"
                  },
                  "trackingNumber": {
                    "type": "string",
                    "description": "Tracking number of the label",
                    "example": "7520610403"
                  },
                  "folio": {
                    "type": "string",
                    "description": "Reference id",
                    "example": "ENV-2026-001234"
                  },
                  "ecommerce": {
                    "type": "integer",
                    "description": "Ecommerce shop id",
                    "example": 0
                  }
                }
              },
              "example": {
                "carrier": "fedex",
                "trackingNumber": "788138721950"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful shipment cancellation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "string",
                      "default": "cancel",
                      "description": "Name of the action"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "carrier": {
                          "type": "string",
                          "description": "Carrier name",
                          "default": "ups"
                        },
                        "service": {
                          "type": "string",
                          "description": "Service name",
                          "default": "ground"
                        },
                        "trackingNumber": {
                          "type": "string",
                          "description": "Tracking number of the shipment",
                          "default": "123456789"
                        },
                        "folio": {
                          "type": "string",
                          "description": "Folio of the shipment"
                        },
                        "ecommerce": {
                          "type": "object",
                          "properties": {
                            "shop": {
                              "type": "string",
                              "description": "Shop identifier"
                            },
                            "order": {
                              "type": "string",
                              "description": "Order number"
                            },
                            "fulfillment": {
                              "type": "string",
                              "description": "Fulfillment identifier"
                            }
                          },
                          "description": "Only applies if the shipment was created from e-commerce"
                        },
                        "balanceReturned": {
                          "type": "boolean",
                          "enum": [
                            true,
                            false
                          ],
                          "description": "Indicates whether the refund was issued after cancellation",
                          "default": ""
                        },
                        "balanceReturnDate": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Indicates the date of the refund",
                          "default": "2025-10-01 12:31:00"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```