ShipStation API v2 (2.0.0)

Download OpenAPI description
Overview
License MIT
Languages
Servers
Mock server
https://docs.shipstation.com/_mock/openapi/
Production
https://api.shipstation.com/

Batches

Process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly.

Operations

Carriers

Retreive useful details about the carriers connected to your accounts, including carrier IDs, service IDs, advanced options, and available carrier package types.

Operations

Downloads

Download your label files in PDF, PNG, and ZPL.

Operations

Labels

Purchase and print shipping labels for any carrier active on your account. The labels endpoint also supports creating return labels, voiding labels, and getting label details like tracking.

Operations

List labels

Request

This endpoint returns a list of labels that you've [created]. You can optionally filter the results as well as control their sort order and the number of results returned at a time.

By default, all labels are returned, 25 at a time, starting with the most recently created ones. You can combine multiple filter options to narrow-down the results. For example, if you only want to get your UPS labels for your east coast warehouse you could query by both warehouse_id and carrier_id

Query
label_statusstring(label_status)

Only return labels that are currently in the specified status

Enum"processing""completed""error""voided"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$

Only return labels for a specific [carrier service]

Example: service_code=usps_first_class_mail
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Carrier ID

Example: carrier_id=se-28529731
tracking_numberstringnon-empty

The tracking number associated with a shipment

Example: tracking_number=9405511899223197428490
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Batch ID

Example: batch_id=se-28529731
rate_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Rate ID

Example: rate_id=se-28529731
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Shipment ID

Example: shipment_id=se-28529731
warehouse_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

Warehouse ID

Example: warehouse_id=se-28529731
created_at_startstring(date-time)

Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)

Example: created_at_start=2019-03-12T19:24:13.657Z
created_at_endstring(date-time)

Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)

Example: created_at_end=2019-03-12T19:24:13.657Z
pageinteger(int32)>= 1

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

Default 1
Example: page=2
page_sizeinteger(int32)>= 1

The number of results to return per response.

Default 25
Example: page_size=50
sort_dirstring(sort_dir)

Controls the sort order of the query.

Default "desc"
Enum"asc""desc"
sort_bystring

Controls which field the query is sorted by.

Default "created_at"
Enum"modified_at""created_at"
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/labels?batch_id=se-28529731&carrier_id=se-28529731&created_at_end=2019-08-24T14%3A15%3A22Z&created_at_start=2019-08-24T14%3A15%3A22Z&label_status=processing&page=1&page_size=25&rate_id=se-28529731&service_code=usps_first_class_mail&shipment_id=se-28529731&sort_by=modified_at&sort_dir=desc&tracking_number=string&warehouse_id=se-28529731' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The response includes a labels array containing a page of results (as determined by the page_size query parameter). It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results.

Bodyapplication/json
labelsArray of objects(label)>= 0 itemsrequired

The labels that matched the query criteria. If no matching labels were found, then this array is empty; otherwise, it contains one page of results. The last page of results may have fewer labels than the page_size.

labels[].​label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
labels[].​statusstring(label_status)read-only

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
labels[].​shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
labels[].​ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-only

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 ShipStation .

Example: "2018-09-23"
labels[].​created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
labels[].​shipment_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

labels[].​insurance_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

labels[].​requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

labels[].​tracking_numberstringnon-emptyread-only

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

Example: "782758401696"
labels[].​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.

Example: true
labels[].​rma_numberstring or null

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

Example: "asd12323"
labels[].​is_internationalbooleanread-only

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

Example: true
labels[].​batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
labels[].​carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
labels[].​charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
labels[].​service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-only

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

Example: "usps_first_class_mail"
labels[].​package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "small_flat_rate_box"
labels[].​voidedbooleanread-only

Indicates whether the label has been [voided]

Example: true
labels[].​voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
labels[].​label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
labels[].​display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
labels[].​label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
labels[].​trackablebooleanread-only

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.

Example: true
labels[].​label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
labels[].​carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
labels[].​tracking_statusstring(tracking_status)read-only

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
labels[].​label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

labels[].​form_downloadobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

