Adding a new shipping carrier

Getting Started
1

Hello!

We’re an international carrier and would like to be onboarded to ShipHero (i.e. we provide shipping rates and labels). Stupid question: do we develop against your API, or does ShipHero call our API to get rates and labels?

Thanks!

1 Like
2

Hi Tony,
For carriers, there are 2 methods of integration
:

  1. ShipHero builds an integration using your API. For carrier requests we evaluate the demand and the work required - at the moment we do have a backlog of carrier integrations so it may be some time before we evaluate adding more.

  2. The other option is if the carrier builds the endpoint to respond to requests coming from ShipHero. In order to generate labels customers would use the Generate Label Webhook. When the customer needs to generate a label, we’ll call the specified URL and expect back a label in the response.
    Unfortunately, quoting is not yet supported for this option.

3

This is very helpful. Thank you @yosef. We do have a label URL you can hit. Is there a specific request/response format you need? Or is this the example? https://api-gateway.shiphero.com/your.domain/labels/create/url

4

Tony,
The request and response is detailed here:https://shipheropublic.docs.apiary.io/#reference/webhooks/generate-label-webhook-url/update-order

The request will contain all the info you need to generate a label (address, packages):

  {
  "shipping_name": "Manual Order Shipping Method",
  "to_address": {
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94105",
    "name": "test order",
    "address_2": "",
    "country": "US",
    "address_1": "123 MAIN ST",
    "email": "none@none.com",
    "phone": "",
    "company_name": ""
  },
  "shipping_method": "My Carrier",
  "order_id": "83478763",
  "packages": [
    {
      "width": 10,
      "weight_in_oz": 11,
      "length": 10,
      "line_items": [
        {
          "tariff_code": "0",
          "price": "0.00",
          "customs_description": null,
          "customs_value": "0.00",
          "line_item_id": "225458557",
          "barcode_exists": "0",
          "partner_line_item_id": "MO114-265348960",
          "sku": "yellow-kit",
          "barcode_scanned": "0",
          "name": "Yellow Kit",
          "ignore_on_customs": false,
          "product_name": "Yellow Kit",
          "quantity": "2"
        }
      ],
      "height": 10
    }
  ],
  "order_number": "MO114",
  "partner_order_id": "MO114",
  "from_address": {
    "city": "Garnerville",
    "state": "NY",
    "zip": "10923",
    "name": "ShipHero Apparel",
    "address_2": "",
    "country": "US",
    "address_1": "123 Main St",
    "email": "hello@shiphero.com",
    "phone": "11111111111",
    "company_name": ""
  }
}

The response expected from your endpoint should be this:

{
  "code": "200",
  "shipping_method": "Ground",
  "tracking_number": "1234567890",
  "cost": "5.55",
  "label": "https://s3.amazonaws.com/myimages/65259502/thermaltmpyjYG5K.png",
  "customs_info": "",
  "shipping_carrier": "ups"
}

Note that customs_info can be a URL to a PDF containing customs or other documentation that needs to be included with the shipment.

1 Like
5

That’s super helpful. Thank you @yosef!

6

Hi @yosef, one more stupid question - assume the client has multiple service levels with us, let’s say orders A&B need to be shipped with Priority, and orders C&D need to be shipped with Economy, what should they do? Register with 2 different endpoints of ours and pass in different “shipping_name”?

7

Yes, we can setup multiple options - they can still go to the same endpoint, but send in different shipping_name.

8

Great stuff. Thank you @yosef!

9

Hi @yosef, sorry got distracted for a while. Circling back to this: is there a way for us to pass back a custom tracking URL to ShipHero through this method?

10

There isn’t, but we can set the tracking link when setting up a customer to use you as a carrier.

11

Thanks Yosef. Just to be 100% sure, even if a client signs up to use our shipping service in this custom endpoint way, you can still help pass back the correct tracking URL, e.g. https://mytrackingurl.com/mytrackingcode?

12

Yes, that’s correct.

13

@yosef we have the webhook developed! Could you please PM me to advise what to do as the next step to get the client live?

14

@yosef in your example above, is the customs_value/price for the 2 items (i.e. each item is customs_value/price divide by quantity), or for just a single item?

15

It should be multiplying it by the quantity.

1 Like