Connecting third party shipping providers via API

I am looking through the API but and I have some concerns. Is it possible to connect a third party shipping provider (ex: PirateShip) to ShipHero’s software? Or are we only able to use the shipping rates within software?

As we wanted to connect a third party shipping label provider to this software but by looking at the API I wasn’t sure that it’s even possible. Seems like we have to use the rates provided by ShipHero.

If what I am speaking about is possible via API please let me know so I can dig further into documentation.

Hey @xos15z<

Thanks for your patience. It is possible to add third party shipping providers via the API through our Generate Label Webhook.

Could you privately message me your:

I’ll go ahead and put in the request for you.
Please let me know if you have any further questions or concerns!

Best,
RayanP

@sh-agent Hi Rayanp, I am also looking for the same. Trying to connect the 3rd party logistics company ( for whom I work) with the Ship Hero software but need more understanding in detail about how it can be achieved. The 3PL company handles all the shipping. The 3PL company has a print label and tracking parcel API built in. Waiting for your response for the solution and the explanation of the solution as well.

Hey @karan19sukhija,

Thanks for hanging in there!

If you’re looking for consultation, I can connect you to some third parties that have previously worked with us. Questions regarding workflows and wants for the integration can be directed towards them.

If you are specifically interested in our Generate Label Webhook, the documentation can be found here:Webhooks – Developer Resources | ShipHero

Please let me know if you have any questions or concerns.

Best,
RayanP

Hi @sh-agent ,

That would be great if you could connect me. Also, I am highly interested in getting to know more about the solution to the problem mentioned in my previous post. And what are the scenarios when we should use generate label webhook and how does it work ?

Also, I read a bit about the generate label webhook. It says that it can be used when you don’t use the Shiphero carrier but yours. In that case, what ship hero will be used for then?

Hello @karan19sukhija!

The Generate Label Webhook sends a webhook to the endpoint the customer sets up, containing the same payload we would send to any natively integrated carrier.

As a response, we expect a label URL and some shipment data, as presented in the documentation Rayan shared.

If you need to use a carrier that ShipHero doesn’t natively integrate with, you would need to use the Generate Label Webhook and build a middleware between it and the carrier. This way, when you receive the webhooks, you query the carrier for a Label, and then you forward that to us in the webhook response.

The webhook will trigger when the packer presses print label in ShipHero UI, and has the GLW carrier selected instead of one of the natively integrated.

Please let me know if this clears it out.

Have a nice day!
TomasFD

I got your points regarding the generate label webhook. So in my case, we have a 3PL who has an account with shiphero and we are the carriers for them. We have the print label and tracking parcel functionality in the form of API’s. So how should I integrate our ( we being the careers ) print label and tracking parcels API’s with our packer/shippers who already use shiphero for their logistics stuff?

Hi,
Any update on this ?

Hello @karan19sukhija,

If you check our documentation, the one Rayan shared, you will see examples of 2 payloads, the request we send, and the response we expect.

In order for you to integrate with us, you would need to build the middleware that receives that request and sends back the response with the corresponding Label and fields pertaining to the order contained in the request.

The field parameters of the response are also in that piece of documentation. If you have any other questions, please let me know.

Kibd regards,
TomasFD

Hello @tomasfd,

As I mentioned, we are the carriers for the shipping company ( which we are working with ), and we want to build the Generate label webhook for our shipping company which is using shiphero for their logistic-related requirements.

We already have built the middleware ( in the form of APIs) which receives the request ( order details ) and sends back the response ( both request and response in JSON format ). I noticed in the URL shared below that the webhook body having order details contains a particular set of fields such as order_id, shipping_method, from_address, packages, etc. Related to that, I have 2 questions:

  1. Does the middleware ( the APIs ) which we the carrier created also need to have the same set of fields in the request payload as what is shown in the webhook payload in order to process the request?

  2. Also, our middleware ( the APIs) i.e. the label API and tracking API have authentication linked to it in terms of API key which needs to be passed in the header section when invoking the API. In that scenario, how we can integrate such apis in the Generate label webhook?

https://developer.shiphero.com/webhooks#generate-label-webhook

