Canada Post Void/Cancel errors (Related to #682) #731

[danh91]

@minchaminder

The current Canada Post cancellation process appears to be broken. When Canada Post returns an empty message, Karrio incorrectly interprets it as a successful cancellation.

Example of Empty Message:

<?xml version="1.0" encoding="UTF-8"?><messages xmlns="http://www.canadapost.ca/ws/messages"/>

---

Context

For contract shipping, Canada Post provides two types of cancellation processes:

1. Void a shipment: Cancels a shipment that has not yet been manifested.
2. Request a shipment refund: Cancels a shipment that has already been manifested but not shipped.

For non-contract shipping, the cancellation process may differ, and Karrio needs to account for this difference. Non-contract shipments do not rely on manifests, so the logic should handle direct refund requests for these shipments.

---

Contract Shipping Scenarios

Scenario 1: Void a Shipment (Unmanifested)

• Void a Shipment (Scenario 1): [API Docs](https://www.canadapost-postescanada.ca/info/mc/business/productsservices/developers/services/shippingmanifest/voidshipment.jsf)

The process to void a shipment involves the following steps:

1. Retrieve the shipment ID:
   Call the following endpoint to get the shipment URL (including the shipment ID):

   GET https://soa-gw.canadapost.ca/rs/{{canada_post_cust_number}}/{{canada_post_cust_number}}/shipment?trackingPIN={{canada_post_tracking_number}}
   

   Sample Response:

   <?xml version="1.0" encoding="UTF-8"?>
   <shipments xmlns="http://www.canadapost.ca/ws/shipment-v8">
       <link rel="shipment" href="https://soa-gw.canadapost.ca/rs/{{canada_post_cust_number}}/{{canada_post_cust_number}}/shipment/{{canada_post_shipment_id}}" media-type="application/vnd.cpc.shipment-v8+xml"/>
   </shipments>

   Note: The shipment ID is also returned when the shipment is initially created. (Karrio likely already has the ID saved)

2. Void the shipment:
   Use the shipment ID from the previous step and make the following request:

   DELETE https://soa-gw.canadapost.ca/rs/{{canada_post_cust_number}}/{{canada_post_cust_number}}/shipment/{{canada_post_shipment_id}}
   

   • A successful response will return a 204 No Content status.
   • Any other response or content indicates a failure.
   • If the shipment was already manifested the response will be a 400 along with a message:

<?xml version="1.0" encoding="UTF-8"?>
<messages xmlns="http://www.canadapost.ca/ws/messages">
    <message>
        <code>8064</code>
        <description>A Shipment can only be void if it is in a PROCESSED or PRINTED state. If it has been transmitted, a Refund request should be submitted.</description>
    </message>
</messages>

---

Scenario 2: Request a Refund for a Manifested Shipment

• Request Shipment Refund (Scenario 2): [API Docs](https://www.canadapost-postescanada.ca/info/mc/business/productsservices/developers/services/shippingmanifest/shipmentrefund.jsf)

To cancel a shipment that has already been included in a manifest but not shipped, follow these steps:

1. Retrieve the shipment ID:
   Similar to Scenario 1, use the following endpoint to get the shipment URL and ID:

   GET https://soa-gw.canadapost.ca/rs/{{canada_post_cust_number}}/{{canada_post_cust_number}}/shipment?trackingPIN={{canada_post_tracking_number}}
   

2. Request a refund:
   Use the shipment ID to call the following endpoint with an XML body:

   POST https://soa-gw.canadapost.ca/rs/{{canada_post_cust_number}}/{{canada_post_cust_number}}/shipment/{{canada_post_shipment_id}}/refund
   

   Sample Request Body:

   <shipment-refund-request xmlns="http://www.canadapost.ca/ws/shipment-v8">
       <email>your-email@email.com</email>
   </shipment-refund-request>

   • If the shipment was already requested for a refund the response will be a 409 conflict along with a message:

<?xml version="1.0" encoding="UTF-8"?>
<messages xmlns="http://www.canadapost.ca/ws/messages">
    <message>
        <code>7292</code>
        <description>A refund has already been requested for this shipment.  Note that refund requests may take a few days to be processed.</description>
    </message>
</messages>

---

Non-Contract Shipping

For non-contract shipments, the cancellation process does not involve manifests, since these shipments are paid immediately upon label creation there's only one endpoint for Request Shipment Refund

• Non-Contract Shipping (Refund Request): [API Docs](https://www.canadapost-postescanada.ca/info/mc/business/productsservices/developers/services/onestepshipping/shipmentrefund.jsf)

---

Expected Behavior

• For Scenario 1 (Contract Shipping), Karrio should only treat a 204 No Content response as a successful cancellation.
• For Scenario 2 (Contract Shipping), if not yet supported, Karrio should introduce support for shipment refunds.
• For Non-Contract Shipping, Karrio should implement separate logic to handle refund request directly.

---

Suggested Fix

1. Differentiate between contract and non-contract shipping:

   • Introduce a flag or configuration option in Karrio to identify the shipping type.
   • Apply appropriate cancellation/void/refund logic based on the type.

2. Verify and handle responses:

   • Ensure that only a 204 No Content response is treated as successful.
   • Log or display errors for empty or unexpected responses (e.g., <messages> tags).

3. Add support for refunds in manifested shipments (Scenario 2):

   • If not already implemented, allow refund requests for manifested shipments under contract shipping.