Assistance Needed with Carrier Integration and Shipment Cancellation Process

[miguelngansop]

Hello,

I am encountering an issue while integrating a carrier into karrio and need your assistance. The shipment creation process I am following involves the following steps:

• Creating a Submission Offer: An offer is created which can either be accepted or refused by the partner. I regularly check the status at intervals to determine if the offer has been accepted or not.

• Handling Refused Offers: If the offer is refused, I need to cancel the shipment on Karrio and also cancel the job on our end.

The problem I am facing is:

When I cancel the shipment, the cancellation is only reflected in the carrier's database and not on Karrio. This results in the dashboard not showing the shipment as cancelled, unlike when I cancel it manually via the dashboard.
I am looking to implement this cancellation process from the backend.

I have noticed that it is possible to call the /cancel API endpoint on Karrio, but it requires the shipment ID (shp_......), which I do not have because the shipment IDs are generated automatically in the backend.

Could you please guide me on how to obtain the shipment ID or implement the cancellation correctly so that it is reflected on Karrio?

Thank you for your assistance!

[miguelngansop]

@DanielOaks @DarkSwoop @rcknr @nahall

[DarkSwoop]

I don't know exactly what you want to develop, but Submission Offer and so on doesn't sound like Karrio itself.

To answer your questions:

• You could retrieve all shipments via the /v1/shipments endpoint. You can also filter these.
• If you got the ShipmentId from there, you can call the cancel endpoint as usual.
• To simplify filtering shipments, you could assign meta tags or use a shipment reference when creating a shipment (which probably happens via an external app).

What exactly do you want to build?

[miguelngansop]

Thank you very much @DarkSwoop , I'm adding a carrier to the system.

[danh91]

Hi @miguelngansop ,

As @DarkSwoop mentioned, Karrio' carrier integration is quite detached from the inner workings of the carrier API for asynchronous operations like a shipment going through a submission offer that can be declined.

What that means is the regular flow is by example:
Karrio sends a shipping request to a carrier like UPS for a certain destination, UPS validated that they can deliver in the said area and return a label in one synchronous API request.

That said if I understand correctly you have a system in between that can reconcile the state with Karrio when shipment submissions are refused. correct me if I am wrong... 🤔
-> If that is true then you can indeed make a /cancel request on Karrio's end to reconcile the state.

Since you mentioned the dashboard, I assume that you are creating shipments using the /v1/shipments endpoint for them to be visible in the shipments page. In that case, you should be receiving a shipment object with an ID (shp_...) that you can use to cancel using the /v1/shipments/{id}/cancel endpoint.

So we are probably missing the big picture of what you are trying to accomplish. and what you've done so far.

We understand that you are trying to add a carrier to the system. But, can you share more details about what you are building?

• Could you share more about the carrier you are adding?
• Does their system have an API (I assume yes)?
• Do they have APIs for the following operations: creating a shipment/label, cancelling a shipment/label, tracking a shipment?
• What you have done so far, Is the code here on GitHub? can you share a link?
• Do you have an app or internal system that you plan to use in conjunction with Karrio or do you plan to use the Karrio dashboard directly?

This is my most important question: Does the carrier system have a tracking API or an API that allows you to retrieve details about the shipment you have created? will that API return a status when the submission is refused?

Ultimately, if I understand correctly your issue, and there is a tracking API that can provide updates about the shipment status when it is refused, then we can add a tracking status in Karrio like cancelled_by_carrier which will automatically cancel the shipment on Karrio's end.

That might solve it because Karrio has a background job that polls tracking APIs to check shipment status updates. It will be able to map the refused state with a cancellation.

If you can illustrate and tell us more about what you are trying to achieve and how the different systems involved interact with each other, we will be able to see how we can help.