labels[].​paperless_downloadobject or null(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

labels[].​insurance_claimobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

labels[].​packagesArray of objects(label_package)read-only

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

labels[].​alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

labels[].​tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
totalinteger>= 0required

The total number of items across all pages of results

Example: 2750
pageinteger>= 1required

The current page number of results. For example, if there are 80 results, and the page size is 25, then page could be 1, 2, 3, or 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items.

Example: 1
pagesinteger>= 0required

The total number of pages of results. For example, if there are 80 results, and the page size is 25, then pages would be 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. If there are no results, then pages will be zero.

Example: 4
linksobject(pagination_link)required

Helpful links to other pages of results

links.​firstobject(link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​first.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​first.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​lastobject(link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​last.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​last.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​prevobject(optional_link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​prev.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​prev.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
links.​nextobject(optional_link)required

A link to a related resource, or an empty object if there is no resource to link to

links.​next.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
links.​next.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
property name*anyadditional property
Response
application/json
{ "labels": [ {} ], "total": 2750, "page": 1, "pages": 4, "links": { "first": {}, "last": {}, "prev": {}, "next": {} } }

Purchase label

Request

Purchase and print a label for shipment

Bodyapplication/jsonrequired
ship_to_service_point_idstring or null

A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's ship to address.

Example: "614940"
ship_from_service_point_idstring or null

A unique identifier for a carrier drop off point where a merchant plans to deliver packages. This will take precedence over a shipment's ship from address.

Example: "614940"
shipmentobject(shipment)write-onlyrequired

The information necessary to ship a package, such as the origin, the destination, the carrier service, and the package dimensions and weight.

shipment.​carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

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

Example: "se-28529731"
shipment.​service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$required

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

Example: "usps_first_class_mail"
shipment.​shipping_rule_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

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

Example: "se-28529731"
shipment.​external_order_idstring or null

ID that the Order Source assigned

Example: "1232434"
shipment.​itemsArray of objects(shipment_item)

Describe the packages included in this shipment as related to potential metadata that was imported from external order sources

Default []
shipment.​tax_identifiersArray of objects or null(tax_identifier)
shipment.​external_shipment_idstring or null<= 50 characters

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

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

Example: "1234556"
shipment.​shipment_numberstring or null<= 50 characters

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

Example: "se-1234545"
shipment.​ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...required

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 ShipStation .

Example: "2018-09-23"
shipment.​ship_toobject(shipping_address_to)required

A complete or partial mailing address.

shipment.​ship_to.​namestringnon-emptyrequired

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

Example: "John Doe"
shipment.​ship_to.​phonestringnon-emptyrequired

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

Example: "+1 204-253-9411 ext. 123"
shipment.​ship_to.​emailstring or null

Email for the address owner.

Example: "example@example.com"
shipment.​ship_to.​company_namestring or nullnon-empty

If this is a business address, then the company name should be specified here.

Example: "The Home Depot"
shipment.​ship_to.​address_line1stringnon-emptyrequired

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

Example: "1999 Bishop Grandin Blvd."
shipment.​ship_to.​address_line2string or nullnon-empty

The second line of the street address. For some addresses, this line may not be needed.

Example: "Unit 408"
shipment.​ship_to.​address_line3string or nullnon-empty

The third line of the street address. For some addresses, this line may not be needed.

Example: "Building #7"
shipment.​ship_to.​city_localitystringnon-emptyrequired

The name of the city or locality

Example: "Winnipeg"
shipment.​ship_to.​state_provincestringnon-emptyrequired

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

Example: "Manitoba"
shipment.​ship_to.​postal_codestring(postal_code)non-emptyrequired

postal code

Example: "78756-3717"
shipment.​ship_to.​country_codestring(country_code)= 2 charactersrequired
Example: "CA"
shipment.​ship_to.​address_residential_indicatorstring(address_residential_indicator)required

Indicates whether an address is residential.

Default "unknown"
Enum"unknown""yes""no"
Example: "no"
shipment.​ship_to.​instructionsstring or nullnon-empty

Additional text about how to handle the shipment at this address.

Example: "any instruction"
shipment.​ship_to.​geolocationArray of objects
shipment.​ship_fromobject(shipping_address)required

A complete or partial mailing address.

shipment.​ship_from.​namestringnon-emptyrequired

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

Example: "John Doe"
shipment.​ship_from.​phonestringnon-emptyrequired

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

Example: "+1 204-253-9411 ext. 123"
shipment.​ship_from.​emailstring or null

Email for the address owner.

Example: "example@example.com"
shipment.​ship_from.​company_namestring or nullnon-empty

If this is a business address, then the company name should be specified here.

Example: "The Home Depot"
shipment.​ship_from.​address_line1stringnon-emptyrequired

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

Example: "1999 Bishop Grandin Blvd."
shipment.​ship_from.​address_line2string or nullnon-empty

The second line of the street address. For some addresses, this line may not be needed.

Example: "Unit 408"
shipment.​ship_from.​address_line3string or nullnon-empty

The third line of the street address. For some addresses, this line may not be needed.

Example: "Building #7"
shipment.​ship_from.​city_localitystringnon-emptyrequired

The name of the city or locality

Example: "Winnipeg"
shipment.​ship_from.​state_provincestringnon-emptyrequired

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

Example: "Manitoba"
shipment.​ship_from.​postal_codestring(postal_code)non-emptyrequired

postal code

Example: "78756-3717"
shipment.​ship_from.​country_codestring(country_code)= 2 charactersrequired
Example: "CA"
shipment.​ship_from.​address_residential_indicatorstring(address_residential_indicator)required

Indicates whether an address is residential.

Default "unknown"
Enum"unknown""yes""no"
Example: "no"
shipment.​ship_from.​instructionsstring or nullnon-empty

Additional text about how to handle the shipment at this address.

Example: "any instructions"
shipment.​warehouse_idstring or null(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

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

Default null
Example: "se-28529731"
shipment.​return_toobject(shipping_address)required

A complete or partial mailing address.

shipment.​return_to.​namestringnon-emptyrequired

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

Example: "John Doe"
shipment.​return_to.​phonestringnon-emptyrequired

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

Example: "+1 204-253-9411 ext. 123"
shipment.​return_to.​emailstring or null

Email for the address owner.

Example: "example@example.com"
shipment.​return_to.​company_namestring or nullnon-empty

If this is a business address, then the company name should be specified here.

Example: "The Home Depot"
shipment.​return_to.​address_line1stringnon-emptyrequired

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

Example: "1999 Bishop Grandin Blvd."
shipment.​return_to.​address_line2string or nullnon-empty

The second line of the street address. For some addresses, this line may not be needed.

Example: "Unit 408"
shipment.​return_to.​address_line3string or nullnon-empty

The third line of the street address. For some addresses, this line may not be needed.

Example: "Building #7"
shipment.​return_to.​city_localitystringnon-emptyrequired

The name of the city or locality

Example: "Winnipeg"
shipment.​return_to.​state_provincestringnon-emptyrequired

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

Example: "Manitoba"
shipment.​return_to.​postal_codestring(postal_code)non-emptyrequired

postal code

Example: "78756-3717"
shipment.​return_to.​country_codestring(country_code)= 2 charactersrequired
Example: "CA"
shipment.​return_to.​address_residential_indicatorstring(address_residential_indicator)required

Indicates whether an address is residential.

Default "unknown"
Enum"unknown""yes""no"
Example: "no"
shipment.​return_to.​instructionsstring or nullnon-empty

Additional text about how to handle the shipment at this address.

Example: "any instructions"
shipment.​is_returnboolean or null

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

Default false
Example: true
shipment.​confirmationstring(delivery_confirmation)required

The possible delivery confirmation values

Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation"
shipment.​customsobject or null(international_shipment_options)required

Options for international shipments, such as customs declarations.

Default null
shipment.​customs.​contentsstring(package_contents)required

The possible package contents values

Default "merchandise"
Enum"merchandise""documents""gift""returned_goods""sample""other"
shipment.​customs.​contents_explanationstring

Explanation for contents (required if the contents is provided as other)

Example: "rubber duckies"
shipment.​customs.​non_deliverystring(non_delivery)required

The possible non delivery values

Default "return_to_sender"
Enum"return_to_sender""treat_as_abandoned"
shipment.​customs.​terms_of_trade_codestring(Allowed incoterms)

Specifies the supported terms of trade code (incoterms)

Enum"exw""fca""cpt""cip""dpu""dap""ddp""fas""fob""cfr"
shipment.​customs.​declarationstring

Declaration statement to be placed on the commercial invoice

Example: "I hereby certify that the information on this invoice is true and correct and that the contents and value of this shipment are as stated above"
shipment.​customs.​invoice_additional_detailsobject(invoice_additional_details)

The additional information to put on commercial invoice

shipment.​customs.​importer_of_recordobject(importer_of_records)

importer of records address, anywhere in the world.

shipment.​customs.​customs_itemsArray of objects(customs_item)>= 0 itemsDeprecated

Customs declarations for each item in the shipment. (Please provide this information under products inside packages)

Default []
shipment.​advanced_optionsobject(advanced_shipment_options)required

Advanced shipment options

shipment.​advanced_options.​bill_to_accountstring or null

This field is used to [bill shipping costs to a third party]. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.

Default null
Example: "123456789"
shipment.​advanced_options.​bill_to_country_codestring or null(country_code)= 2 characters
Default null
Example: "CA"
shipment.​advanced_options.​bill_to_partystring or null(bill_to_party)

The possible bill to party values

Default null
Enum"recipient""third_party"
Example: "third_party"
shipment.​advanced_options.​bill_to_postal_codestring or null

The postal code of the third-party that is responsible for shipping costs.

Default null
Example: "28005"
shipment.​advanced_options.​contains_alcoholboolean

Indicates that the shipment contains alcohol.

Default false
Example: true
shipment.​advanced_options.​delivered_duty_paidboolean

Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.

Default false
Example: true
shipment.​advanced_options.​dry_iceboolean

Indicates if the shipment contain dry ice

Default false
Example: true
shipment.​advanced_options.​dry_ice_weightobject or null(weight)

The weight of a package

shipment.​advanced_options.​non_machinableboolean

Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.

Default false
Example: true
shipment.​advanced_options.​saturday_deliveryboolean

Enables Saturday delivery, if supported by the carrier.

Default false
Example: true
shipment.​advanced_options.​fedex_freightobject

Provide details for the Fedex freight service

shipment.​advanced_options.​use_ups_ground_freight_pricingboolean or null

Whether to use [UPS Ground Freight pricing] If enabled, then a freight_class must also be specified.

Default null
Example: true
shipment.​advanced_options.​freight_classstring or null

The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".

Default null
Example: "77.5"
shipment.​advanced_options.​custom_field1string or null<= 100 characters

An arbitrary field that can be used to store information about the shipment.

Default null
Example: "custom field 1"
shipment.​advanced_options.​custom_field2string or null<= 100 characters

An arbitrary field that can be used to store information about the shipment.

Default null
Example: "custom field 2"
shipment.​advanced_options.​custom_field3string or null<= 100 characters

An arbitrary field that can be used to store information about the shipment.

Default null
Example: "custom field 3"
shipment.​advanced_options.​origin_typestring or null(origin_type)

Indicates if the package will be picked up or dropped off by the carrier

Default null
Enum"pickup""drop_off"
shipment.​advanced_options.​additional_handlingboolean or null

Indicate to the carrier that this shipment requires additional handling.

Default null
Example: true
shipment.​advanced_options.​shipper_releaseboolean or null
Default null
Example: true
shipment.​advanced_options.​collect_on_deliveryobject(collect_on_delivery)

Defer payment until package is delivered, instead of when it is ordered.

shipment.​advanced_options.​third_party_consigneeboolean

Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached

Default false
Example: true
shipment.​advanced_options.​dangerous_goodsboolean

Indicates if the Dangerous goods are present in the shipment

Default false
Example: true
shipment.​advanced_options.​dangerous_goods_contactobject

Contact information for Dangerous goods

shipment.​advanced_options.​windsor_framework_detailsobject

The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.

shipment.​insurance_providerstring(insurance_provider)required

The possible insurance provider values

Default "none"
Enum"none""shipsurance""carrier""third_party"
shipment.​order_source_codestring(order_source_name)

The order sources that are supported by ShipStation

Enum"amazon_ca""amazon_us""brightpearl""channel_advisor""cratejoy""ebay""etsy""jane""groupon_goods""magento"
shipment.​packagesArray of objects(package)non-emptyrequired

The packages in the shipment.

Note: Some carriers only allow one package per shipment. If you attempt to create a multi-package shipment for a carrier that doesn't allow it, an error will be returned.

shipment.​packages[].​package_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$

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

Example: "se-28529731"
shipment.​packages[].​package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$

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

Example: "small_flat_rate_box"
shipment.​packages[].​package_namestring

The name of the of the [package type]

Example: "Flat Rate Envelope"
shipment.​packages[].​weightobject(weight)required

The weight of a package

shipment.​packages[].​weight.​valuenumber> 0required

The weight, in the specified unit

Example: 23
shipment.​packages[].​weight.​unitstring(weight_unit)required

The possible weight unit values

Enum"pound""ounce""gram""kilogram"
shipment.​packages[].​dimensionsobject(dimensions)

The dimensions of a package

shipment.​packages[].​insured_valueobject(monetary_value)

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

Default [{"currency":"usd","amount":0}]
shipment.​packages[].​label_messagesobject(label_messages)

Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.

CarrierMax linesMax line length
USPS (Stamps.com)360
FedEx335 for the first line. 30 for additional lines.
UPS235
OnTrac225
shipment.​packages[].​external_package_idstringnon-empty

An external package id.

Example: "se-1234545"
shipment.​packages[].​content_descriptionstring or null[ 1 .. 35 ] characters

A short description of the package content. Required for shipments moving to, from, and through Mexico.

Example: "Hand knitted wool socks"
shipment.​packages[].​productsArray of objects(products)>= 0 items

Details about products inside packages (Information provided would be used on custom documentation)

Default []
shipment.​comparison_rate_typestring or null

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

Example: "retail"
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.

Example: true
rma_numberstring or null

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

Example: "asd12323"
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
outbound_label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$write-only

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

Example: "se-28529731"
validate_addressstring(validate_address)write-only

The possible validate address values

Default "validate_and_clean"
Enum"no_validation""validate_only""validate_and_clean"
label_download_typestring(label_download_type)write-only

There are two different ways to [download a label]:

Label Download TypeDescription
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Default "url"
Enum"url""inline"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
test_labelbooleanDeprecatedwrite-only

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

Default false
Example: true
curl -i -X POST \
  https://docs.shipstation.com/_mock/openapi/v2/labels \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "ship_to_service_point_id": "614940",
    "ship_from_service_point_id": "614940",
    "shipment": {
      "carrier_id": "se-1234567",
      "service_code": "se_1234567",
      "shipping_rule_id": "se-1234",
      "external_order_id": "1232434",
      "items": [],
      "tax_identifiers": [
        {
          "taxable_entity_type": "shipper",
          "identifier_type": "vat",
          "issuing_authority": "US",
          "value": "value"
        }
      ],
      "external_shipment_id": "1234556",
      "shipment_number": "se-1234545",
      "ship_date": "2018-09-23",
      "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",
        "address_residential_indicator": "no",
        "instructions": "any instruction",
        "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",
        "address_residential_indicator": "no",
        "instructions": "any instructions"
      },
      "warehouse_id": null,
      "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",
        "address_residential_indicator": "no",
        "instructions": "any instructions"
      },
      "is_return": true,
      "confirmation": "none",
      "customs": null,
      "advanced_options": {
        "bill_to_account": "123456789",
        "bill_to_country_code": "US",
        "bill_to_party": "third_party",
        "bill_to_postal_code": "28005",
        "contains_alcohol": true,
        "delivered_duty_paid": true,
        "dry_ice": true,
        "dry_ice_weight": {
          "value": 23,
          "unit": "pound"
        },
        "non_machinable": true,
        "saturday_delivery": true,
        "fedex_freight": {
          "shipper_load_and_count": "shipper_load_and_count",
          "booking_confirmation": "today"
        },
        "use_ups_ground_freight_pricing": true,
        "freight_class": "77.5",
        "custom_field1": "custom field 1",
        "custom_field2": "custom field 2",
        "custom_field3": "custom field 3",
        "origin_type": null,
        "additional_handling": true,
        "shipper_release": true,
        "collect_on_delivery": {
          "payment_type": "any",
          "payment_amount": {
            "currency": "USD",
            "amount": 12
          }
        },
        "third_party_consignee": true,
        "dangerous_goods": true,
        "dangerous_goods_contact": {
          "name": "Michael Robinson",
          "phone": "123456578789"
        },
        "windsor_framework_details": {
          "movement_indicator": "b2b",
          "not_at_risk": true
        }
      },
      "insurance_provider": "none",
      "order_source_code": "amazon_ca",
      "packages": [
        {
          "package_id": "se-123456",
          "package_code": "thick_envelope",
          "package_name": "Flat Rate Envelope",
          "weight": {
            "value": 23,
            "unit": "pound"
          },
          "dimensions": {
            "unit": "inch",
            "length": 2,
            "width": 2,
            "height": 1
          },
          "insured_value": [
            {
              "currency": "usd",
              "amount": 0
            }
          ],
          "label_messages": {
            "reference1": "Reference",
            "reference2": "Reference 2",
            "reference3": "Reference 3"
          },
          "external_package_id": "se-1234545",
          "content_description": "Hand knitted wool socks",
          "products": []
        }
      ],
      "comparison_rate_type": "retail"
    },
    "is_return_label": true,
    "rma_number": "asd12323",
    "charge_event": "carrier_default",
    "outbound_label_id": "se-28529731",
    "test_label": true,
    "validate_address": "validate_and_clean",
    "label_download_type": "url",
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
  }'

Responses

The requested object creation was a success.

Bodyapplication/json
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

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

Example: "se-28529731"
statusstring(label_status)read-onlyrequired

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

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

Example: "se-28529731"
ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-onlyrequired

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 ShipStation .

Example: "2018-09-23"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
shipment_costobject(monetary_value)read-onlyrequired

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

shipment_cost.​currencystring(currency)required

The currencies that are supported by ShipStation are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html

shipment_cost.​amountnumber>= 0required

The monetary amount, in the specified currency.

Example: 12
insurance_costobject(monetary_value)read-onlyrequired

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

insurance_cost.​currencystring(currency)required

The currencies that are supported by ShipStation are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html

insurance_cost.​amountnumber>= 0required

The monetary amount, in the specified currency.

Example: 12
requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

tracking_numberstringnon-emptyread-onlyrequired

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

Example: "782758401696"
is_return_labelbooleanrequired

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

Example: true
rma_numberstring or nullrequired

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

Example: "asd12323"
is_internationalbooleanread-onlyrequired

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

Example: true
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

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

Example: "se-28529731"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-onlyrequired

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

Example: "se-28529731"
charge_eventstring(label_charge_event)required

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-onlyrequired

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

Example: "usps_first_class_mail"
package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-onlyrequired

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

Example: "small_flat_rate_box"
voidedbooleanread-onlyrequired

Indicates whether the label has been [voided]

Example: true
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
label_formatstring(label_format)required

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)required

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)required

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.

