Parcels

Parcel is a new offering from Deliverr that allows merchants to affordably deliver across the US hassle-free.

Parcel is currently only available to select merchants.

Create a parcel

Create a parcel and purchase a label for that parcel.

Error Handling and Troubleshooting

  1. SELLER_NOT_FOUND - Seller is not registered or their registration process has not been completed.

  2. INVALID_INJECTION_LOCATION - Injection location is not valid or is not serviceable for the seller.

  3. EXCEEDS_MAX_DIMENSIONS - Dimensions of the parcel being processed exceed the maximum allowable limits set by the shipping carrier.

  4. INVALID_DESTINATION_ADDRESS - Destination address provided for the parcel is incorrect, incomplete or cannot be validated by the system.

  5. CUSTOMS_INFORMATION_REQUIRED - The essential customs details, which are required for international shipping, have not been provided or are incomplete.

  6. FAILED_TO_DETERMINE_ZONE - Unable to identify or determine the appropriate shipping zone for the parcel based on the provided destination address.

  7. SERVICE_LEVEL_UNSUPPORTED_FOR_DESTINATION - The level of service selected (e.g. Standard, Expedited, International) is not supported for the provided destination address.

  8. SERVICE_LEVEL_NOT_CONFIGURED - The service level selected is not configured for the seller.

  9. RETURNS_UNSUPPORTED - Returns are not supported for parcels associated with the seller.

SecurityBEARER
Request
Request Body schema: application/json
required
customerParcelId
string

An identifier meaningful to the seller.

serviceLevel
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

injectionLocation
string

The origin Flexport sortation center.

required
object (DeliverrAddress)

The delivery address for the parcel.

name
required
string
company
string
street1
required
string
street2
string
city
required
string
zip
required
string
state
required
string
country
required
string
phone
string
email
string
isResidential
boolean
object (DeliverrAddress)

The return address for the parcel.

name
required
string
company
string
street1
required
string
street2
string
city
required
string
zip
required
string
state
required
string
country
required
string
phone
string
email
string
isResidential
boolean
skipAddressValidation
boolean

If true, the correctness of the address will not be verified.

pickupDateTime
string <date-time>

The date the parcel will be picked up for injection into a Flexport sortation center.

required
object (ParcelDimensions)

The dimensions and weight of the parcel.

height
required
number <double>
length
required
number <double>
lengthUnit
required
string (LengthUnit)
Enum: "in" "cm" "mm" "m"
weight
required
number <double>
weightUnit
required
string (WeightUnit)
Enum: "oz" "kg" "lb" "g"
width
required
number <double>
customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

ShippingLabelFormat (string) or ShippingLabelFormatParcel (string) (ShippingLabelFormatParcel)

The format of the shipping label. (e.g. PDF, PNG, or ZPL)

Any of:

The format of the shipping label. (e.g. PDF, PNG, or ZPL)

string (ShippingLabelFormat)
Enum: "PNG" "ZPL203"
isReturn
boolean

If true, the parcel delivers to the return address.

marketplace
string

The marketplace integration for the parcel. (e.g. AMAZON, EBAY, WALMART)

object (CustomLabelFooterFields)

Additional information to be included on the shipping label.

customLabelFooter1
required
string [ 1 .. 25 ] characters

A custom field that can be used to define a string to be placed in the footer of the shipping label.

customLabelFooter2
string [ 1 .. 25 ] characters

A custom field that can be used to define a string to be placed in the footer of the shipping label.

object (ParcelCustomsInformation)

Customs information is required for each item in a parcel with an International delivery address.

required
Array of objects (ParcelCustomsInformationItems)
Array
code
required
string

The product SKU for the item.

description
required
string

A description of the item.

quantity
required
number <double>

The quantity of the item.

weight
required
number <double>

The weight of the item.

weightUnit
required
string (WeightUnit)

The unit of weight for the item.

