# Cancel Shipment

This operation cancels or voids a shipment label that has not been processed by the carrier. When you cancel an unused prepaid shipment label, the API initiates a request for an electronic refund.<br>
**Key Considerations**
- Cancelation must occur before the shipment is picked up or processed by the carrier.
- Refunds are only applicable for unused labels. Voiding a used label may result in penalties or billing.<br>
- **USPS**:
  - Cancel unused USPS prepaid labels within 30 days of printing to start the refund process.
  - Refund requests are processed within 14 business days from the date the refund was requested, provided the label has not been used.
  - Approved refunds are automatically credited to the account you used to pay for the label.
  - **Note**: USPS considers it a federal offense to induct a label that has already been refunded.
  - **Note**: Refunds are not available for First-Class Mail letters and flats.
  - **Note**: Refunds are subject to the policies of the applicable carrier.
- For unused post-paid labels, you must void them. Voiding avoids billing for the label and allows the carrier to maintain an accurate count for pickups.
- Always destroy voided labels to prevent accidental use. If a voided label is shipped, you will be billed for the label.
- Once a refund has been claimed, you cannot use the shipping label for sending packages. It will be rejected.<br/>

**Shipment Cancelation Rules**
- Provide either `shipmentId` or `parcelTrackingNumber` to cancel a shipment.
- If both are provided, `shipmentId` takes precedence and `parcelTrackingNumber` is ignored.
- If only `parcelTrackingNumber` is provided, the shipment associated with that parcel tracking number is canceled.

Endpoint: POST /api/v2/shipments/cancel
Version: 1.0.0
Security: bearerAuth

## Header parameters:

  - `X-PB-Developer-Partner-Id` (string)
    The Developer Partner ID is assigned by PB to uniquely identify a Developer's strategic business partners. If the developer is the sole business partner, this field isn't required.

  - `X-PB-LocationId` (string)
    The X-PB-LocationId header identifies the enterprise, developer, or partner location under which a shipment is processed and billed.
If the header is not provided, the system defaults to the enterprise-level location that was created during developer account onboarding. This default location is automatically used for shipment processing and billing.<br/>

**Requirement Rules**

- The `X-PB-LocationId` header is optional when the shipment origin country code matches the enterprise's default address country code.
- The `X-PB-LocationId` header is required when the shipment origin country code differs from the enterprise's default address country code.
- If the header is required but not provided, the API will return a validation error *"invalid origin countryCode"*.

  - `X-PB-TransactionId` (string)
    A unique Transaction ID provided by the partner which is used to enable debugging and linking between the client's transaction and the system.

## Request fields (application/json):

  - `shipmentId` (string)
    The shipmentId is a unique identifier for an individual Shipment.
    Example: PUROLATOR2200626353009030

  - `parcelTrackingNumber` (string)
    The tracking number associated with one parcel in a shipment. The parcel tracking number can be used to track one specific parcel.
    Example: 1234sjhgf

  - `references` (object)
    Contains key value map for passing references which is printed on Shipping Label. For example Department Name, Invoice No., PO No., Package description, Order No./ Purchase Order No., Carrier note, Cost Account No., Transportation No., etc. . Max references allowed here is 2, and max length of each Reference field is 30. [IN/OUT].

  - `references.additionalReference1` (string)
    Additional Reference is hardly used, but sender can mention anything as per requirement, just for Recipient's information.  `Max length = 30`.
    Example: 612987641

  - `references.additionalReference2` (string)
    Any tags or information that to be shown to Recipient, can be mentioned by Sender, which is not indicated on AdditionalReference1 field, e.g., PO No, Order No. etc. `Max length = 30`.
    Example: 989

## Response 200 fields (application/json):

  - `carrier` (string)
    The name of the Carrier.
    Example: USPS

  - `totalCarrierCharge` (number)
    The total amount payable to the carrier, including special service fees, surcharges, and any international taxes and duties.
    Example: 0

  - `parcelTrackingNumber` (string)
    The Tracking number given to the Parcel for tracking purpose.
    Example: 9471309105156000624885

  - `status` (string)
    Status of the Shipment.
    Enum: "INITIATED", "APPROVED"

  - `references` (object)
    Contains key value map for passing references which is printed on Shipping Label. For example Department Name, Invoice No., PO No., Package description, Order No./ Purchase Order No., Carrier note, Cost Account No., Transportation No., etc. . Max references allowed here is 2.

  - `references.additionalReference1` (string)
    Additional Reference is hardly used, but sender can mention anything as per requirement, just for Recipient's information.  `Max length = 30`.
    Example: 612987641

  - `references.additionalReference2` (string)
    Any tags or information that to be shown to Recipient, can be mentioned by Sender, which is not indicated on AdditionalReference1 field, e.g., PO No, Order No. etc. `Max length = 30`.
    Example: 989

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g., validation-error.
    Example: validation_error

  - `errorDescription` (string)
    The HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
    Example: string

  - `additionalCode` (string)
    A unique identifier for the error, for example 1101055, 0100008, or 1021126.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceID, or if the information is missing.

  - `additionalParameters` (array)

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.

## Response 404 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due HTTP 404 Page or File not found.
    Example: not_found

  - `errorDescription` (string)
    The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.
    Example: resource not found

  - `additionalCode` (string)
    A unique identifier for the error, for example 0100025, 1110017, or 1090001.

  - `additionalInfo` (string)
    Additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`.

  - `additionalParameters` (array)

## Response 500 fields (application/json):

  - `message` (string, required)
    This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.