Generate Label Webhook
Warning
Adding carriers using the Generate Label Webhook must be approved prior to use. Please reach out to support@shiphero.com to request approval prior to starting any development.
Instead of using one of the ShipHero supported carriers, we can call a URL you provide to get the label from your endpoint. The endpoint you build must accept a JSON payload and return an image/PDF.
Contact us at support@shiphero.com or via chat with the following information:
- Endpoint URL (Something like https://someurl.com/print-label )
- Tracking URL (Something like https://www.trackingurl.com/?MyTrakcingNumber= )
- Name of the method (Name they want to show when choosing the method)
Then we can register that for you and when you go to ship the order, you will choose API as the carrier and the name you provided as the method, and hit Print Label to trigger the call.
Important
Wholesale Earth supports API Carriers; select ‘API’ as the carrier for your wholesale orders.
The response must include an image in PNG or PDF format. We DO NOT support clean URLs, the URL sent to us must contain the file extension.
Ex. “http://yourwebsite.com/file.pdf" or “http://yourwebsite.com/file.png"
Any errors must be returned with a status code of 500 or 400.
Webhook Body:
{
"shipping_method": "API Shipping",
"order_id": 242662901,
"profile": "default",
"fulfillment_status": "pending",
"order_number": "MO31",
"shop_name": "Manual Order",
"account_id": 5927,
"partner_order_id": "MO31",
"shipping_name": "Manual Order Shipping Method",
"tax_type": null,
"tax_id": null,
"incoterms": null,
"currency": "USD",
"from_address": {
"name": "ShipHero",
"company_name": "ShipHero",
"address_1": "123 First St.",
"address_2": "",
"email": "help@shiphero.com",
"city": "Anytown",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "1234567890"
},
"to_address": {
"name": "Test Order",
"company_name": "",
"address_1": "1 MAIN ST",
"address_2": "",
"email": "help@shiphero.com",
"city": "Anytown",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "1234567890"
},
"packages": [
{
"name": "Package 1",
"weight_in_oz": 4,
"width": 12,
"length": 15,
"height": 4,
"line_items": [
{
"sku": "shiphero-socks-black",
"tariff_code": "00.00.00.000",
"price": 0,
"customs_description": "ShipHero Socks - Black",
"customs_value": "0.01",
"line_item_id": 639727287,
"quantity": 1,
"weight": 2,
"partner_line_item_id": "MO31-299273207",
"id": "MO31-299273207",
"country_of_manufacture": "",
"product_name": "ShipHero Socks - Black",
"name": "ShipHero Socks - Black",
"ignore_on_customs": false
},
{
"sku": "shiphero-socks-blue",
"tariff_code": "00.00.00.000",
"price": 0,
"customs_description": "ShipHero Socks - Blue",
"customs_value": "0.01",
"line_item_id": 639727288,
"quantity": 1,
"weight": 2,
"partner_line_item_id": "MO31-299273245",
"id": "MO31-299273245",
"country_of_manufacture": "",
"product_name": "ShipHero Socks - Blue",
"name": "ShipHero Socks - Blue",
"ignore_on_customs": false
}
],
"box_code": "custom",
"box_id": 5612,
"box_name": "12x15 Poly Mailer"
},
{
"name": "Package 2",
"weight_in_oz": 3.50,
"width": 8,
"length": 12,
"height": 2,
"line_items": [
{
"sku": "shiphero-hero",
"tariff_code": "00.00.00.000",
"price": 0,
"customs_description": "ShipHero Hero ",
"customs_value": "0.01",
"line_item_id": 639727284,
"quantity": 1,
"weight": 0.92,
"partner_line_item_id": "MO31-299273995",
"id": "MO31-299273995",
"country_of_manufacture": "",
"product_name": "ShipHero Hero ",
"name": "ShipHero Hero ",
"ignore_on_customs": false
},
{
"sku": "shiphero-knit-hat",
"tariff_code": "00.00.00.000",
"price": 0,
"customs_description": "ShipHero Knit Hat ",
"customs_value": "0.01",
"line_item_id": 639727285,
"quantity": 1,
"weight": 2.19,
"partner_line_item_id": "MO31-299273169",
"id": "MO31-299273169",
"country_of_manufacture": "",
"product_name": "ShipHero Knit Hat ",
"name": "ShipHero Knit Hat ",
"ignore_on_customs": false
}
],
"box_code": "custom",
"box_id": 5565,
"box_name": "2 x 8 Poly Mailer"
}
]
}
Single Package Response
{
"code": "200",
"shipping_method": "Ground",
"tracking_number": "456123789",
"cost": "5.55",
"label": "https://url-to-label.com",
"customs_info": "",
"shipping_carrier": "ups",
"tracking_url": "https://mycarrier.com/456123789"
}
Multi Package Response
Note: You can use this format response for single packages as well.
{
"code": "200",
"packages":[
{
"name": "Package 1",
"shipping_method": "Ground",
"tracking_number": "987654321",
"cost": "20.20",
"label": "https://url-to-label.com/package2.pdf",
"customs_info": "",
"shipping_carrier": "ups",
"tracking_url": "https://mycarrier.com/987654321"
},
{
"name": "Package 2",
"shipping_method": "Ground",
"tracking_number": "123456789",
"cost": "10.10",
"label": "https://url-to-label.com/package1.pdf",
"customs_info": "https://url-to-label.com/customs1.pdf",
"shipping_carrier": "ups",
"tracking_url": "https://mycarrier.com/123456789"
}
]
}
or
{
"code": "4xx or 5xx",
"error": "Some validation error"
}
Response fields params:
- shipping_carrier:
- Non-mandatory. We will use API for all API methods.
- varchar(45)
- shipping_method:
- Non-mandatory. We will use the same name sent when creating the method.
- varchar(45)
- cost:
- Non-mandatory. We will use 0.00 if the field is not sent.
- Float(6,2). Must be sent as a string.
- tracking_number:
- Non-mandatory. Se note below.
- varchar(45). We will truncate any extra characters rendering the tracking link unusable.
- label:
- Mandatory.
- varchar(255)
- We DO NOT support clean URLs, must contain the file extension.
- customs_info:
- Non-mandatory. We will leave it blank if not sent
- varchar(255)
- We DO NOT support clean URLs, must contain the file extension.
- tracking_url:
- Non-mandatory. See note below
- varchar(255)
Important
All Label Responses beginning 08/01/2025 will require the Content-Type
Header.
For Json Responses the content type must be application/json
.
Any response without this will be rejected after the effective date.
Note
On Tracking URLs:
- The tracking URL we use for the label is the sum of the
tracking_number
sent in the Generate Label Webhook response and the Tracking URL sent when creating the method. - If no
tracking_number
is sent, we will leave it blank and no tracking link will be provided. - If the
tracking_url
field is present in the response, this value will override what has been explained above. - If you are sending the
tracking_url
field, make sure to send thetracking_number
field. We will use what’s on this field to set the display text for the tracking_url in the UI.
Note
On weight fields:
- Both
weight_in_oz
at the package level andweight
inside each line items are expressed in ounces. - Total weight of each package can be
>=
the sum of weight of line items.