Default "4x6"
Enum"4x6""letter"
trackablebooleanread-onlyrequired

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.

Example: true
label_image_idstring or null(image_id)>= 4 charactersrequired

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-onlyrequired

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

Example: "dhl_express"
tracking_statusstring(tracking_status)read-onlyrequired

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
label_downloadobject(label_download)read-onlyrequired

Reference to the various downloadable file formats for the generated label

label_download.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
label_download.​pdfstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
label_download.​pngstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
label_download.​zplstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
form_downloadobject or null(link)read-onlyrequired

A link to a related resource, or an empty object if there is no resource to link to

form_download.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
form_download.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
paperless_downloadobject or null(paperless_download)read-onlyrequired

The paperless details which may contain elements like href, instructions and handoff_code.

paperless_download.​hrefstring(url)(url)non-empty

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
paperless_download.​instructionsstring or null

The instructions for the paperless download.

Default null
Example: "any instructions"
paperless_download.​handoff_codestring or null

The handoff code for the paperless download.

Default null
Example: "122334"
insurance_claimobject or null(link)read-onlyrequired

A link to a related resource, or an empty object if there is no resource to link to

insurance_claim.​hrefstring(url)(url)non-emptyrequired

A URL

Example: "http://api.shipstation.com/v2/labels/se-28529731"
insurance_claim.​typestringnon-empty

The type of resource, or the type of relationship to the parent resource

Example: "child"
packagesArray of objects(label_package)read-onlyrequired

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

packages[].​package_idinteger(int32)read-only

The shipment package id

Example: 1234545
packages[].​package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$

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

Example: "small_flat_rate_box"
packages[].​weightobject(weight)required

The weight of a package

packages[].​weight.​valuenumber> 0required

The weight, in the specified unit

Example: 23
packages[].​weight.​unitstring(weight_unit)required

The possible weight unit values

Enum"pound""ounce""gram""kilogram"
packages[].​dimensionsobject(dimensions)

The dimensions of a package

packages[].​insured_valueobject(monetary_value)

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

Default [{"currency":"usd","amount":0}]
packages[].​tracking_numberstring(tracking_number)non-emptyread-only

A tracking number for a package. The format depends on the carrier.