Enum: "oz" "kg" "lb" "g"
value
required
number <double>

The value of the item in USD.

hsTariffCode
required
string

The HS tariff code for the item.

originCountry
required
string (CountryCode)

The origin country of the item.

Enum: "AF" "AX" "AL" "DZ" "AS" "AD" "AO" "AI" "AQ" "AG" "AR" "AM" "AW" "AU" "AT" "AZ" "BS" "BH" "BD" "BB" "BY" "BE" "BZ" "BJ" "BM" "BT" "BO" "BQ" "BA" "BW" "BV" "BR" "IO" "BN" "BG" "BF" "BI" "CV" "KH" "CM" "CA" "KY" "CF" "TD" "CL" "CN" "CX" "CC" "CO" "KM" "CG" "CD" "CK" "CR" "CI" "HR" "CU" "CW" "CY" "CZ" "DK" "DJ" "DM" "DO" "EC" "EG" "SV" "GQ" "ER" "EE" "SZ" "ET" "FK" "FO" "FJ" "FI" "FR" "GF" "PF" "TF" "GA" "GM" "GE" "DE" "GH" "GI" "GR" "GL" "GD" "GP" "GU" "GT" "GG" "GN" "GW" "GY" "HT" "HM" "VA" "HN" "HK" "HU" "IS" "IN" "ID" "IR" "IQ" "IE" "IM" "IL" "IT" "JM" "JP" "JE" "JO" "KZ" "KE" "KI" "KP" "KR" "KW" "KG" "LA" "LV" "LB" "LS" "LR" "LY" "LI" "LT" "LU" "MO" "MG" "MW" "MY" "MV" "ML" "MT" "MH" "MQ" "MR" "MU" "YT" "MX" "FM" "MD" "MC" "MN" "ME" "MS" "MA" "MZ" "MM" "NA" "NR" "NP" "NL" "NC" "NZ" "NI" "NE" "NG" "NU" "NF" "MK" "MP" "NO" "OM" "PK" "PW" "PS" "PA" "PG" "PY" "PE" "PH" "PN" "PL" "PT" "PR" "QA" "RE" "RO" "RU" "RW" "BL" "SH" "KN" "LC" "MF" "PM" "VC" "WS" "SM" "ST" "SA" "SN" "RS" "SC" "SL" "SG" "SX" "SK" "SI" "SB" "SO" "ZA" "GS" "SS" "ES" "LK" "SD" "SR" "SJ" "SE" "CH" "SY" "TW" "TJ" "TZ" "TH" "TL" "TG" "TK" "TO" "TT" "TN" "TR" "TM" "TC" "TV" "UG" "UA" "AE" "GB" "US" "UM" "UY" "UZ" "VU" "VE" "VN" "VG" "VI" "WF" "EH" "YE" "ZM" "ZW"
packslipNotes
string

The packslip notes to be included with a label. Packslip notes will be printed on a separate sheet.

Responses
201

Parcel created

400

Bad Request

401

Unauthorized

post/logistics/api/2024-07/parcels
Request samples
application/json
{
  • "customerParcelId": "string",
  • "serviceLevel": "string",
  • "injectionLocation": "string",
  • "shipToAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "returnAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "skipAddressValidation": true,
  • "pickupDateTime": "2019-08-24T14:15:22Z",
  • "dimensions": {
    • "height": 5,
    • "length": 2,
    • "lengthUnit": "in",
    • "weight": 1,
    • "weightUnit": "oz",
    • "width": 8
    },
  • "customerCustomField": "string",
  • "labelFormat": "PNG",
  • "isReturn": true,
  • "marketplace": "string",
  • "customLabelFooterFields": {
    • "customLabelFooter1": "string",
    • "customLabelFooter2": "string"
    },
  • "customsInformation": {
    • "customsItems": [
      • {
        }
      ]
    },
  • "packslipNotes": "string"
}
Response samples
application/json
{
  • "status": "OK",
  • "parcelId": "string",
  • "price": 0,
  • "serviceLevel": "string",
  • "trackingCode": "string",
  • "carrierCode": "string",
  • "packageTrackingUrl": "string",
  • "shippingLabelUrl": "string",
  • "customerReferenceId": "string",
  • "customerCustomField": "string",
  • "flexportTrackingUrl": "string",
  • "carrierBarcode": "string"
}

