Label API

The Label API returns the labelling information for an order, including pre-signed URLs to the shipping label and any customs or dangerous goods documents.

Labelling information is only available once the order has been processed and allocated a courier, which can take some time after the order was placed. Until then the request returns a 422.

For more information about common labelling errors, and how to avoid label request timeouts, see the labelling section in the Developer Guide.

Endpoints

GET/orders/{tracking_number}/labelRetrieve the label and documents for an order

The label object

dataobjectOptional

none

idintegerOptional

The internal Shippit ID of the generated label

orderobjectRequired

The order being labelled

Show child attributesHide child attributes

tracking_numberstringRequired

Unique random ID assigned to an order. Use this as a reference for future API calls or support tickets.

slugstringRequired

tracking_number in lowercase.

parcel_attributesarray of objectsOptional

Represents a parcel attached to an order

Show child attributesHide child attributes

qtynumberOptional: The number of parcels specified by the entry.
Depending on the configuration of the merchant account, the number of parcels generated might not match the number of parcel attributes passed in. By default, Shippit tries to combine all parcel attributes into a single parcel with the sum of the weights. However, if you have enabled Allocate each item in an order to a separate carton, Shippit generates one parcel entry for each parcel entry sent in.
weightnumberOptional: Weight of the parcel in kilograms
depthnumberOptional: Depth of the parcel in metres
lengthnumberOptional: Length of the parcel in metres
widthnumberOptional: Width of the parcel in metres
label_numberstringOptional: Parcel number in the carrier system.
Used when the order is a track-only order, to match the parcel number in a carrier against the parcel recorded in Shippit.

productsarray of objectsOptional

An array of product items specified in the order.
If no product information provided, this array is blank.

Show child attributesHide child attributes

titlestringOptional: conditional: Title or description of the product. Mandatory for international orders with specific carriers.
packedintegerOptional: The number of products packed. Used in partial orders, or otherwise when the number of products in the parcel is less than the total in the order. If not present, set to product quantity. If this is present, at least one item should have packed greater than 0. For international orders, all items should have packed greater than 0.
skustringOptional: conditional: SKU of the product. Mandatory on international orders for some carriers.
product_line_idstringOptional: Product line ID associated with product. Optional, for use when SKU isn't a unique identifier, such as when you have multiple lines containing the same SKU.
origin_country_codestringOptional: Two-letter country code (ISO 3166-1 Alpha-2) for the product's origin country. This is used in customs tracking for International shipments. Defaults to the home country of the Merchant.
locationstringOptional: Location of the product
dangerous_goods_codestringRequired if shipping dangerous goods: The dangerous goods code required when making dangerous goods declarations. Shipping any class of restricted or dangerous goods must be pre-approved by Shippit and the carrier. See Shipping dangerous goods.
dangerous_goods_textstringRequired if shipping dangerous goods: Additional information related to the dangerous goods being shipped
dangerous_goods_classstringRequired if shipping dangerous goods: The class of dangerous goods being shipped.
tariff_codestringOptional: Tariff or HS code for international orders declarations
quantityintegerOptional: The number of products ordered
pricenumberOptional: Unit price of each product line item. Used in the packing slip and customs declarations.
statusstringRequired: The status of the order
timestampstringRequired: The date/time when the status change occurred.

tracking_urlstringOptional

The URL of the customer tracking page for the order

returnbooleanOptional

Whether or not the order is a return order

idintegerOptional

Shippit internal numerical ID

processing_statestringOptional

Internal order status set and progressed by Shippit upon creation

invoice_numberanyOptional

Internal link between an order and a Shippit invoice - this is almost always null on order creation.

courier_delivery_instructionsstringOptional

Delivery instructions as sent to the carrier. In most cases, this is the same as the delivery_instructions passed into the request. Some carriers, however, have a specific format expected when sending delivery instructions through their API. This contains the actual delivery instructions that get sent through the carrier API when booked.

priceanyOptional

The price charged for the allocated order.
If you're creating orders by passing in courier_type, the carrier is usually not yet assigned at order creation and you get 0. Carrier allocation runs as a background process depending on the merchant preferences, available carriers, and quotes returned by the carriers, which can take a few seconds to complete after order creation. Shippit web users can also update the carrier in between API calls. Use the label call to retrieve the final carrier and quoted price. If the quoted price is still 0 during the label call, something could have gone wrong with the carrier selection, and you might need to amend the order.

customs_documents_require_printingbooleanOptional

Whether or not to print customs documents, such as declarations or invoices for including with the shipment. By default this is true for International orders.