Example: "1Z932R800392060079"
packages[].​label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

packages[].​form_downloadobject(optional_link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packages[].​qr_code_downloadobject(optional_link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packages[].​paperless_downloadobject(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

packages[].​label_messagesobject(label_messages)

Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.

CarrierMax linesMax line length
USPS (Stamps.com)360
FedEx335 for the first line. 30 for additional lines.
UPS235
OnTrac225
packages[].​external_package_idstringnon-empty

An external package id.

Example: "se-1234567"
packages[].​content_descriptionstring or null[ 1 .. 35 ] characters

A short description of the package content. Required for shipments moving to, from, and through Mexico.

Example: "Hand knitted wool socks"
packages[].​sequenceinteger(int32)read-only

Package sequence

Example: 34
packages[].​has_label_documentsboolean

Whether the package has label documents available for download

Example: true
packages[].​has_form_documentsboolean

Whether the package has form documents available for download

Example: true
packages[].​has_qr_code_documentsboolean

Whether the package has QR code documents available for download

Example: true
packages[].​has_paperless_label_documentsboolean

Whether the package has paperless documents available for download

Example: true
packages[].​alternative_identifiersArray of objects or null(alternative_identifier)read-only

Alternative identifiers associated with this package.

alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "ship_date": "2018-09-23", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 12 }, "insurance_cost": { "currency": "string", "amount": 12 }, "requested_comparison_amount": { "currency": "string", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" }

Purchase label with rate id

Request

When retrieving rates for shipments using the /rates endpoint, the returned information contains a rate_id property that can be used to generate a label without having to refill in the shipment information repeatedly.

Path
rate_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Rate ID

Example: se-28529731
Bodyapplication/jsonrequired
validate_addressstring(validate_address)

The possible validate address values

Enum"no_validation""validate_only""validate_and_clean"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
label_download_typestring(label_download_type)

There are two different ways to [download a label]:

Label Download TypeDescription
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Enum"url""inline"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
curl -i -X POST \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/rates/{rate_id}' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "validate_address": "no_validation",
    "label_layout": "4x6",
    "label_format": "pdf",
    "label_download_type": "url",
    "display_scheme": "label"
  }'

Responses

The requested object creation was a success.

Bodyapplication/json
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
statusstring(label_status)read-only

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-only

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 ShipStation .

Example: "2018-09-23"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
shipment_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

insurance_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

tracking_numberstringnon-emptyread-only

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

Example: "782758401696"
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.

Example: true
rma_numberstring or null

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

Example: "asd12323"
is_internationalbooleanread-only

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

Example: true
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-only

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

Example: "usps_first_class_mail"
package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "small_flat_rate_box"
voidedbooleanread-only

Indicates whether the label has been [voided]

Example: true
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
trackablebooleanread-only

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.

Example: true
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
tracking_statusstring(tracking_status)read-only

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

form_downloadobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

paperless_downloadobject or null(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

insurance_claimobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packagesArray of objects(label_package)read-only

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "ship_date": "2018-09-23", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 12 }, "insurance_cost": { "currency": "string", "amount": 12 }, "requested_comparison_amount": { "currency": "string", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" }

Purchase label with shipment id

Request

Purchase a label using a shipment ID that has already been created with the desired address and package info.

Path
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Shipment ID

Example: se-28529731
Bodyapplication/jsonrequired
validate_addressstring(validate_address)

The possible validate address values

Enum"no_validation""validate_only""validate_and_clean"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
label_download_typestring(label_download_type)

There are two different ways to [download a label]:

Label Download TypeDescription
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Enum"url""inline"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
curl -i -X POST \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/shipment/{shipment_id}' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "validate_address": "no_validation",
    "label_layout": "4x6",
    "label_format": "pdf",
    "label_download_type": "url",
    "display_scheme": "label"
  }'

Responses

The requested object creation was a success.

Bodyapplication/json
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
statusstring(label_status)read-only

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-only

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 ShipStation .

Example: "2018-09-23"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
shipment_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

insurance_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

tracking_numberstringnon-emptyread-only

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

Example: "782758401696"
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.

Example: true
rma_numberstring or null

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

Example: "asd12323"
is_internationalbooleanread-only

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

Example: true
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-only

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

Example: "usps_first_class_mail"
package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "small_flat_rate_box"
voidedbooleanread-only

Indicates whether the label has been [voided]

Example: true
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
trackablebooleanread-only

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.

Example: true
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
tracking_statusstring(tracking_status)read-only

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

form_downloadobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

paperless_downloadobject or null(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

insurance_claimobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packagesArray of objects(label_package)read-only

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "ship_date": "2018-09-23", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 12 }, "insurance_cost": { "currency": "string", "amount": 12 }, "requested_comparison_amount": { "currency": "string", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" }

Get label by id

Request

Retrieve information for individual labels.

Path
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Label ID

Example: se-28529731
Query
label_download_typestring(label_download_type)

There are two different ways to [download a label]:

Label Download TypeDescription
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Enum"url""inline"
Example: label_download_type=url
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/{label_id}?label_download_type=url' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
statusstring(label_status)read-only

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-only

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 ShipStation .

Example: "2018-09-23"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
shipment_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

insurance_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

tracking_numberstringnon-emptyread-only

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

Example: "782758401696"
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.

Example: true
rma_numberstring or null

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

Example: "asd12323"
is_internationalbooleanread-only

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

Example: true
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-only

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

Example: "usps_first_class_mail"
package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "small_flat_rate_box"
voidedbooleanread-only

Indicates whether the label has been [voided]

Example: true
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
trackablebooleanread-only

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.

Example: true
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
tracking_statusstring(tracking_status)read-only

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

form_downloadobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

paperless_downloadobject or null(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

insurance_claimobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packagesArray of objects(label_package)read-only

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "ship_date": "2018-09-23", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 12 }, "insurance_cost": { "currency": "string", "amount": 12 }, "requested_comparison_amount": { "currency": "string", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" }

Create a return label

Request

Create a return label

Path
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Label ID

Example: se-28529731
Bodyapplication/jsonrequired
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
label_download_typestring(label_download_type)write-only

There are two different ways to [download a label]:

Label Download TypeDescription
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Default "url"
Enum"url""inline"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
curl -i -X POST \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/{label_id}/return' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "charge_event": "carrier_default",
    "label_layout": "4x6",
    "label_format": "pdf",
    "label_download_type": "url",
    "display_scheme": "label",
    "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
  }'

Responses

The request was a success.

Bodyapplication/json
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
statusstring(label_status)read-only

The possible statuses that a [shipping label] can be in.

StatusDescription
processingWhen 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.
completedThe label was successfully created
errorThe label could not be created due to an error, such as an invalid delivery address
voidedThe label has been [voided]
Enum"processing""completed""error""voided"
Example: "completed"
shipment_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
ship_datestring(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...read-only

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 ShipStation .

Example: "2018-09-23"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
shipment_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

insurance_costobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

requested_comparison_amountobject(monetary_value)read-only

A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

tracking_numberstringnon-emptyread-only

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

Example: "782758401696"
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.

Example: true
rma_numberstring or null

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

Example: "asd12323"
is_internationalbooleanread-only

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

Example: true
batch_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
carrier_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$read-only

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

Example: "se-28529731"
charge_eventstring(label_charge_event)

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

Enum"carrier_default""on_creation""on_carrier_acceptance"
service_codestring(service_code)^[a-z0-9]+(_[a-z0-9-]+)* ?$read-only

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

Example: "usps_first_class_mail"
package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "small_flat_rate_box"
voidedbooleanread-only

Indicates whether the label has been [voided]

Example: true
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
label_formatstring(label_format)

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 FormatSupported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
Default "pdf"
Enum"pdf""png""zpl"
display_schemestring(display_scheme)

The display format that the label should be shown in.

Default "label"
Enum"label""qr_code""label_and_qr_code""paperless""label_and_paperless"
label_layoutstring(label_layout)

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.

Default "4x6"
Enum"4x6""letter"
trackablebooleanread-only

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.

Example: true
label_image_idstring or null(image_id)>= 4 characters

Used to identify an image resource.

Example: "img_DtBXupDBxREpHnwEXhTfgK"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
tracking_statusstring(tracking_status)read-only

The different statuses that can apply to a shipment.

Enum"unknown""in_transit""error""delivered"
label_downloadobject(label_download)read-only

Reference to the various downloadable file formats for the generated label

form_downloadobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

paperless_downloadobject or null(paperless_download)read-only

The paperless details which may contain elements like href, instructions and handoff_code.

insurance_claimobject or null(link)read-only

A link to a related resource, or an empty object if there is no resource to link to

packagesArray of objects(label_package)read-only

The label's package(s).

Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

alternative_identifiersArray of objects or null(alternative_identifier)read-only

Additional information some carriers may provide by which to identify a given label in their system.

tracking_urlstring or nullread-only

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

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "ship_date": "2018-09-23", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 12 }, "insurance_cost": { "currency": "string", "amount": 12 }, "requested_comparison_amount": { "currency": "string", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" }

Get label tracking information

Request

Retrieve the label's tracking information

Path
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Label ID

Example: se-28529731
curl -i -X GET \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/{label_id}/track' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
tracking_numberstring(tracking_number)non-emptyrequired

A tracking number for a package. The format depends on the carrier.

Example: "1Z932R800392060079"
tracking_urlstringread-only

Carrier Tracking Url, if available

Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
status_codestring(status_detail_code)read-onlyrequired

The tracking status detail codes

ValueDescription
COLLECTION_FAILEDShipment pickup failed. The delivery company will try again soon.
AWAITING_DESPATCHYour shipment is ready to go and is waiting for pickup.
COLLECTION_REQUESTEDYour shipment pickup has been scheduled.
DESPATCHEDYour shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey.
ELEC_ADVICE_RECD_BY_CARRIERYour shipment is now in the carrier's system.
NOT_YET_RECEIVED_BY_CARRIERThe sender couldn't hand over your shipment. The delivery company will try to collect it again.
COLLECTION_MADEYour shipment has been picked up by the carrier.
ATTEMPTED_DELIVERYDelivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_2NDSecond delivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_3RDThird delivery attempt failed. Please check the carrier's instructions for next steps.
COD_AMOUNT_NOT_PAIDDelivery failed due to unpaid cash on delivery. Please check carrier instructions.
COD_AMOUNT_PAIDCash on delivery payment received.
CUSTOMER_CARDEDDelivery attempt failed. Please check for delivery instructions left by the carrier.
CUSTOMER_IDENTIFICATION_FAILEDThere was a recipient identification issue. Please check carrier instructions.
INVALID_METHOD_OF_PAYMENTDelivery failed due to incorrect payment. Please check carrier instructions.
NO_ACCESS_TO_RECIPIENTS_ADDRESSDelivery couldn't be completed due to issues with accessing address. Please follow carrier instructions.
OUT_FOR_DELIVERYYour shipment is out for delivery.
DELIVEREDYour shipment has been delivered.
DELIVERED_DAMAGEDYour shipment was delivered but arrived damaged.
DELIVERED_IN_PARTPart of your shipment has been delivered. Check for updates on the rest.
DELIVERED_SPECIFIED_SAFE_PLACEYour shipment has been left in your designated safe place.
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATIONYour shipment was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details.
DELIVERED_TO_NEIGHBOURYour shipment was delivered to your neighbor.
DELIVERED_TO_PO_BOXYour shipment was delivered to your PO Box.
PARCEL_COLLECTED_FROM_PICKUP_POINTYour package has been picked up from the collection point.
POST_TRANSIT_STATUSThe carrier has added more information about your delivery.
PROOF_OF_DELIVERYDelivery confirmed.
CANCELLEDYour shipment has been cancelled.
CANCELLED_BEFORE_DESPATCHYour shipment was cancelled before pickup. Contact the sender if unexpected.
CUSTOMER_MOVEDRecipient not at address. Your shipment is being returned.
HAZARDOUS_PROHIBITEDYour parcel contained a prohibited item and is being returned. Contact the sender.
NOT_COLLECTED_FROM_PICKUP_POINTShipment not collected from the pickup point. Your parcel is being returned to the sender.
NOT_DELIVEREDDelivery attempts failed. Your parcel is being returned to the sender.
NOT_DELIVERED_ADDRESSEE_DECEASEDDelivery not possible due to recipient's passing.
PARCEL_DAMAGEDYour parcel was damaged and can't be delivered. It's being returned. Contact the sender.
PARCEL_DISPOSEDShipment was disposed of. Contact the sender for details.
PARCEL_LOSTYour parcel is lost. Contact the sender for next steps.
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITYShipment is too large/heavy for delivery. Being returned. Contact sender.
REFUSED_BY_CUSTOMERDelivery refused. Shipment being returned. Contact the sender.
RETURN_TO_SENDERYour shipment is being returned to the sender. Contact them for details.
ADDRESS_QUERYThere's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier.
CARRIER_DELAYSThere's a delivery delay. We'll update you when there's more info.
CUSTOMS_CLEAREDYour shipment has passed customs clearance.
CUSTOMS_PROCESSINGYour shipment is going through customs.
DELAYED_NOT_CARRIERUnexpected delivery delay. We'll update you soon.
DELIVERY_ARRANGED_WITH_RECIPIENTDelivery arranged by recipient.
HELD_BY_CARRIERYour shipment is on hold due to a carrier issue. We'll update you soon.
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSINGYour shipment is held by carrier due to customs issues. We'll update you.
HELD_BY_CUSTOMSYour shipment is held in customs. We'll update you.
HELD_BY_EXPORT_CUSTOMSYour shipment is held in export customs. We'll update you.
HELD_BY_IMPORT_CUSTOMSYour shipment is held in import customs. We'll update you.
HUB_SCAN_OUTYour shipment is at the main delivery depot.
IN_TRANSITYour shipment is on its way between depots.
INCORRECT_DECLARATIONIncorrect shipment dimensions. Delivery may be delayed or returned. We'll update you.
INFORMATIONThe carrier has shared additional shipment information.
MISSORTEDYour shipment was missorted. There might be a delivery delay. We'll update you.
PARCEL_OVER_LABELLEDYour shipment was over labelled by the delivery company to improve processing.
PARCEL_REPACKEDYour shipment packaging was damaged. It's being repacked. This might delay delivery.
PARCEL_UPDATE_NOTIFICATION_VIA_EMAILYou've received an email with a shipment update.
PARCEL_UPDATE_NOTIFICATION_VIA_SMSYou've received a text message with a shipment update.
RECEIVED_BY_CARRIERYour shipment has been received by the carrier.
RECEIVED_LOCAL_DELIVERY_DEPOTYour shipment is at the local delivery depot, ready for delivery.
ROUTING_ERRORYour shipment was sent to the wrong place. There might be a delay.
SUB_CONTRACTOR_EVENTYour shipment is with the local delivery partner.
SUB_CONTRACTOR_RECEIVEDYour shipment has been received by the local delivery partner.
RECD_BY_CARRIER_NO_ELEC_ADVICEThere's a system issue with your shipment. Tracking updates might be delayed.
AWAITING_ELECTRONIC_ADVICEYour tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup.
AWAITING_COLLECTION_FROM_PICKUP_POINTYour shipment is ready for pickup at the specified location.
COLLECT_AT_LOCAL_POYour shipment has been redirected to the local post office for pickup. Check carrier instructions.
CUSTOMER_TO_COLLECT_FROM_CARRIERYour shipment is being held for pickup. Check carrier instructions.
DELIVERED_TO_LOCKER_COLLECTION_POINTYour shipment has been delivered to your locker.
CARRIER_STATUS_NOT_MAPPEDStatus not mapped. Please check the carrier's website for updates.
Enum"COLLECTION_FAILED""AWAITING_DESPATCH""COLLECTION_REQUESTED""DESPATCHED""ELEC_ADVICE_RECD_BY_CARRIER""NOT_YET_RECEIVED_BY_CARRIER""COLLECTION_MADE""ATTEMPTED_DELIVERY""ATTEMPTED_DELIVERY_2ND""ATTEMPTED_DELIVERY_3RD"
Example: "COLLECTION_FAILED"
status_detail_codestring(status_detail_code)read-only

The tracking status detail codes

ValueDescription
COLLECTION_FAILEDShipment pickup failed. The delivery company will try again soon.
AWAITING_DESPATCHYour shipment is ready to go and is waiting for pickup.
COLLECTION_REQUESTEDYour shipment pickup has been scheduled.
DESPATCHEDYour shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey.
ELEC_ADVICE_RECD_BY_CARRIERYour shipment is now in the carrier's system.
NOT_YET_RECEIVED_BY_CARRIERThe sender couldn't hand over your shipment. The delivery company will try to collect it again.
COLLECTION_MADEYour shipment has been picked up by the carrier.
ATTEMPTED_DELIVERYDelivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_2NDSecond delivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_3RDThird delivery attempt failed. Please check the carrier's instructions for next steps.
COD_AMOUNT_NOT_PAIDDelivery failed due to unpaid cash on delivery. Please check carrier instructions.
COD_AMOUNT_PAIDCash on delivery payment received.
CUSTOMER_CARDEDDelivery attempt failed. Please check for delivery instructions left by the carrier.
CUSTOMER_IDENTIFICATION_FAILEDThere was a recipient identification issue. Please check carrier instructions.
INVALID_METHOD_OF_PAYMENTDelivery failed due to incorrect payment. Please check carrier instructions.
NO_ACCESS_TO_RECIPIENTS_ADDRESSDelivery couldn't be completed due to issues with accessing address. Please follow carrier instructions.
OUT_FOR_DELIVERYYour shipment is out for delivery.
DELIVEREDYour shipment has been delivered.
DELIVERED_DAMAGEDYour shipment was delivered but arrived damaged.
DELIVERED_IN_PARTPart of your shipment has been delivered. Check for updates on the rest.
DELIVERED_SPECIFIED_SAFE_PLACEYour shipment has been left in your designated safe place.
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATIONYour shipment was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details.
DELIVERED_TO_NEIGHBOURYour shipment was delivered to your neighbor.
DELIVERED_TO_PO_BOXYour shipment was delivered to your PO Box.
PARCEL_COLLECTED_FROM_PICKUP_POINTYour package has been picked up from the collection point.
POST_TRANSIT_STATUSThe carrier has added more information about your delivery.
PROOF_OF_DELIVERYDelivery confirmed.
CANCELLEDYour shipment has been cancelled.
CANCELLED_BEFORE_DESPATCHYour shipment was cancelled before pickup. Contact the sender if unexpected.
CUSTOMER_MOVEDRecipient not at address. Your shipment is being returned.
HAZARDOUS_PROHIBITEDYour parcel contained a prohibited item and is being returned. Contact the sender.
NOT_COLLECTED_FROM_PICKUP_POINTShipment not collected from the pickup point. Your parcel is being returned to the sender.
NOT_DELIVEREDDelivery attempts failed. Your parcel is being returned to the sender.
NOT_DELIVERED_ADDRESSEE_DECEASEDDelivery not possible due to recipient's passing.
PARCEL_DAMAGEDYour parcel was damaged and can't be delivered. It's being returned. Contact the sender.
PARCEL_DISPOSEDShipment was disposed of. Contact the sender for details.
PARCEL_LOSTYour parcel is lost. Contact the sender for next steps.
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITYShipment is too large/heavy for delivery. Being returned. Contact sender.
REFUSED_BY_CUSTOMERDelivery refused. Shipment being returned. Contact the sender.
RETURN_TO_SENDERYour shipment is being returned to the sender. Contact them for details.
ADDRESS_QUERYThere's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier.
CARRIER_DELAYSThere's a delivery delay. We'll update you when there's more info.
CUSTOMS_CLEAREDYour shipment has passed customs clearance.
CUSTOMS_PROCESSINGYour shipment is going through customs.
DELAYED_NOT_CARRIERUnexpected delivery delay. We'll update you soon.
DELIVERY_ARRANGED_WITH_RECIPIENTDelivery arranged by recipient.
HELD_BY_CARRIERYour shipment is on hold due to a carrier issue. We'll update you soon.
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSINGYour shipment is held by carrier due to customs issues. We'll update you.
HELD_BY_CUSTOMSYour shipment is held in customs. We'll update you.
HELD_BY_EXPORT_CUSTOMSYour shipment is held in export customs. We'll update you.
HELD_BY_IMPORT_CUSTOMSYour shipment is held in import customs. We'll update you.
HUB_SCAN_OUTYour shipment is at the main delivery depot.
IN_TRANSITYour shipment is on its way between depots.
INCORRECT_DECLARATIONIncorrect shipment dimensions. Delivery may be delayed or returned. We'll update you.
INFORMATIONThe carrier has shared additional shipment information.
MISSORTEDYour shipment was missorted. There might be a delivery delay. We'll update you.
PARCEL_OVER_LABELLEDYour shipment was over labelled by the delivery company to improve processing.
PARCEL_REPACKEDYour shipment packaging was damaged. It's being repacked. This might delay delivery.
PARCEL_UPDATE_NOTIFICATION_VIA_EMAILYou've received an email with a shipment update.
PARCEL_UPDATE_NOTIFICATION_VIA_SMSYou've received a text message with a shipment update.
RECEIVED_BY_CARRIERYour shipment has been received by the carrier.
RECEIVED_LOCAL_DELIVERY_DEPOTYour shipment is at the local delivery depot, ready for delivery.
ROUTING_ERRORYour shipment was sent to the wrong place. There might be a delay.
SUB_CONTRACTOR_EVENTYour shipment is with the local delivery partner.
SUB_CONTRACTOR_RECEIVEDYour shipment has been received by the local delivery partner.
RECD_BY_CARRIER_NO_ELEC_ADVICEThere's a system issue with your shipment. Tracking updates might be delayed.
AWAITING_ELECTRONIC_ADVICEYour tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup.
AWAITING_COLLECTION_FROM_PICKUP_POINTYour shipment is ready for pickup at the specified location.
COLLECT_AT_LOCAL_POYour shipment has been redirected to the local post office for pickup. Check carrier instructions.
CUSTOMER_TO_COLLECT_FROM_CARRIERYour shipment is being held for pickup. Check carrier instructions.
DELIVERED_TO_LOCKER_COLLECTION_POINTYour shipment has been delivered to your locker.
CARRIER_STATUS_NOT_MAPPEDStatus not mapped. Please check the carrier's website for updates.
Enum"COLLECTION_FAILED""AWAITING_DESPATCH""COLLECTION_REQUESTED""DESPATCHED""ELEC_ADVICE_RECD_BY_CARRIER""NOT_YET_RECEIVED_BY_CARRIER""COLLECTION_MADE""ATTEMPTED_DELIVERY""ATTEMPTED_DELIVERY_2ND""ATTEMPTED_DELIVERY_3RD"
Example: "DELIVERED"
carrier_codestring(carrier_code)^[a-z0-9]+(_[a-z0-9]+)*$read-only

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

Example: "dhl_express"
carrier_idinteger(int32)read-only

The unique ID of the [carrier account] that was used to create this label

Example: 1234567
status_descriptionstring>= 0 charactersread-only

Status description

Example: "Delivered"
status_detail_descriptionstring>= 0 charactersread-only

Status detail description

Example: "Your shipment has been delivered."
carrier_status_codestringnon-emptyread-onlyrequired

Carrier status code

Example: "1"
carrier_detail_codestringnon-emptyread-only

Carrier detail code

Example: "OT"
carrier_status_descriptionstring>= 0 charactersread-only

carrier status description

Example: "Your item was delivered in or at the mailbox at 9:10 am on March"
ship_datestring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
estimated_delivery_datestring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...required

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
actual_delivery_datestring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
exception_descriptionstring>= 0 charactersread-only

Exception description

Example: "this is exception description"
eventsArray of objects(track_event)read-onlyrequired

The events that have occured during the lifetime of this tracking number.

events[].​occurred_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...required

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
events[].​carrier_occurred_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...

An ISO 8601 string that represents a date and time.

Example: "2018-09-23T15:00:00.000Z"
events[].​descriptionstring>= 0 charactersread-only

Event description

Example: "Delivered, In/At Mailbox"
events[].​city_localitystring>= 0 charactersread-onlyrequired

City locality

Example: "AUSTIN"
events[].​state_provincestring>= 2 charactersread-onlyrequired

State province

Example: "TX"
events[].​postal_codestring>= 0 charactersread-onlyrequired

Postal code

Example: "78756"
events[].​country_codestring(country_code)= 2 characters
Example: "CA"
events[].​company_namestring>= 0 charactersread-only

Company Name

Example: "Stamps.com"
events[].​signerstring>= 0 charactersread-only

Signer information

Example: ""
events[].​event_codestring>= 0 characters

Event Code

Example: "DLD"
events[].​carrier_detail_codestringnon-emptyread-onlyrequired

Carrier detail code

Example: "OT"
events[].​status_codestring(status_detail_code)read-onlyrequired

The tracking status detail codes

ValueDescription
COLLECTION_FAILEDShipment pickup failed. The delivery company will try again soon.
AWAITING_DESPATCHYour shipment is ready to go and is waiting for pickup.
COLLECTION_REQUESTEDYour shipment pickup has been scheduled.
DESPATCHEDYour shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey.
ELEC_ADVICE_RECD_BY_CARRIERYour shipment is now in the carrier's system.
NOT_YET_RECEIVED_BY_CARRIERThe sender couldn't hand over your shipment. The delivery company will try to collect it again.
COLLECTION_MADEYour shipment has been picked up by the carrier.
ATTEMPTED_DELIVERYDelivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_2NDSecond delivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_3RDThird delivery attempt failed. Please check the carrier's instructions for next steps.
COD_AMOUNT_NOT_PAIDDelivery failed due to unpaid cash on delivery. Please check carrier instructions.
COD_AMOUNT_PAIDCash on delivery payment received.
CUSTOMER_CARDEDDelivery attempt failed. Please check for delivery instructions left by the carrier.
CUSTOMER_IDENTIFICATION_FAILEDThere was a recipient identification issue. Please check carrier instructions.
INVALID_METHOD_OF_PAYMENTDelivery failed due to incorrect payment. Please check carrier instructions.
NO_ACCESS_TO_RECIPIENTS_ADDRESSDelivery couldn't be completed due to issues with accessing address. Please follow carrier instructions.
OUT_FOR_DELIVERYYour shipment is out for delivery.
DELIVEREDYour shipment has been delivered.
DELIVERED_DAMAGEDYour shipment was delivered but arrived damaged.
DELIVERED_IN_PARTPart of your shipment has been delivered. Check for updates on the rest.
DELIVERED_SPECIFIED_SAFE_PLACEYour shipment has been left in your designated safe place.
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATIONYour shipment was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details.
DELIVERED_TO_NEIGHBOURYour shipment was delivered to your neighbor.
DELIVERED_TO_PO_BOXYour shipment was delivered to your PO Box.
PARCEL_COLLECTED_FROM_PICKUP_POINTYour package has been picked up from the collection point.
POST_TRANSIT_STATUSThe carrier has added more information about your delivery.
PROOF_OF_DELIVERYDelivery confirmed.
CANCELLEDYour shipment has been cancelled.
CANCELLED_BEFORE_DESPATCHYour shipment was cancelled before pickup. Contact the sender if unexpected.
CUSTOMER_MOVEDRecipient not at address. Your shipment is being returned.
HAZARDOUS_PROHIBITEDYour parcel contained a prohibited item and is being returned. Contact the sender.
NOT_COLLECTED_FROM_PICKUP_POINTShipment not collected from the pickup point. Your parcel is being returned to the sender.
NOT_DELIVEREDDelivery attempts failed. Your parcel is being returned to the sender.
NOT_DELIVERED_ADDRESSEE_DECEASEDDelivery not possible due to recipient's passing.
PARCEL_DAMAGEDYour parcel was damaged and can't be delivered. It's being returned. Contact the sender.
PARCEL_DISPOSEDShipment was disposed of. Contact the sender for details.
PARCEL_LOSTYour parcel is lost. Contact the sender for next steps.
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITYShipment is too large/heavy for delivery. Being returned. Contact sender.
REFUSED_BY_CUSTOMERDelivery refused. Shipment being returned. Contact the sender.
RETURN_TO_SENDERYour shipment is being returned to the sender. Contact them for details.
ADDRESS_QUERYThere's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier.
CARRIER_DELAYSThere's a delivery delay. We'll update you when there's more info.
CUSTOMS_CLEAREDYour shipment has passed customs clearance.
CUSTOMS_PROCESSINGYour shipment is going through customs.
DELAYED_NOT_CARRIERUnexpected delivery delay. We'll update you soon.
DELIVERY_ARRANGED_WITH_RECIPIENTDelivery arranged by recipient.
HELD_BY_CARRIERYour shipment is on hold due to a carrier issue. We'll update you soon.
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSINGYour shipment is held by carrier due to customs issues. We'll update you.
HELD_BY_CUSTOMSYour shipment is held in customs. We'll update you.
HELD_BY_EXPORT_CUSTOMSYour shipment is held in export customs. We'll update you.
HELD_BY_IMPORT_CUSTOMSYour shipment is held in import customs. We'll update you.
HUB_SCAN_OUTYour shipment is at the main delivery depot.
IN_TRANSITYour shipment is on its way between depots.
INCORRECT_DECLARATIONIncorrect shipment dimensions. Delivery may be delayed or returned. We'll update you.
INFORMATIONThe carrier has shared additional shipment information.
MISSORTEDYour shipment was missorted. There might be a delivery delay. We'll update you.
PARCEL_OVER_LABELLEDYour shipment was over labelled by the delivery company to improve processing.
PARCEL_REPACKEDYour shipment packaging was damaged. It's being repacked. This might delay delivery.
PARCEL_UPDATE_NOTIFICATION_VIA_EMAILYou've received an email with a shipment update.
PARCEL_UPDATE_NOTIFICATION_VIA_SMSYou've received a text message with a shipment update.
RECEIVED_BY_CARRIERYour shipment has been received by the carrier.
RECEIVED_LOCAL_DELIVERY_DEPOTYour shipment is at the local delivery depot, ready for delivery.
ROUTING_ERRORYour shipment was sent to the wrong place. There might be a delay.
SUB_CONTRACTOR_EVENTYour shipment is with the local delivery partner.
SUB_CONTRACTOR_RECEIVEDYour shipment has been received by the local delivery partner.
RECD_BY_CARRIER_NO_ELEC_ADVICEThere's a system issue with your shipment. Tracking updates might be delayed.
AWAITING_ELECTRONIC_ADVICEYour tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup.
AWAITING_COLLECTION_FROM_PICKUP_POINTYour shipment is ready for pickup at the specified location.
COLLECT_AT_LOCAL_POYour shipment has been redirected to the local post office for pickup. Check carrier instructions.
CUSTOMER_TO_COLLECT_FROM_CARRIERYour shipment is being held for pickup. Check carrier instructions.
DELIVERED_TO_LOCKER_COLLECTION_POINTYour shipment has been delivered to your locker.
CARRIER_STATUS_NOT_MAPPEDStatus not mapped. Please check the carrier's website for updates.
Enum"COLLECTION_FAILED""AWAITING_DESPATCH""COLLECTION_REQUESTED""DESPATCHED""ELEC_ADVICE_RECD_BY_CARRIER""NOT_YET_RECEIVED_BY_CARRIER""COLLECTION_MADE""ATTEMPTED_DELIVERY""ATTEMPTED_DELIVERY_2ND""ATTEMPTED_DELIVERY_3RD"
Example: "COLLECTION_FAILED"
events[].​status_detail_codestring(status_detail_code)read-only

The tracking status detail codes

ValueDescription
COLLECTION_FAILEDShipment pickup failed. The delivery company will try again soon.
AWAITING_DESPATCHYour shipment is ready to go and is waiting for pickup.
COLLECTION_REQUESTEDYour shipment pickup has been scheduled.
DESPATCHEDYour shipment has been handed over to the carrier or dropped off at collection point. It will soon start its journey.
ELEC_ADVICE_RECD_BY_CARRIERYour shipment is now in the carrier's system.
NOT_YET_RECEIVED_BY_CARRIERThe sender couldn't hand over your shipment. The delivery company will try to collect it again.
COLLECTION_MADEYour shipment has been picked up by the carrier.
ATTEMPTED_DELIVERYDelivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_2NDSecond delivery attempt failed. Please check the carrier's instructions for next steps.
ATTEMPTED_DELIVERY_3RDThird delivery attempt failed. Please check the carrier's instructions for next steps.
COD_AMOUNT_NOT_PAIDDelivery failed due to unpaid cash on delivery. Please check carrier instructions.
COD_AMOUNT_PAIDCash on delivery payment received.
CUSTOMER_CARDEDDelivery attempt failed. Please check for delivery instructions left by the carrier.
CUSTOMER_IDENTIFICATION_FAILEDThere was a recipient identification issue. Please check carrier instructions.
INVALID_METHOD_OF_PAYMENTDelivery failed due to incorrect payment. Please check carrier instructions.
NO_ACCESS_TO_RECIPIENTS_ADDRESSDelivery couldn't be completed due to issues with accessing address. Please follow carrier instructions.
OUT_FOR_DELIVERYYour shipment is out for delivery.
DELIVEREDYour shipment has been delivered.
DELIVERED_DAMAGEDYour shipment was delivered but arrived damaged.
DELIVERED_IN_PARTPart of your shipment has been delivered. Check for updates on the rest.
DELIVERED_SPECIFIED_SAFE_PLACEYour shipment has been left in your designated safe place.
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATIONYour shipment was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details.
DELIVERED_TO_NEIGHBOURYour shipment was delivered to your neighbor.
DELIVERED_TO_PO_BOXYour shipment was delivered to your PO Box.
PARCEL_COLLECTED_FROM_PICKUP_POINTYour package has been picked up from the collection point.
POST_TRANSIT_STATUSThe carrier has added more information about your delivery.
PROOF_OF_DELIVERYDelivery confirmed.
CANCELLEDYour shipment has been cancelled.
CANCELLED_BEFORE_DESPATCHYour shipment was cancelled before pickup. Contact the sender if unexpected.
CUSTOMER_MOVEDRecipient not at address. Your shipment is being returned.
HAZARDOUS_PROHIBITEDYour parcel contained a prohibited item and is being returned. Contact the sender.
NOT_COLLECTED_FROM_PICKUP_POINTShipment not collected from the pickup point. Your parcel is being returned to the sender.
NOT_DELIVEREDDelivery attempts failed. Your parcel is being returned to the sender.
NOT_DELIVERED_ADDRESSEE_DECEASEDDelivery not possible due to recipient's passing.
PARCEL_DAMAGEDYour parcel was damaged and can't be delivered. It's being returned. Contact the sender.
PARCEL_DISPOSEDShipment was disposed of. Contact the sender for details.
PARCEL_LOSTYour parcel is lost. Contact the sender for next steps.
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITYShipment is too large/heavy for delivery. Being returned. Contact sender.
REFUSED_BY_CUSTOMERDelivery refused. Shipment being returned. Contact the sender.
RETURN_TO_SENDERYour shipment is being returned to the sender. Contact them for details.
ADDRESS_QUERYThere's an issue with your delivery address. This may cause a delay or return. Contact sender or carrier.
CARRIER_DELAYSThere's a delivery delay. We'll update you when there's more info.
CUSTOMS_CLEAREDYour shipment has passed customs clearance.
CUSTOMS_PROCESSINGYour shipment is going through customs.
DELAYED_NOT_CARRIERUnexpected delivery delay. We'll update you soon.
DELIVERY_ARRANGED_WITH_RECIPIENTDelivery arranged by recipient.
HELD_BY_CARRIERYour shipment is on hold due to a carrier issue. We'll update you soon.
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSINGYour shipment is held by carrier due to customs issues. We'll update you.
HELD_BY_CUSTOMSYour shipment is held in customs. We'll update you.
HELD_BY_EXPORT_CUSTOMSYour shipment is held in export customs. We'll update you.
HELD_BY_IMPORT_CUSTOMSYour shipment is held in import customs. We'll update you.
HUB_SCAN_OUTYour shipment is at the main delivery depot.
IN_TRANSITYour shipment is on its way between depots.
INCORRECT_DECLARATIONIncorrect shipment dimensions. Delivery may be delayed or returned. We'll update you.
INFORMATIONThe carrier has shared additional shipment information.
MISSORTEDYour shipment was missorted. There might be a delivery delay. We'll update you.
PARCEL_OVER_LABELLEDYour shipment was over labelled by the delivery company to improve processing.
PARCEL_REPACKEDYour shipment packaging was damaged. It's being repacked. This might delay delivery.
PARCEL_UPDATE_NOTIFICATION_VIA_EMAILYou've received an email with a shipment update.
PARCEL_UPDATE_NOTIFICATION_VIA_SMSYou've received a text message with a shipment update.
RECEIVED_BY_CARRIERYour shipment has been received by the carrier.
RECEIVED_LOCAL_DELIVERY_DEPOTYour shipment is at the local delivery depot, ready for delivery.
ROUTING_ERRORYour shipment was sent to the wrong place. There might be a delay.
SUB_CONTRACTOR_EVENTYour shipment is with the local delivery partner.
SUB_CONTRACTOR_RECEIVEDYour shipment has been received by the local delivery partner.
RECD_BY_CARRIER_NO_ELEC_ADVICEThere's a system issue with your shipment. Tracking updates might be delayed.
AWAITING_ELECTRONIC_ADVICEYour tracking number is ready. Your shipment is waiting to be registered in the carrier system and scheduled for pickup.
AWAITING_COLLECTION_FROM_PICKUP_POINTYour shipment is ready for pickup at the specified location.
COLLECT_AT_LOCAL_POYour shipment has been redirected to the local post office for pickup. Check carrier instructions.
CUSTOMER_TO_COLLECT_FROM_CARRIERYour shipment is being held for pickup. Check carrier instructions.
DELIVERED_TO_LOCKER_COLLECTION_POINTYour shipment has been delivered to your locker.
CARRIER_STATUS_NOT_MAPPEDStatus not mapped. Please check the carrier's website for updates.
Enum"COLLECTION_FAILED""AWAITING_DESPATCH""COLLECTION_REQUESTED""DESPATCHED""ELEC_ADVICE_RECD_BY_CARRIER""NOT_YET_RECEIVED_BY_CARRIER""COLLECTION_MADE""ATTEMPTED_DELIVERY""ATTEMPTED_DELIVERY_2ND""ATTEMPTED_DELIVERY_3RD"
Example: "IN_TRANSIT"
events[].​status_descriptionstringnon-emptyread-onlyrequired

Event Status Description

Example: "In Transit"
events[].​status_detail_descriptionstring>= 0 charactersread-only

Event Status Detail Description

Example: "Your shipment is on its way between depots."
events[].​carrier_status_codestringnon-emptyread-onlyrequired

Carrier status code

Example: "01"
events[].​carrier_status_descriptionstring>= 0 charactersread-onlyrequired

carrier status description

Example: "Your item was delivered in or at the mailbox at 9:10 am on March"
events[].​latitudenumber(double)[ -90 .. 90 ]

Latitude coordinate of tracking event.

Example: 89
events[].​longitudenumber(double)[ -180 .. 180 ]

Longitude coordinate of tracking event.

Example: 23
Response
application/json
{ "tracking_number": "1Z932R800392060079", "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "status_code": "COLLECTION_FAILED", "status_detail_code": "DELIVERED", "carrier_code": "dhl_express", "carrier_id": 1234567, "status_description": "Delivered", "status_detail_description": "Your shipment has been delivered.", "carrier_status_code": "1", "carrier_detail_code": "OT", "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March", "ship_date": "2024-12-23T00:00:00.000Z", "estimated_delivery_date": "2018-09-23T15:00:00.000Z", "actual_delivery_date": "2018-09-23T15:00:00.000Z", "exception_description": "this is exception description", "events": [ {} ] }

Void a label by id

Request

Void a label by ID to get a refund.

Path
label_idstring(se_id)[ 1 .. 25 ] characters^se(-[a-z0-9]+)+$required

Label ID

Example: se-28529731
curl -i -X PUT \
  'https://docs.shipstation.com/_mock/openapi/v2/labels/{label_id}/void' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

The request was a success.

Bodyapplication/json
approvedbooleanread-onlyrequired

Indicates whether the attempt to void the label was successful

Example: false
messagestring>= 0 charactersread-onlyrequired
Example: "Unable to delete FedEx shipment. Unable to retrieve record from database."
reason_codestring(reason_code)read-only

The possible normalized reasons a label void request may not have been approved

Enum"unknown""unspecified""validation_failed""label_not_found_within_void_period""label_already_used""label_already_voided""contact_carrier"
Example: "label_not_found_within_void_period"
Response
application/json
{ "approved": false, "message": "Unable to delete FedEx shipment. Unable to retrieve record from database.", "reason_code": "label_not_found_within_void_period" }

Manifests

A manifest is a document that provides a list of the day's shipments. It typically contains a barcode that allows the pickup driver to scan a single document to register all shipments, rather than scanning each shipment individually.

Operations

Package Pickups

Scheduled pickups and manage pickup requests for supported carriers.

Operations

Package Types

Create custom package types to use for your shipments, rather than the carriers' default package types.

Operations

Rates

Quickly compare rates using the Rates endpoint. You can see and compare rates for the carriers connected to your account (as long as they support sending rates).

Operations

Shipments

Shipments are at the core of most ShipStation capabilities. Shipment objects are required for cretaing labels and manifests, as well as getting rates.

Operations

Tags

Tags are text-based identifiers you can add to shipments to help in your shipment management workflows.

Operations

Tracking

Use the tracking endpoint to stop receiving tracking updates (more dedicated tracking endpoint methods coming soon).

Operations

Warehouses

Get warehouse details like warehouse ID and related addresses using the warehouses endpoint.

Operations

Webhooks

Webhooks are a powerful feature that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipStation will automatically contact your servers when the stage changes. This can include parcel tracking events, notification when a batch operation completes, and more.

Operations