Hello @karan19sukhija

  1. This is a webhook; we send a payload, and we expect a response. The payload we send has a set of fields (contents, weight, from and to address, etc) that carriers usually need to process what method, label, and/or service level is going to be needed for that order.
    What we do need is for you to provide the response containing the label and the other fields, if you want, according to the parameters shared in that URL. You can see there is an option for single-package response and one for multi-package response. That is what we need you to respond with to our webhook.
    What you do with the payload we send and the middleware it’s your choice. We just require the right label to be sent back to us in the response.
  2. We cannot customize the headers. However, we could register the webhook endpoint URL with the API key for you to catch it. As for the tracking URL, we just need the URL to paste in the order. We won’t be consulting tracking statuses, that is not scoped within the Generate Label Webhook.

Have a great day!
TomasFD

@tomasfd Thanks for the detailed information. Really appreciate it. One more question related to it. You said you sent the payload to the webhook. The request payload will contain all such fields (contents, weight, from and to address, etc) in that same format? I mean the field names will be the same such as from_address, to_address, and packages? Because in the middleware we have different fields set up such as instead of from_address, we have the shipperFrom field

Hello @karan19sukhija!

When I said middleware in one of my first messages, I meant something to translate our payload to your end’s field names and data types.

We provide the webhook payload for our customers to use and translate into the carrier’s API requirements, and then translate back the carrier response to our expected response’s field names an data types.

Kind regards,
TomasFD

@tomasfd that’s a lot clearer to me. One thing I need to ask is related to the order statuses. Do we ( the carriers ) or the shiphero customers ( in my case our shipping company ) need to send the order/parcel statuses to shiphero ?

Hey @karan19sukhija,

Thanks for hanging in there!

No, I don’t believe you need to. As long as the response to the GLW webhook is formatted with the mandatory fields, that should be enough.

Please let me know if you have any questions or concerns.

Best,
RayanP

@sh-agent Thanks Rayan for responding. The webhook payload for GLW which shiphero provides to their customers ( which can be seen in the below link ) is fixed ? I mean all the fields which I can see in GLW payload such as packages list contaning line_items list containing fields such as sku, tariff_code etc, will all be there or some are optional ? Also, is it possible to get the description of all the fields in GLW so that we can configure our middleware better to map the fields accordingly. For example, in the line_items list, I don’t know what is line_item_id, partner_line_item_id, what is id, what is partner_order_id etc ?

https://developer.shiphero.com/webhooks#generate-label-webhook

@sh-agent Hi rayan, any update on this ?

Hey @karan19sukhija,

Thanks for hanging in there!

The payload from the GLW is fixed and cannot be altered.

I don’t believe there is a resource that defines all of the fields present. Which other fields do you need further clarification on?

line_item_id is the unique id given to a line_item of an order by ShipHero

partner_line_item_id is a unique ID input to a line_item of an order that can be used as reference in ShipHero or other applications. EX this value can be set as the Shopify’s line_item_id, which can then be used as reference from our side.

partner_order_id follows the same line of thinking as the partner_order_id. For example, a customer could set this value as the Shopify order ID and then use it as a reference.

Best,
RayanP

Hi @sh-agent sure,

Few things which I need to ask to you for the payload now are mentioned below. Would be great if you can answer that:

  1. In the GLW payload, there is a packages list. I am assuming this list contains the number of packages. For example, in the package 1, there are 2 line_items, then it means that the single package 1 contains 2 items ? Then another package 2 can contain any number of items but they call be passed in a single payload ?

  2. The weight_in_oz field in the package 1 list determines the total weight of the package 1 only? Let’s say, if I combine line_item 1 weight with line_item 2 weight, it should give me total equal to package 1 weight which is stored in weight_in_oz ?

  3. Which field in the GLW payload can determine “shipping company name “ ?

  4. Which field in the GLW payload can determine “ special delivery instructions “ to the order ?

  5. Which field in the GLW payload can determine “ any customer number “ ? It can be a number which is internal to shipper and related to the customer/end-user ( for whom the order is places )

  6. Which field in the GLW payload can determine “ Customer order number “ ? The order number represents the number for the single order in which multiple line_items are passed within their own packages.

  7. Which field in the GLW payload can determine “delivery type “ of the order such as standard or express?

  8. Which field in the GLW payload can determine “ expected delivery date“ to the individual package ( not the whole order ) ?

  9. Which field in the GLW payload can determine “ load reference Id “ to the order ? This id determines the Id of the load which is loaded in the truck. This id helps in determining that a particular line_item belongs to which load in the trick. This Id is internal to shippers

  10. Which field in the GLW payload can determine “ total cost “ of the order ?

  11. Are all the units of weights in the GLW are in lbs and of height/length/width in cm ?

Warm Regards,