Label Service Limitations - Return Helper API

Each return service type checks the sender address, parcel and items before a label is created. A request that breaks a rule is rejected with a validation error that names the field. Call Get all return service types to see which service types and origin countries your account can use.

Field names follow Create return shipment: shipFrom.* is shipment.shipFrom, parcel.* is shipment.parcel, and items[] is shipment.parcel.items[].
Weights are in grams and dimensions in centimetres. Lengths are character counts.
The API orders the three dimensions longest-first before checking, so length is always the longest side.
Truncated to N chars — a longer value is shortened to N characters and the request continues. For a combined limit, characters are removed from the end of the last address line first. Max N chars — a longer value is rejected.
Every service requires shipFrom.country, shipFrom.contactName, shipFrom.street1 and shipFrom.postalCode. The tables list the rules each service adds.
Optional fields are checked only when sent. Omit an optional field instead of sending an empty string.

United Kingdom

Royal Mail Tracked Returns 48

Service type codes: RETURN_POSTMEN_RM_BIR (Royal Mail Tracked Returns 48), RETURN_RM48_QRCODE_BIR_GBR (Royal Mail Tracked Returns 48 - QR Code)

Field	Required	Limit
shipFrom.country	Yes	Must be `gbr`
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Truncated to 60 chars
shipFrom.street2	No	Truncated to 60 chars; street1 + street2 truncated to 60 chars combined
shipFrom.street3	No	Max 60 chars; street1 + street2 + street3 truncated to 75 chars combined
shipFrom.city	Yes	Max 35 chars
shipFrom.state	No	Max 35 chars
shipFrom.postalCode	Yes	UK postcode in upper case with one space, e.g. `SW1A 1AA`
shipFrom.phone	No	Max 255 chars
shipFrom.email	No	Max 255 chars, valid email format
shipFrom.fax	No	Max 255 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0
parcel.length	Must be > 0, max 90 cm
parcel.width	Must be > 0, max 46 cm
parcel.height	Must be > 0, max 46 cm
length + width + height	Max 104 cm when length is over 61 cm

Item constraints:

Constraint	Limit
Sum of items[].weight	Must be > 0
items[].value	Must be > 0, max 9,999,999.99

DPD

Service type codes: RETURN_GBR_DPD_BIR (DPD), RETURN_DPD_QR_BIR (DPD QR CODE)

Field	Required	Limit
shipFrom.country	Yes	Must be `gbr`
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Truncated to 70 chars
shipFrom.street2	No	Truncated to 69 chars
shipFrom.street3	No	Truncated to 68 chars; street1 + street2 + street3 truncated to 70 chars combined
shipFrom.city	Yes	1–30 chars, no leading or trailing spaces
shipFrom.state	No	Max 30 chars, no leading or trailing spaces
shipFrom.postalCode	Yes	1–8 chars, no leading or trailing spaces
shipFrom.phone	Yes	10–15 chars: optional leading `+`, then digits only
shipFrom.email	No	Max 255 chars
shipFrom.fax	No	Max 50 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0
Longest side + second-longest side	Max 120 cm

Item constraints:

Constraint	Limit
Sum of items[].weight	Must be > 0
items[].value	Must be > 0

InPost – Locker & Shop Drop-off

Service type code: RETURN_INPOST_QR_BIR

Field	Required	Limit
shipFrom.email	Yes	Valid email format, single line
shipFrom.phone	Yes	UK mobile in international format: `+447` followed by 9 digits (13 chars), e.g. `+447700900123`

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0
parcel.length	Must be > 0, max 64 cm
parcel.width	Must be > 0, max 41 cm
parcel.height	Must be > 0, max 38 cm

Germany

DHL

Service type code: sdhl

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Street name. Truncated to 35 chars
shipFrom.street2	Yes	House number. Truncated to 5 chars
shipFrom.city	Yes	Max 35 chars, no leading or trailing spaces
shipFrom.postalCode	Yes	Exactly 5 digits
shipFrom.phone	No	Optional leading `+`, then 1–34 digits

DHL Retoure

Service type codes: RETURN_DHL_ECOMMERCE_DEU (DHL Retoure), RETURN_DHL_ECOMMERCE_INTL_DEU (DHL Retoure International) No field may contain the | character.

