v1

latestOpenAPI 3.0.02026-07-1397337495.2 KB

labels

Purchase Label from Rate Shopper

Purchase and print a shipping label using the Rate Shopper. The Rate Shopper automatically selects the optimal carrier and service from your wallet carriers based on your specified rate selection strategy (cheapest, fastest, or best_value). For more information about this in the rates documentation.

post/v1/labels/rate_shopper_id/{rate_shopper_id}

Path parameters

rate_shopper_id'best_value' | 'cheapest' | 'fastest' required

Optional attributes that indicate the most profitable rates

The rate selection strategy for the Rate Shopper. This determines which carrier and service will be automatically selected from your wallet carriers based on the rates returned for the shipment.

Request body

is_return_labelboolean

Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.

rma_numberstring nullable

An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.

charge_event'carrier_default' | 'on_creation' | 'on_carrier_acceptance'

Determines when the user's account will be charged for the label.

outbound_label_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

test_labelboolean

Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.

validate_address'no_validation' | 'validate_only' | 'validate_and_clean'

The possible validate address values

label_download_type'url' | 'inline'

There are two different ways to download a label:

Label Download Type	Description
url	You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inline	You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

label_format'pdf' | 'png' | 'zpl'

The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

Label Format	Supported Carriers
pdf	All carriers
png	fedex <br> stamps_com <br> ups <br> usps
zpl	access_worldwide <br> apc <br> asendia <br> dhl_global_mail <br> dhl_express <br> dhl_express_australia <br> dhl_express_canada <br> dhl_express_worldwide <br> dhl_express_uk <br> dpd <br> endicia <br> fedex <br> fedex_uk <br> firstmile <br> imex <br> newgistics <br> ontrac <br> rr_donnelley <br> stamps_com <br> ups <br> usps

display_scheme'label' | 'paperless' | 'label_and_paperless'

The display format that the label should be shown in.

label_layout'4x6' | 'letter' | 'A4' | 'A6'

The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_image_idstring

Used to identify an image resource.

Example request

{
  "shipment": {
    "shipment_id": "se-28529731",
    "items": [
      {
        "asin": "B00005N5PF"
      }
    ],
    "ship_date": "2018-09-23T00:00:00.000Z",
    "created_at": "2018-09-23T15:00:00.000Z",
    "modified_at": "2018-09-23T15:00:00.000Z",
    "ship_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "ship_from": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "warehouse_id": "se-28529731",
    "return_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "customs": {
      "importer_of_record": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA"
      },
      "customs_items": [
        {
          "customs_item_id": "se-28529731",
          "country_of_origin": "CA"
        }
      ]
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "invoice_number": "IOC56888"
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "tracking_number": "1Z932R800392060079",
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "country_of_origin": "CA",
            "vat_rate": 0.2
          }
        ]
      }
    ],
    "comparison_rate_type": "retail",
    "zone": 6
  },
  "outbound_label_id": "se-28529731",
  "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
}

Response

Label created successfully using Rate Shopper. The response includes the selected carrier_id, service_code, and rate_shopper_id that was used.

label_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

status'processing' | 'completed' | 'error' | 'voided'

The possible statuses that a shipping label can be in.

Status	Description
processing	When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status.
completed	The label was successfully created
error	The label could not be created due to an error, such as an invalid delivery address
voided	The label has been voided

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

external_shipment_idstring nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

external_order_idstring nullable

ID that the Order Source assigned

ship_datestring date-time

An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.

created_atstring date-time

An ISO 8601 string that represents a date and time.

tracking_numberstring

The tracking number for the package. Tracking number formats vary across carriers.

is_return_labelboolean

Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.

rma_numberstring nullable

An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.

is_internationalboolean

Indicates whether this is an international shipment. That is, the originating country and destination country are different.

batch_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

carrier_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

charge_event'carrier_default' | 'on_creation' | 'on_carrier_acceptance'

Determines when the user's account will be charged for the label.

outbound_label_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

service_codestring

A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

test_labelboolean

Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.

package_codestring

A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.

validate_address'no_validation' | 'validate_only' | 'validate_and_clean'

The possible validate address values

voidedboolean

Indicates whether the label has been voided

voided_atstring date-time

An ISO 8601 string that represents a date and time.

label_download_type'url' | 'inline'

There are two different ways to download a label:

Label Download Type	Description
url	You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inline	You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

label_format'pdf' | 'png' | 'zpl'

The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

Label Format	Supported Carriers
pdf	All carriers
png	fedex <br> stamps_com <br> ups <br> usps
zpl	access_worldwide <br> apc <br> asendia <br> dhl_global_mail <br> dhl_express <br> dhl_express_australia <br> dhl_express_canada <br> dhl_express_worldwide <br> dhl_express_uk <br> dpd <br> endicia <br> fedex <br> fedex_uk <br> firstmile <br> imex <br> newgistics <br> ontrac <br> rr_donnelley <br> stamps_com <br> ups <br> usps

display_scheme'label' | 'paperless' | 'label_and_paperless'

The display format that the label should be shown in.