courier_typestringOptional

The carrier allocated to the order. See the create order courier_allocation API for available keywords.

courier_namestringOptional

Human-readable name of the carrier allocated to the order.

tracking_historiesArray, see tableOptional

An array of tracking history statuses shown to the recipient as part of the order history on the tracking page

statestringOptional

The state of the order as progressed by the merchant

userobjectOptional

The recipient of the order

Show child attributesHide child attributes

emailstringRequired: The customer's email address. Must match the regular expression defined in WHATWG HTML spec.
first_namestringRequired: The customer's first name. Used as the customer's full name if last_name isn't provided.
last_namestringOptional: The customer's last name
mobilestringOptional: Mobile number of the user who purchased the order. This might be different to the recipient's phone number.

documentsobjectRequired

Documents attached to the label response

Show child attributesHide child attributes

archive_awbobjectOptional: Archive Airway Bill
urlstringOptional: URL to a printable PDF document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.
page_sizestringOptional
file_typestringOptional: File type of the label
encoded_labelstringOptional: Printable ZPL data for the document, if available

order_attachmentsobjectOptional

Additional attachments related to the order, such as certificates of origin or other supporting documents

Show child attributesHide child attributes

invoiceobjectOptional

Invoice document related to the order

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

customs_documentobjectOptional

Customs documentation for international shipments

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

msdsobjectOptional

Material Safety Data Sheet for hazardous goods

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

drop_ball_testobjectOptional

Drop ball test certification document

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

survey_reportobjectOptional

Survey report documentation

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

health_permitobjectOptional

Health permit documentation

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

fda_licenseobjectOptional

FDA license documentation

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

certificate_of_originobjectOptional

Certificate of origin document for international shipments

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

import_permitobjectOptional

Import permit documentation

Show child attributesHide child attributes

urlstringOptional: URL to a printable document.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

courier_job_idstringOptional

The ID assigned by the carrier to the shipment, if provided

qualified_urlstringRequired

URL to a printable label for the order.
This is a pre-signed URL, generated by the Shippit platform to provide access to a secured label. The pre-signed URL remains valid for 7 days. If you need to access the label after it's expired, make a new request to generate a new URL.

Sample responseJSON

{
  "response": {
    "id": 5044,
    "order": {
      "courier_delivery_instructions": "Authority to Leave. ",
      "courier_job_id": "SHP0100002",
      "courier_type": "CouriersPlease",
      "courier_name": "Couriers Please",
      "delivery_address": "37 Manorvale Pde",
      "delivery_instructions": "",
      "delivery_postcode": "3030",
      "delivery_state": "VIC",
      "delivery_suburb": "Werribee",
      "id": 9972,
      "invoice_number": "INV-1384",
      "parcels": [
        {
          "depth": 0.19,
          "length": 0.38,
          "name": "",
          "weight": 1,
          "width": 0.29,
          "label_number": "SHP010000201000930803",
          "courier_data": {
            "product_code": "X123",
            "pickup_zone": "SYD",
            "dropoff_zone": "MEL"
          }
        }
      ],
      "products": [
        {
          "title": "Industrial Paint Stripper",
          "price": 29.13,
          "sku": 0.1,
          "quantity": 1,
          "tariff_code": "000999",
          "dangerous_goods_code": "ID8000",
          "dangerous_goods_text": "ID8000 Consumer commodities - Dangerous Goods as per attached DGD",
          "origin_country_code": "TH"
        }
      ],
      "price": "15.95",
      "receiver_contact_number": "",
      "receiver_language_code": "EN",
      "receiver_name": "Jane Doe",
      "retailer_invoice": "",
      "slug": "ppkfqy44u8nff",
      "state": "completed",
      "tracking_number": "PPKFqy44U8Nff",
      "user": {
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "last_name": "Doe ",
        "mobile": ""
      },
      "customs_documents_require_printing": false,
      "documents": {
        "archive_awb": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/archive_document/15870762/archive_581833317220190318-2852-yi07y0.PDF",
          "page_size": "a6",
          "file_type": "pdf"
        },
        "customs_invoice": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/customs_invoice/361690/commercial_invoice_3073489348620190218-6221-mxrhx4.pdf",
          "page_size": "a3",
          "file_type": "pdf"
        },
        "dangerous_goods_declaration": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/dangerous_goods_declaration/361690/dangerous_goods_declaration_3073489348620140318-6220-11vib5y.pdf",
          "page_size": "a3",
          "file_type": "pdf"
        },
        "shipping_label": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/label/attachment/5044/PPKFqy44U8Nff.pdf",
          "page_size": "a6",
          "file_type": "pdf"
        }
      },
      "order_attachments": {
        "certificate_of_origin": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/26/certificate_of_origin.pdf"
        },
        "invoice": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/27/invoice.pdf"
        },
        "msds": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/28/msds.pdf"
        },
        "fda_license": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/29/fda_license.pdf"
        }
      }
    },
    "qualified_url": "https://shippit-production.s3.amazonaws.com/uploads/label/attachment/5044/PPKFqy44U8Nff.pdf"
  }
}