Field	Required	Limit
shipFrom.country	Yes	Valid ISO3 country code
shipFrom.contactName	Yes	Combined with your account name (`apiName` in Get API info). Truncated so that contactName, a space and `apiName` fit in 49 chars (26 chars for `RETURN_DHL_ECOMMERCE_INTL_DEU`)
shipFrom.street1	Yes	Truncated to 49 chars
shipFrom.street2	Yes	Truncated to 49 chars
shipFrom.street3	No	Max 150 chars
shipFrom.city	No	Max 30 chars
shipFrom.state	No	Max 100 chars
shipFrom.postalCode	Yes	1–10 chars
shipFrom.phone	No	Max 20 chars: digits and `- ( ) # +` only
shipFrom.email	No	Max 50 chars

Parcel constraints:

Constraint	Limit
parcel.length	Must be > 0, max 120 cm
parcel.width	Must be > 0, max 60 cm
parcel.height	Must be > 0, max 60 cm

Item constraints:

Constraint	Limit
items[].value	Must be > 0.01

France

Mondial Relay

Service type codes: RETURN_MONDIALRELAY_FRA (Mondial Relay- Dropoff), RETURN_MONDIALRELAY_EU_FRA (Mondial Relay EU- Dropoff)

Field	Required	Limit
shipFrom.country	Yes	Valid ISO3 country code
shipFrom.contactName	Yes	Truncated to 27 chars
shipFrom.street1	Yes	Truncated to 40 chars
shipFrom.street2	No	street2 + street3 max 30 chars combined
shipFrom.street3	No	street2 + street3 max 30 chars combined
shipFrom.city	Yes	—
shipFrom.postalCode	Yes	Max 10 chars
shipFrom.phone	No	Max 20 chars; must be a valid phone number for `shipFrom.country`
shipFrom.email	No	Max 48 chars, valid email format

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0
parcel.length	Must be > 0, max 240 cm
parcel.width / height	Each must be > 0
length + width + height	Must be under 250 cm

Item constraints:

Constraint	Limit
items[].value	Must be > 0

United States

FedEx Ground

Service type codes: fedex_ground (Fedex Ground-NJ), RETURN_FEDEX_GROUND_WA (Fedex Ground-WA), RETURN_FEDEX_GROUND_USCA (FedEx Ground-CA), RETURN_FEDEX_GROUND_TX (FedEx Ground-TX)

Field	Required	Limit
shipFrom.country	Yes	Must be `usa`
shipFrom.contactName	Yes	Truncated to 30 chars
shipFrom.street1	Yes	Truncated to 30 chars
shipFrom.street2	No	Truncated to 30 chars
shipFrom.street3	No	Truncated to 29 chars. When street1, street2 and street3 are all sent: max 59 chars combined
shipFrom.state	Yes	Exactly 2 chars
shipFrom.postalCode	Yes	Exactly 5 digits
shipFrom.phone	Yes	Optional leading `+`, then 10–16 digits or spaces
shipFrom.email	No	Valid email format
shipFrom.fax	No	Max 16 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0
Longest side	Max 274 cm
Length + girth	Max 419 cm (longest side + 2 × the other two sides, rounded up)

Item constraints:

Constraint	Limit
Sum of items[].weight	Must be > 0, max 68,000 g
items[].value	Must be > 0

USPS

Service type code	Name	Length + girth
`RETURN_USPS_NJ`	USPS Priority Mail-NJ	Max 274 cm
`endicia`	USPS Priority Mail-WA	Max 274 cm
`RETURN_USPS_PM_USCA`	USPS Priority Mail-CA	Max 274 cm
`RETURN_USPS_PM_USTX`	USPS Priority Mail-TX	Max 274 cm
`RETURN_USPS_QRCODE_PM_USCA`	USPS QR CODE-PM-CA	Max 274 cm
`RETURN_USPS_QRCODE_PM_USTX`	USPS QR CODE-PM-TX	Max 274 cm
`RETURN_USPS_BROKER_PM_NJ`	USPS QR CODE-PM-NJ
`RETURN_USPS_BROKER_PM_WA`	USPS QR CODE-PM-WA
`RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_NJ`	USPS Ground Advantage-NJ	Max 330 cm
`RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_WA`	USPS Ground Advantage-WA	Max 330 cm
`RETURN_USPS_GA_USCA`	USPS Ground Advantage-CA	Max 330 cm
`RETURN_USPS_GA_USTX`	USPS Ground Advantage-TX	Max 330 cm
`RETURN_USPS_QRCODE_GA_USCA`	USPS QR CODE-GA-CA	Max 330 cm
`RETURN_USPS_QRCODE_GA_USTX`	USPS QR CODE-GA-TX	Max 330 cm
`RETURN_USPS_BROKER_GA_NJ`	USPS QR CODE-GA-NJ
`RETURN_USPS_BROKER_GA_WA`	USPS QR CODE-GA-WA