label_layout'4x6' | 'letter' | 'A4' | 'A6'

trackableboolean

Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.

label_image_idstring

Used to identify an image resource.

carrier_codestring

A shipping carrier, such as fedex, dhl_express, stamps_com, etc.

tracking_status'unknown' | 'in_transit' | 'error' | 'delivered'

The different statuses that can apply to a shipment.

The possible delivery confirmation values

tracking_urlstring nullable

The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.

void_type'refund_assist' | 'manual'

Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.

Example response

{
  "label_id": "se-28529731",
  "shipment_id": "se-28529731",
  "shipment": {
    "shipment_id": "se-28529731",
    "carrier_id": "se-28529731",
    "service_code": "usps_first_class_mail",
    "shipping_rule_id": "se-28529731",
    "items": [
      {
        "asin": "B00005N5PF"
      }
    ],
    "ship_date": "2018-09-23T00:00:00.000Z",
    "created_at": "2018-09-23T15:00:00.000Z",
    "modified_at": "2018-09-23T15:00:00.000Z",
    "ship_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "ship_from": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "warehouse_id": "se-28529731",
    "return_to": {
      "name": "John Doe",
      "phone": "+1 204-253-9411 ext. 123",
      "email": "example@example.com",
      "company_name": "The Home Depot",
      "address_line1": "1999 Bishop Grandin Blvd.",
      "address_line2": "Unit 408",
      "address_line3": "Building #7",
      "city_locality": "Winnipeg",
      "state_province": "Manitoba",
      "postal_code": "78756-3717",
      "country_code": "CA"
    },
    "customs": {
      "importer_of_record": {
        "name": "John Doe",
        "phone": "+1 204-253-9411 ext. 123",
        "email": "example@example.com",
        "company_name": "The Home Depot",
        "address_line1": "1999 Bishop Grandin Blvd.",
        "address_line2": "Unit 408",
        "address_line3": "Building #7",
        "city_locality": "Winnipeg",
        "state_province": "Manitoba",
        "postal_code": "78756-3717",
        "country_code": "CA"
      },
      "customs_items": [
        {
          "customs_item_id": "se-28529731",
          "country_of_origin": "CA"
        }
      ]
    },
    "advanced_options": {
      "bill_to_country_code": "CA",
      "invoice_number": "IOC56888"
    },
    "tags": [
      {
        "tag_id": 8712,
        "name": "Fragile",
        "color": "#FF0000"
      }
    ],
    "packages": [
      {
        "shipment_package_id": "se-28529731",
        "package_id": "se-28529731",
        "package_code": "small_flat_rate_box",
        "tracking_number": "1Z932R800392060079",
        "content_description": "Hand knitted wool socks",
        "products": [
          {
            "country_of_origin": "CA",
            "vat_rate": 0.2
          }
        ]
      }
    ],
    "comparison_rate_type": "retail",
    "zone": 6
  },
  "ship_date": "2018-09-23T00:00:00.000Z",
  "created_at": "2018-09-23T15:00:00.000Z",
  "tracking_number": "782758401696",
  "batch_id": "se-28529731",
  "carrier_id": "se-28529731",
  "outbound_label_id": "se-28529731",
  "service_code": "usps_first_class_mail",
  "package_code": "small_flat_rate_box",
  "voided_at": "2018-09-23T15:00:00.000Z",
  "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  "carrier_code": "dhl_express",
  "label_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731",
    "pdf": "http://api.shipengine.com/v1/labels/se-28529731",
    "png": "http://api.shipengine.com/v1/labels/se-28529731",
    "zpl": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "form_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "qr_code_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "paperless_download": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "insurance_claim": {
    "href": "http://api.shipengine.com/v1/labels/se-28529731"
  },
  "packages": [
    {
      "package_code": "small_flat_rate_box",
      "tracking_number": "1Z932R800392060079",
      "label_download": {
        "href": "http://api.shipengine.com/v1/labels/se-28529731",
        "pdf": "http://api.shipengine.com/v1/labels/se-28529731",
        "png": "http://api.shipengine.com/v1/labels/se-28529731",
        "zpl": "http://api.shipengine.com/v1/labels/se-28529731"
      },
      "form_download": {
        "href": "http://api.shipengine.com/v1/labels/se-28529731"
      },
      "qr_code_download": {
        "href": "http://api.shipengine.com/v1/labels/se-28529731"
      },
      "paperless_download": {
        "href": "http://api.shipengine.com/v1/labels/se-28529731"
      },
      "content_description": "Hand knitted wool socks",
      "alternative_identifiers": [
        {
          "type": "last_mile_tracking_number",
          "value": "12345678912345678912"
        }
      ]
    }
  ],
  "alternative_identifiers": [
    {
      "type": "last_mile_tracking_number",
      "value": "12345678912345678912"
    }
  ],
  "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  "ship_to": {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "geolocation": [
      {
        "type": "what3words",
        "value": "cats.with.thumbs"
      }
    ]
  },
  "refund_details": {
    "request_date": "2018-09-23T15:00:00.000Z"
  }
}