Retrieve label information for an order

GET/orders/{tracking_number}/label

Retrieves labelling information for an order using the tracking number.

To perform this operation, you must authenticate with an authentication token.

Parameters

tracking_numberstringpathRequired: The tracking number of the order

Response codes

Status	Meaning	Description
200	OK	Returns an Order and related label information.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, when the API secret is missing the permission this endpoint requires, or when the merchant account is disabled.
404	Not Found	Returns an error indicating that the Order could not be found in Shippit
422	Unprocessable Entity	Returns an error indicating that the Order cannot yet be processed for labelling. Typically this is because the Order has yet to be processed or allocated a courier. For more information about these errors, see the labelling section in the Developer Guide.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
  "response": {
    "id": 5044,
    "order": {
      "courier_delivery_instructions": "Authority to Leave. ",
      "courier_job_id": "SHP0100002",
      "courier_type": "CouriersPlease",
      "courier_name": "Couriers Please",
      "delivery_address": "37 Manorvale Pde",
      "delivery_instructions": "",
      "delivery_postcode": "3030",
      "delivery_state": "VIC",
      "delivery_suburb": "Werribee",
      "id": 9972,
      "invoice_number": "INV-1384",
      "parcels": [
        {
          "depth": 0.19,
          "length": 0.38,
          "name": "",
          "weight": 1,
          "width": 0.29,
          "label_number": "SHP010000201000930803",
          "courier_data": {
            "product_code": "X123",
            "pickup_zone": "SYD",
            "dropoff_zone": "MEL"
          }
        }
      ],
      "products": [
        {
          "title": "Industrial Paint Stripper",
          "price": 29.13,
          "sku": 0.1,
          "quantity": 1,
          "tariff_code": "000999",
          "dangerous_goods_code": "ID8000",
          "dangerous_goods_text": "ID8000 Consumer commodities - Dangerous Goods as per attached DGD",
          "origin_country_code": "TH"
        }
      ],
      "price": "15.95",
      "receiver_contact_number": "",
      "receiver_language_code": "EN",
      "receiver_name": "Jane Doe",
      "retailer_invoice": "",
      "slug": "ppkfqy44u8nff",
      "state": "completed",
      "tracking_number": "PPKFqy44U8Nff",
      "user": {
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "last_name": "Doe ",
        "mobile": ""
      },
      "customs_documents_require_printing": false,
      "documents": {
        "archive_awb": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/archive_document/15870762/archive_581833317220190318-2852-yi07y0.PDF",
          "page_size": "a6",
          "file_type": "pdf"
        },
        "customs_invoice": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/customs_invoice/361690/commercial_invoice_3073489348620190218-6221-mxrhx4.pdf",
          "page_size": "a3",
          "file_type": "pdf"
        },
        "dangerous_goods_declaration": {
          "url": "https://shippit-web-production.s3.amazonaws.com/uploads/order/dangerous_goods_declaration/361690/dangerous_goods_declaration_3073489348620140318-6220-11vib5y.pdf",
          "page_size": "a3",
          "file_type": "pdf"
        },
        "shipping_label": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/label/attachment/5044/PPKFqy44U8Nff.pdf",
          "page_size": "a6",
          "file_type": "pdf"
        }
      },
      "order_attachments": {
        "certificate_of_origin": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/26/certificate_of_origin.pdf"
        },
        "invoice": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/27/invoice.pdf"
        },
        "msds": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/28/msds.pdf"
        },
        "fda_license": {
          "url": "https://shippit-production.s3.amazonaws.com/uploads/order_attachment/attachment/29/fda_license.pdf"
        }
      }
    },
    "qualified_url": "https://shippit-production.s3.amazonaws.com/uploads/label/attachment/5044/PPKFqy44U8Nff.pdf"
  }
}

JSON

{
  "error": "label_failed_tracking_order",
  "error_description": "You have requested a label for a tracking order, tracking orders are not labelled in Shippit. Shippit just provides the tracking service for these orders."
}