Length + girth = longest side + 2 × the other two sides.

Field	Required	Limit
shipFrom.country	Yes	Must be `usa`
shipFrom.contactName	Yes	Truncated to 100 chars
shipFrom.street1	Yes	Truncated to 50 chars
shipFrom.street2	No	Truncated to 50 chars
shipFrom.street3	No	Max 100 chars
shipFrom.city	Yes	Max 50 chars
shipFrom.state	Yes	Max 50 chars
shipFrom.postalCode	Yes	Max 14 chars
shipFrom.phone	Yes	Max 30 chars
shipFrom.email	Yes	Max 50 chars, valid email format

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0, max 31,751 g
parcel.length / width / height	Each must be > 0

Canada

Canada Post

Service type code: ubi_ca

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 50 chars
shipFrom.street1	Yes	Truncated to 45 chars
shipFrom.street2	No	Truncated to 41 chars
shipFrom.street3	No	Truncated to 80 chars
shipFrom.city	Yes	Max 50 chars
shipFrom.state	Yes	Max 80 chars
shipFrom.postalCode	Yes	Max 16 chars
shipFrom.phone	Yes	Max 20 chars
shipFrom.email	Yes	Max 50 chars
orderTitle	Yes	1–50 chars. Must start with a letter; letters, digits, spaces and `# / - _ ( )` only

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0, max 30,000 g
parcel.length / width / height	Each must be > 0, max 200 cm

Australia

AU Post

Service type code: ubi_au

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Truncated to 40 chars
shipFrom.street2	No	Truncated to 60 chars
shipFrom.street3	No	Max 80 chars
shipFrom.city	Yes	Max 80 chars
shipFrom.state	Yes	Max 80 chars
shipFrom.postalCode	Yes	Max 16 chars
shipFrom.phone	No	Max 20 chars
shipFrom.email	No	Max 50 chars
orderTitle	Yes	Max 50 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0, max 22,000 g
parcel.length / width / height	Each must be > 0, max 105 cm
length × width × height	Max 250,000 cm³

Hong Kong

SF Express

Service type codes: sf_hk (SF Express), RETURN_SF_EXPRESS_XB_HKG (SF Express Macao-HK)

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 30 chars
shipFrom.street1	Yes	Truncated to 39 chars; street1 + street2 truncated to 39 chars combined
shipFrom.street2	No	See street1
shipFrom.city	No	Max 100 chars
shipFrom.postalCode	Yes	Max 25 chars
shipFrom.phone	No	Optional leading `+`, then 2–15 digits; the first digit cannot be `0`
shipFrom.email	No	Max 200 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0

Item constraints:

Constraint	Limit
Sum of items[].weight	Must be > 0
items[].value	Max 3 decimal places

DHL Express Worldwide (to Hong Kong)

Service type code: RETURN_SPACESHIP_DHL (DHL- Express Worldwide)

Field	Required	Limit
shipFrom.contactName	Yes	Max 200 chars
shipFrom.street1	Yes	Max 70 chars
shipFrom.street2	No	Max 50 chars; street1 + street2 max 96 chars combined
shipFrom.city	Yes	Max 30 chars
shipFrom.state	No	Max 35 chars
shipFrom.postalCode	Yes	Max 9 chars
shipFrom.phone	Yes	Max 20 chars; must be a valid phone number for `shipFrom.country`
shipFrom.email	No	Max 81 chars, valid email format
shipFrom.fax	No	Max 255 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0, whole centimetres only
Longest side	Max 303 cm
length + width + height	Max 789 cm

Item constraints:

Constraint	Limit
items[].description	Required, max 35 chars
items[].value	Must be >= 0, max 2 decimal places

FedEx International Economy (to Hong Kong)

Service type code: RETURN_SPACESHIP_FEDEX (Fedex- International Economy)

Field	Required	Limit
shipFrom.contactName	Yes	Max 200 chars
shipFrom.street1	Yes	Max 70 chars
shipFrom.street2	No	Max 50 chars; street1 + street2 max 96 chars combined
shipFrom.city	Yes	Max 100 chars
shipFrom.state	No	Max 80 chars
shipFrom.postalCode	Yes	Max 10 chars
shipFrom.phone	Yes	Max 20 chars; must be a valid phone number for `shipFrom.country`
shipFrom.email	No	Max 81 chars, valid email format
shipFrom.fax	No	Max 255 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0, whole centimetres only
Longest side	Max 274 cm
length + width + height	Max 302 cm

