We currently use Canada Post’s website to manually set up a “Return Policy” (specifying our receiving address, box-free option, QR-code option, etc.), which generates a code. We give this code to a customer who needs to return an item; the customer goes to a Canada Post URL, enters the code and their email, and Canada Post then automatically sends them an official email containing a QR code and drop-off instructions. The customer can then bring the item to a post office and use the QR code to complete the return.
We’d like to automate this entire experience through the API: when our system approves a customer’s return request, we want the customer to immediately receive that same official Canada Post email (QR code + instructions), without any manual step on our end. On our side, we only need to capture the tracking number and, eventually, the actual amount we were charged for the label.
Based on the developer documentation, we believe Create Authorized Return is the right API for this, but a few things aren’t clear to us:
- Is Create Authorized Return the correct API to replicate our manual “Return Policy + code” workflow? Is the self-serve experience we currently get through the website (code entry → customer email with QR code + instructions) backed by the same Authorized Return API, or is it a separate product/feature that requires different API access?
- Automatic customer email: Does calling Create Authorized Return (with
create-public-keyandcreate-qr-codeset to true) automatically trigger Canada Post to send an email to the customer containing the QR code and drop-off instructions — the same email our customers receive today through the manual website flow? Or is that email specific to the website-based “Return Policy” workflow and not triggered by a direct API call? If it’s not automatic via the API, is there a way to request it, or would we need to send that email ourselves? - Weight for partial returns: If a customer purchases 10 units of an item and is only returning 1, how should we handle the
weightfield in the request? Should we pull the actual weight of the single returned item from our own product data, or does it not matter much given that this is a “bill on scan” label — i.e., is the weight submitted at creation just an estimate for reference, with the final price determined by the actual weight measured at scan time? - Retrieving the actual charge for a bill-on-scan label: Once a label has been scanned/used and billed, is there an API we can call (using the tracking number) to retrieve the actual amount we were charged? We’d like to record this cost automatically rather than relying solely on monthly invoice reconciliation.
- Get Artifact and the QR-code-only flow: If our use case only needs the QR code (not a PDF label copy), is it necessary to call Get Artifact at all, given that the QR code image is already returned directly in the Create Authorized Return response? Separately, the docs mention “you have five calendar days to retrieve the return label before the link expires” for Get Artifact — does this 5-day window affect the QR code / label itself in any way (e.g., how long the customer has to actually use it at a retail location), or is it strictly about the Get Artifact retrieval link?
- Unused labels: If a return request is approved and a label is created, but the customer never brings the item in for scanning (e.g., the return is later rejected, or the customer changes their mind), is there anything we need to do on our end (e.g., cancel/void the label), or does it simply remain unbilled and require no action?
Any clarification, or pointers to more detailed documentation covering these points, would be greatly appreciated.