Cancel a parcel

Cancels a parcel that was previously created.

Error Handling and Troubleshooting

  1. PARCEL_NOT_FOUND - The parcelId provided in the API request is incorrect.

  2. LABEL_ALREADY_CANCELLED - The parcel is already cancelled.

SecurityBEARER
Request
Request Body schema: application/json
required
parcelId
required
string

The Flexport parcel ID to cancel.

Responses
200

Successfully cancelled parcel

400

Bad Request

401

Unauthorized

post/logistics/api/2024-07/parcels/cancel
Request samples
application/json
{
  • "parcelId": "string"
}
Response samples
application/json
{
  • "status": 400,
  • "type": "string",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Get a parcel by ID

Fetch the parcel with a specified Parcel ID.

Error Handling and Troubleshooting

  1. PARCEL_NOT_FOUND - The parcelId provided in the API request is incorrect.
SecurityBEARER
Request
path Parameters
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

Responses
200

Fetched Parcel

Response Schema: application/json
Any of:
status
required
string (ParcelApiStatus)

The status of the parcel. (e.g. OK, ERROR)

Enum: "OK" "ERROR"
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

price
required
number <double>

The price of the parcel.

serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

trackingCode
required
string

The tracking code for the package.

carrierCode
required
string

The carrier code for the package.

packageTrackingUrl
required
string

URL that can be used to track the package.

shippingLabelUrl
required
string

URL used to download the shipping label data.

customerReferenceId
required
string

An identifier meaningful to the seller.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

flexportTrackingUrl
string

URL that can be used to track a package end-to-end through Flexport and final-mile partner networks.

carrierBarcode
string

Carrier barcode is the exact barcode which is on the physical label that is scanned.

401

Unauthorized

404

Parcel not found

get/logistics/api/2024-07/parcels/{parcelId}
Response samples
application/json
{
  • "status": "OK",
  • "parcelId": "string",
  • "price": 0,
  • "serviceLevel": "string",
  • "trackingCode": "string",
  • "carrierCode": "string",
  • "packageTrackingUrl": "string",
  • "shippingLabelUrl": "string",
  • "customerReferenceId": "string",
  • "customerCustomField": "string",
  • "flexportTrackingUrl": "string",
  • "carrierBarcode": "string"
}

Get a parcel's tracking information by Parcel ID

Fetch the tracking information for the parcel with the specified Parcel ID.

Error Handling and Troubleshooting

  1. PARCEL_NOT_FOUND - The parcelId provided in the API request is incorrect.

  2. PARCEL_TRACKING_NOT_FOUND - Failed to find tracking details for parcel.

SecurityBEARER
Request
path Parameters
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

Responses
200

Contains the tracking information for the parcel

Response Schema: application/json
Any of:
parcelId
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

customerReferenceId
string

An identifier meaningful to the seller.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

status
required
string (ParcelApiStatus)

The status of the parcel. (e.g. OK, ERROR)

Enum: "OK" "ERROR"
errors
string

An error code if the status is ERROR.

errorMessage
string

An error message if the status is ERROR.

packageTrackingUrl
string

URL that can be used to track the package.

shippingLabelUrl
string

URL used to download the shipping label data.

trackingCode
string

The tracking code for the package.

carrierCode
string

The carrier code for the package.

carrierBarcode
string

Carrier barcode is the exact barcode which is on the physical label that is scanned. In some cases it's prefix+trackingCode so sending it as a separate field

required
object (TrackingResultTimestamps)

The tracking event timestamps.

labelTime
required
string or null <date-time>

UTC timestamp of when a label was printed for the package.

arrivalScanTime
required
string or null <date-time>

UTC timestamp of the arrival scan.

sortationArrivalTime
string or null <date-time>

This is the time at which the parcel is scanned at the sortation center.

facilityTime
required
string or null <date-time>

UTC timestamp of when the package arrived at the facility.

attemptedDeliveryTime
required
string or null <date-time>

UTC timestamp of when delivery was attempted for the package.

deliveryTime
required
string or null <date-time>

UTC timestamp of when the package was delivered.

estimatedDeliveryTime
required
string or null <date-time>

UTC timestamp of when the package is expected to be delivered.

promisedDeliveryTime
string or null <date-time>

UTC timestamp of when the package is promised to be delivered.

lastTrackingEventTime
required
string or null <date-time>

UTC timestamp of the last tracking event for the package.

lastTrackingIngestionTime
required
string or null <date-time>

UTC timestamp of when the last tracking event for the package was ingested.

Array of objects (ExpiredTrackingData)

Canceled tracking data for repurchased parcels.

Array
labelId
string

Unique ID for the label.

trackingCode
string

The tracking code for the package.

shippingLabelUrl
string

URL used to download the label data.

packageTrackingUrl
string

URL that can be used to track the package through a final-mile partner network.

shippingMethod
string (ShippingMethod)

The shipping method used to ship the package.

flexportTrackingUrl
string (URL)

URL that can be used to track a package end-to-end through Flexport and final-mile partner networks.

400

Bad Request

401

Unauthorized

get/logistics/api/2024-07/parcels/{parcelId}/tracking
Response samples
application/json
{
  • "parcelId": "string",
  • "customerReferenceId": "string",
  • "customerCustomField": "string",
  • "status": "OK",
  • "errors": "string",
  • "errorMessage": "string",
  • "packageTrackingUrl": "string",
  • "shippingLabelUrl": "string",
  • "trackingCode": "string",
  • "carrierCode": "string",
  • "carrierBarcode": "string",
  • "eventTimestamps": {
    • "labelTime": "2019-08-24T14:15:22Z",
    • "arrivalScanTime": "2019-08-24T14:15:22Z",
    • "sortationArrivalTime": "2019-08-24T14:15:22Z",
    • "facilityTime": "2019-08-24T14:15:22Z",
    • "attemptedDeliveryTime": "2019-08-24T14:15:22Z",
    • "deliveryTime": "2019-08-24T14:15:22Z",
    • "estimatedDeliveryTime": "2019-08-24T14:15:22Z",
    • "promisedDeliveryTime": "2019-08-24T14:15:22Z",
    • "lastTrackingEventTime": "2019-08-24T14:15:22Z",
    • "lastTrackingIngestionTime": "2019-08-24T14:15:22Z"
    },
  • "expiredTrackingData": [
    • {
      • "labelId": "string",
      • "trackingCode": "string",
      • "shippingLabelUrl": "string",
      • "packageTrackingUrl": "string",
      • "shippingMethod": "string"
      }
    ],
  • "flexportTrackingUrl": "string"
}

Get a parcel's tracking information by tracking code

Fetch the tracking information for the parcel with a specified tracking code. Only valid for Parcel users.

Error Handling and Troubleshooting

  1. PARCEL_NOT_FOUND - The parcelId provided in the API request is incorrect.

  2. PARCEL_TRACKING_NOT_FOUND - Failed to find tracking details for parcel.

SecurityBEARER
Request
path Parameters
trackingCode
required
string

tracking code used to track the parcel

Responses
200

Contains the tracking information for the parcel

Response Schema: application/json
Any of:
parcelId
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

customerReferenceId
string

An identifier meaningful to the seller.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

status
required
string (ParcelApiStatus)

The status of the parcel. (e.g. OK, ERROR)

Enum: "OK" "ERROR"
errors
string

An error code if the status is ERROR.

errorMessage
string

An error message if the status is ERROR.

packageTrackingUrl
string

URL that can be used to track the package.

shippingLabelUrl
string

URL used to download the shipping label data.

trackingCode
string

The tracking code for the package.

carrierCode
string

The carrier code for the package.

carrierBarcode
string

Carrier barcode is the exact barcode which is on the physical label that is scanned. In some cases it's prefix+trackingCode so sending it as a separate field

required
object (TrackingResultTimestamps)

The tracking event timestamps.

labelTime
required
string or null <date-time>

UTC timestamp of when a label was printed for the package.

arrivalScanTime
required
string or null <date-time>

UTC timestamp of the arrival scan.

sortationArrivalTime
string or null <date-time>

This is the time at which the parcel is scanned at the sortation center.

facilityTime
required
string or null <date-time>

UTC timestamp of when the package arrived at the facility.

attemptedDeliveryTime
required
string or null <date-time>

UTC timestamp of when delivery was attempted for the package.

deliveryTime
required
string or null <date-time>

UTC timestamp of when the package was delivered.

estimatedDeliveryTime
required
string or null <date-time>

UTC timestamp of when the package is expected to be delivered.

promisedDeliveryTime
string or null <date-time>

UTC timestamp of when the package is promised to be delivered.

lastTrackingEventTime
required
string or null <date-time>

UTC timestamp of the last tracking event for the package.

lastTrackingIngestionTime
required
string or null <date-time>

UTC timestamp of when the last tracking event for the package was ingested.

Array of objects (ExpiredTrackingData)

Canceled tracking data for repurchased parcels.

Array
labelId
string

Unique ID for the label.

trackingCode
string

The tracking code for the package.

shippingLabelUrl
string

URL used to download the label data.

packageTrackingUrl
string

URL that can be used to track the package through a final-mile partner network.

shippingMethod
string (ShippingMethod)

The shipping method used to ship the package.

flexportTrackingUrl
string (URL)

URL that can be used to track a package end-to-end through Flexport and final-mile partner networks.

400

Bad Request

401

Unauthorized

get/logistics/api/2024-07/parcels/tracking/{trackingCode}
Response samples
application/json
{
  • "parcelId": "string",
  • "customerReferenceId": "string",
  • "customerCustomField": "string",
  • "status": "OK",
  • "errors": "string",
  • "errorMessage": "string",
  • "packageTrackingUrl": "string",
  • "shippingLabelUrl": "string",
  • "trackingCode": "string",
  • "carrierCode": "string",
  • "carrierBarcode": "string",
  • "eventTimestamps": {
    • "labelTime": "2019-08-24T14:15:22Z",
    • "arrivalScanTime": "2019-08-24T14:15:22Z",
    • "sortationArrivalTime": "2019-08-24T14:15:22Z",
    • "facilityTime": "2019-08-24T14:15:22Z",
    • "attemptedDeliveryTime": "2019-08-24T14:15:22Z",
    • "deliveryTime": "2019-08-24T14:15:22Z",
    • "estimatedDeliveryTime": "2019-08-24T14:15:22Z",
    • "promisedDeliveryTime": "2019-08-24T14:15:22Z",
    • "lastTrackingEventTime": "2019-08-24T14:15:22Z",
    • "lastTrackingIngestionTime": "2019-08-24T14:15:22Z"
    },
  • "expiredTrackingData": [
    • {
      • "labelId": "string",
      • "trackingCode": "string",
      • "shippingLabelUrl": "string",
      • "packageTrackingUrl": "string",
      • "shippingMethod": "string"
      }
    ],
  • "flexportTrackingUrl": "string"
}

Get the tracking URL for a parcel

Fetch the tracking URL for a parcel given a Parcel ID.

Error Handling and Troubleshooting

  1. PARCEL_NOT_FOUND - The parcelId provided in the API request is incorrect.
SecurityBEARER
Request
path Parameters
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

Responses
200

Contains the tracking URL for the parcel

Response Schema: application/json
string
400

Bad Request

401

Unauthorized

get/logistics/api/2024-07/parcels/{parcelId}/tracking_url
Response samples
application/json
"string"

Get a parcel quote

Fetch a quote for a label purchase without purchasing a label.

Error Handling and Troubleshooting

  1. INVALID_SELLER - The seller information appears to be incomplete or there are discrepancies with the seller's status.

  2. INVALID_INJECTION_LOCATION - Injection location is not valid or is not serviceable for the seller.

  3. EXCEEDS_MAX_DIMENSIONS - Dimensions of the parcel being processed exceed the maximum allowable limits set by the shipping carrier.

  4. FAILED_TO_DETERMINE_ZONE - Unable to identify or determine the appropriate shipping zone for the parcel based on the provided destination address.

  5. INVALID_DESTINATION_ADDRESS - Destination address provided for the parcel is incorrect, incomplete or cannot be validated by the system.

  6. SERVICE_LEVEL_NOT_CONFIGURED - The service level selected is not configured for the seller.

SecurityBEARER
Request
Request Body schema: application/json
required
serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

injectionLocation
string

The origin Flexport sortation center.

required
object (DeliverrAddress)

The delivery address for the parcel.

name
required
string
company
string
street1
required
string
street2
string
city
required
string
zip
required
string
state
required
string
country
required
string
phone
string
email
string
isResidential
boolean
required
object (ParcelDimensions)

The dimensions and weight of the parcel.

height
required
number <double>
length
required
number <double>
lengthUnit
required
string (LengthUnit)
Enum: "in" "cm" "mm" "m"
weight
required
number <double>
weightUnit
required
string (WeightUnit)
Enum: "oz" "kg" "lb" "g"
width
required
number <double>
Responses
200

Successfully fetched quote

Response Schema: application/json
Any of:
price
required
number <double>

The price of the parcel delivery.

serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

billedWeightLbs
required
number <double>

The billed weight in pounds (based on the dimensions and weight of the parcel).

required
object (ParcelDimensions)

The dimensions and weight of the parcel.

height
required
number <double>
length
required
number <double>
lengthUnit
required
string (LengthUnit)
Enum: "in" "cm" "mm" "m"
weight
required
number <double>
weightUnit
required
string (WeightUnit)
Enum: "oz" "kg" "lb" "g"
width
required
number <double>
warnings
required
Array of strings

Warnings (e.g. Unable to verify if address is valid)

400

Bad Request

401

Unauthorized

post/logistics/api/2024-07/parcels/quote
Request samples
application/json
{
  • "serviceLevel": "string",
  • "injectionLocation": "string",
  • "shipToAddress": {
    • "name": "string",
    • "company": "string",
    • "street1": "string",
    • "street2": "string",
    • "city": "string",
    • "zip": "string",
    • "state": "string",
    • "country": "string",
    • "phone": "string",
    • "email": "string",
    • "isResidential": true
    },
  • "dimensions": {
    • "height": 5,
    • "length": 2,
    • "lengthUnit": "in",
    • "weight": 1,
    • "weightUnit": "oz",
    • "width": 8
    }
}
Response samples
application/json
{
  • "price": 0,
  • "serviceLevel": "string",
  • "billedWeightLbs": 0,
  • "dimensions": {
    • "height": 5,
    • "length": 2,
    • "lengthUnit": "in",
    • "weight": 1,
    • "weightUnit": "oz",
    • "width": 8
    },
  • "warnings": [
    • "string"
    ]
}

Get a Bulk Parcel Job by ID

Fetch the Bulk Parcel Job for the specified ID.

Possible statuses and their meaning

  1. CREATING: This bulk job is currently being processed.
  2. COMPLETED: This bulk job has been successfully completed.
  3. PARTIALLY_COMPLETED: Some parcels in this bulk job have failed.
  4. FAILED: This bulk job has failed.

Error Handling and Troubleshooting

  1. BULK_PARCEL_JOB_ID_NOT_FOUND - The bulk_parcel_job_ID provided in the API request is incorrect.
SecurityBEARER
Request
path Parameters
id
required
number <double>

The Bulk Parcel Job ID

Responses
200

Contains the Bulk Parcel Job for the specified ID

Response Schema: application/json
jobId
required
number <double>

Id associated with bulk parcel job

status
required
string

Status of the bulk parcel job (e.g. CREATING, COMPLETED, PARTIALLY_COMPLETED, FAILED)

labelsUrl
string

The URL incorporating the specified labels generated

Array of objects (BulkParcelJobParcel)

Compilation of parcels generated via the bulk job

Array
status
required
string (ParcelApiStatus)

The status of the parcel. (e.g. OK, ERROR)

Enum: "OK" "ERROR"
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

price
required
number <double>

The price of the parcel.

serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

trackingCode
required
string

The tracking code for the package.

carrierCode
required
string

The carrier code for the parcel

packageTrackingUrl
required
string

URL that can be used to track the package.

shippingLabelUrl
required
string

URL used to download the shipping label data.

customerReferenceId
required
string

An identifier meaningful to the seller.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

flexportTrackingUrl
string

URL that can be used to track a package end-to-end through Flexport and final-mile partner networks.

carrierBarcode
string

Carrier barcode is the exact barcode which is on the physical label that is scanned.

integrationChannelParcelId
required
string

The parcel ID linked to the integration channel (e.g., ShipStation)

trackingNumber
required
string

The tracking number associated with the parcel

shipDate
required
string <date-time>

The shipping date of the parcel

parcelStatus
required
string

The current status of the parcel

errorMessages
required
string

An error message if the status is ERROR.

400

Bad Request

401

Unauthorized

get/logistics/api/2024-07/parcels/jobs/{id}
Response samples
application/json
{
  • "jobId": 0,
  • "status": "string",
  • "labelsUrl": "string",
  • "parcels": [
    • {
      • "status": "OK",
      • "parcelId": "string",
      • "price": 0,
      • "serviceLevel": "string",
      • "trackingCode": "string",
      • "carrierCode": "string",
      • "packageTrackingUrl": "string",
      • "shippingLabelUrl": "string",
      • "customerReferenceId": "string",
      • "customerCustomField": "string",
      • "flexportTrackingUrl": "string",
      • "carrierBarcode": "string",
      • "integrationChannelParcelId": "string",
      • "trackingNumber": "string",
      • "shipDate": "2019-08-24T14:15:22Z",
      • "parcelStatus": "string",
      • "errorMessages": "string"
      }
    ]
}

Create a bulk parcel job

Create a Bulk Parcel Job.

Error Handling and Troubleshooting

  1. INVALID_SELLER - The seller information appears to be incomplete or there are discrepancies with the seller's status.
SecurityBEARER
Request
Request Body schema: application/json
required

The bulk parcel job request

required
Array of objects (BulkParcelRequest)
Array
customerParcelId
string

An identifier meaningful to the seller.

serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

injectionLocation
string

The origin Flexport sortation center.

required
object (DeliverrAddress)

The delivery address for the parcel.

object (DeliverrAddress)

The return address for the parcel.

skipAddressValidation
boolean

If true, the correctness of the address will not be verified.

pickupDateTime
string <date-time>

The date the parcel will be picked up for injection into a Flexport sortation center.

required
object (ParcelDimensions)

The dimensions and weight of the parcel.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

ShippingLabelFormat (string) or ShippingLabelFormatParcel (string) (ShippingLabelFormatParcel)

The format of the shipping label. (e.g. PDF, PNG, or ZPL)

isReturn
boolean

If true, the parcel delivers to the return address.

marketplace
string

The marketplace integration for the parcel. (e.g. AMAZON, EBAY, WALMART)

object (CustomLabelFooterFields)

Additional information to be included on the shipping label.

object (ParcelCustomsInformation)

Customs information is required for each item in a parcel with an International delivery address.

packslipNotes
string

The packslip notes to be included with a label. Packslip notes will be printed on a separate sheet.

integrationChannel
string

The integration channel generating the request. (e.g. shipstation)

packslipRequired
required
boolean

If true, packslip notes should be included in the parcel request.

Responses
200

Successfully created bulk parcel job

Response Schema: application/json
jobId
required
number <double>

Id associated with bulk parcel job

status
required
string

Status of the bulk parcel job (e.g. CREATING, COMPLETED, PARTIALLY_COMPLETED, FAILED)

labelsUrl
string

The URL incorporating the specified labels generated

Array of objects (BulkParcelJobParcel)

Compilation of parcels generated via the bulk job

Array
status
required
string (ParcelApiStatus)

The status of the parcel. (e.g. OK, ERROR)

Enum: "OK" "ERROR"
parcelId
required
string

Unique ID used to track the parcel, returned after acquiring a purchase label.

price
required
number <double>

The price of the parcel.

serviceLevel
required
string

The level of service selected for parcel delivery. (e.g. Standard, Expedited, International)

trackingCode
required
string

The tracking code for the package.

carrierCode
required
string

The carrier code for the parcel

packageTrackingUrl
required
string

URL that can be used to track the package.

shippingLabelUrl
required
string

URL used to download the shipping label data.

customerReferenceId
required
string

An identifier meaningful to the seller.

customerCustomField
string

An optional field that has additional information about the parcel provided by the caller.

flexportTrackingUrl
string

URL that can be used to track a package end-to-end through Flexport and final-mile partner networks.

carrierBarcode
string

Carrier barcode is the exact barcode which is on the physical label that is scanned.

integrationChannelParcelId
required
string

The parcel ID linked to the integration channel (e.g., ShipStation)

trackingNumber
required
string

The tracking number associated with the parcel

shipDate
required
string <date-time>

The shipping date of the parcel

parcelStatus
required
string

The current status of the parcel

errorMessages
required
string

An error message if the status is ERROR.

400

Bad Request

401

Unauthorized

post/logistics/api/2024-07/parcels/jobs
Request samples
application/json
{
  • "parcels": [
    • {
      • "customerParcelId": "string",
      • "serviceLevel": "string",
      • "injectionLocation": "string",
      • "shipToAddress": {
        },
      • "returnAddress": {
        },
      • "skipAddressValidation": true,
      • "pickupDateTime": "2019-08-24T14:15:22Z",
      • "dimensions": {
        },
      • "customerCustomField": "string",
      • "labelFormat": "PNG",
      • "isReturn": true,
      • "marketplace": "string",
      • "customLabelFooterFields": {
        },
      • "customsInformation": {
        },
      • "packslipNotes": "string",
      • "integrationChannel": "string"
      }
    ],
  • "packslipRequired": true
}
Response samples
application/json
{
  • "jobId": 0,
  • "status": "string",
  • "labelsUrl": "string",
  • "parcels": [
    • {
      • "status": "OK",
      • "parcelId": "string",
      • "price": 0,
      • "serviceLevel": "string",
      • "trackingCode": "string",
      • "carrierCode": "string",
      • "packageTrackingUrl": "string",
      • "shippingLabelUrl": "string",
      • "customerReferenceId": "string",
      • "customerCustomField": "string",
      • "flexportTrackingUrl": "string",
      • "carrierBarcode": "string",
      • "integrationChannelParcelId": "string",
      • "trackingNumber": "string",
      • "shipDate": "2019-08-24T14:15:22Z",
      • "parcelStatus": "string",
      • "errorMessages": "string"
      }
    ]
}