Item constraints:

Constraint	Limit
items[].description	Required, max 35 chars
items[].value	Must be >= 0, max 2 decimal places

UPS Worldwide Express Saver (to Hong Kong)

Service type code: RETURN_UPS_SV_HKG (UPS Worldwide Express Saver)

Field	Required	Limit
shipFrom.contactName	Yes	Max 35 chars
shipFrom.street1	Yes	Max 70 chars
shipFrom.street2	No	Max 50 chars; street1 + street2 max 96 chars combined
shipFrom.city	Yes	Max 30 chars
shipFrom.state	No	Max 80 chars
shipFrom.postalCode	Yes	Max 9 chars. When `shipFrom.country` is `twn`: 3 or 5 digits
shipFrom.phone	Yes	Max 20 chars; must be a valid phone number for `shipFrom.country`
shipFrom.email	No	Max 81 chars, valid email format
shipFrom.fax	No	Max 255 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0
parcel.length / width / height	Each must be > 0, whole centimetres only
Longest side	Max 274 cm
length + width + height	Max 302 cm
Length + girth	Max 400 cm (longest side + 2 × the other two sides)

Item constraints:

Constraint	Limit
Sum of items[].weight	Must be > 0
items[].description	Required, max 35 chars
items[].value	Must be >= 0, max 2 decimal places

Japan

Sagawa Express

Service type code: RETURN_SAGAWA_EXPR_JPN

Field	Required	Limit
shipFrom.contactName	Yes	Max 255 chars
shipFrom.street1	Yes	Max 255 chars
shipFrom.street2	No	Max 255 chars
shipFrom.state	No	Max 255 chars; Japanese characters only
shipFrom.city	No	Max 255 chars; Japanese characters only
shipFrom.postalCode	Yes	`NNNNNNN` or `NNN-NNNN`
shipFrom.phone	Yes	Digits only

Parcel constraints:

Constraint	Limit
parcel.weight	Max 30,000 g
length + width + height	Max 160 cm

DHL Express Worldwide (to Japan and Singapore)

Service type codes: RETURN_DHL_WPX_PHY_DROP_JPN (DHL Express Worldwide-JP (Physical Label)-Drop Off), RETURN_DHL_WPX_QR_DROP_JPN (DHL Express Worldwide-JP (QR Code)-Drop Off), RETURN_DHL_WPX_PHY_DROP_SGP (DHL Express Worldwide-SG (Physical Label)-Drop Off), RETURN_DHL_WPX_QR_DROP_SGP (DHL Express Worldwide-SG (QR Code)-Drop Off)

Field	Required	Limit
shipFrom.country	Yes	Valid ISO3 country code
shipFrom.contactName	Yes	Max 255 chars
shipFrom.street1	Yes	Max 45 chars
shipFrom.street2	No	Max 45 chars
shipFrom.street3	No	Max 45 chars
shipFrom.city	Yes	Max 45 chars
shipFrom.state	No	Max 35 chars
shipFrom.postalCode	Yes	Max 12 chars
shipFrom.phone	Yes	Max 70 chars
shipFrom.email	No	Max 70 chars, valid email format

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0

Item constraints:

Constraint	Limit
items[].weight	Must be > 0
items[].value	Must be > 0

Singapore

SingPost

Service type code: RETURN_SGPPOST_EZY2SHIP

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Truncated to 35 chars
shipFrom.street2	No	Truncated to 35 chars
shipFrom.street3	No	Truncated to 35 chars
shipFrom.city	Yes	Max 30 chars
shipFrom.state	Yes	Max 30 chars
shipFrom.postalCode	Yes	Exactly 6 digits
shipFrom.phone	Yes	Max 20 chars
shipFrom.fax	No	Max 255 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0 and under 100,000 g
parcel.length / width / height	Each must be > 0, max 999.99 cm, up to 2 decimal places

Item constraints:

Constraint	Limit
Number of items	Max 20
items[].weight	Must be > 0 and under 100,000 g
Sum of items[].weight	Must be under 100,000 g
items[].value	Must be >= 0, max 9,999,999.99, up to 2 decimal places

J&T Express – Drop-off (Point to Door)

Service type code: RETURN_JNT_PUDO_SG

Field	Required	Limit
shipFrom.city	Yes	—
shipFrom.state	Yes	—
shipFrom.postalCode	Yes	Exactly 6 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0
parcel.length / width / height	Each must be > 0, max 80 cm
length + width + height	Max 240 cm
length × width × height	Max 150,000 cm³

Item constraints:

Constraint	Limit
items[].value	Must be > 0

DHL Express Worldwide (to Singapore)

See DHL Express Worldwide (to Japan and Singapore).

Taiwan

Yamato

Service type code: RETURN_YAMATO_TWN

Field	Required	Limit
shipFrom.contactName	Yes	Max 30 chars. Chinese characters, English letters, digits, spaces and `~!@#$%^&*()_+=-[]{};:'",.?/ only
shipFrom.phone	Yes	`09` followed by 8 digits
shipFrom.city	Yes	city + street1 + street2 + street3 max 120 chars combined
orderTitle	Yes	Max 100 chars

Parcel constraints:

Constraint	Limit
parcel.weight	Must be > 0 and under 20,000 g
length + width + height	Max 150 cm

Item constraints:

Constraint	Limit
items[].description	Max 20 chars

Malaysia

DHL eCommerce

Service type code: RETURN_DHL_ECOMMERC_MYS

Field	Required	Limit
shipFrom.contactName	Yes	Truncated to 35 chars
shipFrom.street1	Yes	Truncated to 100 chars; street1 + street2 truncated to 100 chars combined
shipFrom.street2	No	See street1
shipFrom.city	Yes	Max 35 chars
shipFrom.postalCode	Yes	Max 10 chars
shipFrom.phone	Yes	Max 16 chars. Malaysian number with optional `+60`, digits separated by `-` or a space, e.g. `+60 12-345 6789`

Item constraints:

Constraint	Limit
Sum of items[].weight	Max 30,000 g
items[].value	Must not be 0

United Arab Emirates

EMX

Service type code: RETURN_EMX_ARE

Field	Required	Limit
shipFrom.country	Yes	Valid ISO3 country code
shipFrom.contactName	Yes	Max 48 chars
shipFrom.street1	Yes	Max 100 chars
shipFrom.street2	No	Max 100 chars
shipFrom.street3	No	Max 100 chars; street1 + street2 + street3 max 100 chars combined
shipFrom.city	Yes	Max 100 chars
shipFrom.state	Yes	Max 255 chars
shipFrom.postalCode	Yes	Max 64 chars
shipFrom.phone	Yes	Max 25 chars
shipFrom.email	No	Max 50 chars

Parcel constraints:

Constraint	Limit
parcel.length / width / height	Each must be > 0

Item constraints:

Constraint	Limit
items[].weight	Must be > 0, up to 3 decimal places
items[].description	Max 128 chars
items[].value	Must be > 0, up to 2 decimal places

​United Kingdom

​Royal Mail Tracked Returns 48

​DPD

​InPost – Locker & Shop Drop-off

​Germany

​DHL

​DHL Retoure

​France

​Mondial Relay

​United States

​FedEx Ground

​USPS

​Canada

​Canada Post

​Australia

​AU Post

​Hong Kong

​SF Express

​DHL Express Worldwide (to Hong Kong)

​FedEx International Economy (to Hong Kong)

​UPS Worldwide Express Saver (to Hong Kong)

​Japan

​Sagawa Express

​DHL Express Worldwide (to Japan and Singapore)

​Singapore

​SingPost

​J&T Express – Drop-off (Point to Door)

​DHL Express Worldwide (to Singapore)

​Taiwan

​Yamato

​Malaysia

​DHL eCommerce

​United Arab Emirates

​EMX

United Kingdom

Royal Mail Tracked Returns 48

DPD

InPost – Locker & Shop Drop-off

Germany

DHL

DHL Retoure

France

Mondial Relay

United States

FedEx Ground

USPS

Canada

Canada Post

Australia

AU Post

Hong Kong

SF Express

DHL Express Worldwide (to Hong Kong)

FedEx International Economy (to Hong Kong)

UPS Worldwide Express Saver (to Hong Kong)

Japan

Sagawa Express

DHL Express Worldwide (to Japan and Singapore)

Singapore

SingPost

J&T Express – Drop-off (Point to Door)

DHL Express Worldwide (to Singapore)

Taiwan

Yamato

Malaysia

DHL eCommerce

United Arab Emirates

EMX