Create a FedEx Shipment

HTTP Request

POST /v1/shipments

Summary

This operation creates a post-paid shipping label using FedEx® as the carrier. Shipments can originate from the U.S. and Canada.

Prerequisites

The merchant must have an existing FedEx account and must register the account with Pitney Bowes. See Onboard a Merchant to Print FedEx Labels.

Considerations

  1. For an overview of available services and operations, see the FedEx reference page.

  2. You must specify a SHIPPER_ID in the shipmentOptions array and set its value to the merchant’s postalReportingNumber. To retrieve a merchant’s postalReportingNumber, use the Merchants API.

  3. You can print a merchant-defined reference field on the shipping label by specifying the PRINT_CUSTOM_MESSAGE_1 shipment option in the shipmentOptions array.

  4. For shipments to Puerto Rico or international destinations:

    • If the importer is the same as the final recipient, the toAddress and soldToAddress must match.

    • If the importer is different from the final recipient, enter the importer address in the toAddress and enter the final recipient’s address in the soldToAddress.

  5. Labels retrieved through URLs are available for 24 hours after label creation.

  6. If your request returns the HTTP 500 Internal Server Error, see these troubleshooting steps.

  7. For errors other than the HTTP 500 Internal Server Error, do not resubmit the request without first checking whether the label was created by invoking the Retry Shipment API.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments

Request Headers

Name


Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

Content-Type

Required. The media type of the request entity. Set this to application/json.

Accept-Language

Language and country code. Default: en-US

X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

X-PB-Shipper-Carrier-AccountId

The unique identifier for the carrier account. To retrieve the identifier, see this FAQ.

Required if the merchant has registered multiple accounts for the same carrier. For more information, see Add Commercial Carrier Accounts.

X-PB-UnifiedErrorStructure

Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name

Data Type

Description

fromAddress

Address Object

Required. The origin address. If you want a different address to appear on the label from the one listed here, see this FAQ. The fromAddress object requires the following fields:

  • addressLines

  • postalCode

  • countryCode

toAddress

Address Object

Required. The destination address. The following fields are required:

  • addressLines

  • postalCode

  • countryCode

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The response specifies the service charges. The array takes one rates object. Set the following:

Field:

Value:

carrier

FEDEX

serviceId

See FedEx Services.

parcelType

See FedEx Parcel Types.

specialServices

See FedEx Special Services.

documents

Array[Documents Object]

Required. Defines the label. The response returns the label as a URL or Base64 string. The array takes one documents object. Set the following:

Field:

Value:

type

SHIPPING_LABEL

size,
fileFormat,
contentType

For valid combinations of values, see FedEx Labels.

shipmentOptions

Array[Object]

Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:

The SHIPPER_ID shipment option is required. Set this to the merchant’s Shipper ID. For all available options, see Shipment Options.

customs

Object

For shipments that use customs forms, this object contains the customs information.

Required for shipments to international destinations and Puerto Rico.

customs.customsInfo

Customs Info Object

Customs clearance information for the commercial invoice.

Required if you use the customs object.

customs.customsItems

Array[Customs Info Object]

Customs clearance information for each commodity. If the shipment has multiple types of items, create separate customsItems objects for each type. The array takes a maximum of 30 objects.

Required if you use the customs object.

carrierPayments

Array[Carrier Payments Object]

If one or more of the shipment costs should be charged to a third-party account, enter the information in this array.

soldToAddress

Address Object

The final recipient of the shipment. Required for shipments from the U.S. to Puerto Rico or international destinations. Otherwise optional.

shipmentId

String

RESPONSE ONLY. The unique identifier for the shipment generated by the system.

parcelTrackingNumber

String

RESPONSE ONLY. The tracking number assigned to the shipment.

Customs Info Object for FedEx

Name

Data Type

Description

certificateNumber

String

The certificate number associated with the commodity.

comments

String

Free-form comments regarding the exported shipment entered by the shipper.

currencyCode

String

Required. The type of currency used for the monetary values in this API request. Use three uppercase letters, per ISO 4217. For example, use USD for US Dollars, CAD for Canadian Dollars, and EUR for Euros.

customsDeclaredValue

BigDecimal

Required. Enter the value to declare in customs for the shipment. Enter the value in the currency specified in the currencyCode field.

EELPFC

String

A number provided by the Automated Export System (AES).

Required if the item is valued at more than $2,500 USD per Schedule B export codes.

freightCharge

BigDecimal

Prints a freight charge on the FedEx Commercial Invoice.

fromCustomsReference

String

Free-form reference information provided by the requestor of the shipment.

handlingCosts

BigDecimal

Prints a handling charge on the FedEx Commercial Invoice.

importerCustomsReference

String

A reference number used by the importer, such as a VAT number, PO number, or insured number.

Required for the following:

  • Shipments to the EU. Enter a VAT or IOSS number. You must also pass the importerCustomsReferenceType field.

  • Shipments to Brazil. Enter the Importer’s Tax Identification Number. Brazil requires the Tax ID for all imports. Items missing the Tax ID are subject to return.

importerCustomsReferenceType

String

Required if you enter a VAT or IOSS number in the importerCustomsReference field. Specify which type of number you entered:

  • VAT_NUMBER

  • IOSS_NUMBER

insuredAmount

BigDecimal

Enter the insurance fee, if applicable. This field prints the insurance fee on the FedEx Commercial Invoice. Enter the fee for the purchased insurance. Do not enter coverage amount.

insuredNumber

String

If the sender wishes to insure the contents, they complete an insurance receipt and affix the insured numbered label to the package. The insured number label is what this field represents.

invoiceNumber

String

The commercial invoice number assigned by the exporter.

licenseNumber

String

The export license number associated with the commodity.

otherCharge

BigDecimal

Prints any additional charges on the Commercial Invoice, other than those entered in the freightCharge, handlingCosts, insuredAmount, or packingCosts fields.

packingCosts

BigDecimal

Prints a packing charge on the FedEx Commercial Invoice.

reasonForExport

String

The reason the commodity is being exported. Valid values are:

  • GIFT

  • COMMERCIAL_SAMPLE

  • MERCHANDISE

  • DOCUMENTS

  • RETURNED_GOODS

  • OTHER

reasonForExportExplanation

String

The reason the commodity is being exported.

sdrValue

BigDecimal

When an international parcel is insured, the insured value must be expressed in Special Drawing Rights values. E.g. $100 USD = 66.87 SDR.

 

Customs Items Object for FedEx

If the shipment has multiple types of items, create separate customsItems objects for each. The array takes a maximum of 30 objects.

Name

Data Type


Description


description

String

Required. A detailed description of the commodity, up to 255 characters. The description will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each. Each description will appear on the form.

hSTariffCode

String

The destination country’s tariff-classification number (HS code) for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and then add digits for more detail. The maximum length for an HS code is 14 characters. The HS code will appear on the customs form. If the shipment has multiple types of items, create a separate customsItems object for each.

originCountryCode

String

Required. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.

quantity

Integer

Required. Enter the total number of items of this type of commodity.

quantityUOM

String

Required. The 1-to-3 character code for the unit of measurement, such as BAG, CTN, or EA.

unitPrice

BigDecimal

Required. The price of one item of this type of commodity.

unitWeight

Object

Required. The weight and unit of measure of one item of the commodity.

unitWeight.weight

Number

The weight of the item. This field is required by the unitWeight object.

unitWeight.unitOfMeasurement

String

The unit of measurement. This field is required by the unitWeight object. This field can take the following values:

  • OZ: Ounces

  • GM: Grams

Carrier Payments Object for FedEx

Name

Data Type

Description

accountNumber

String

The account number of the party responsible for the specified charge. The charge is specified in the typeOfCharge field.

countryCode

String

The country code of the party responsible for the charge.

party

String

The role of the party responsible for the charge. Possible values:

  • BILL_RECEIVER

  • BILL_SENDER

  • BILL_THIRD_PARTY

  • BILL_RECEIVER_CONTRACT

postalCode

String

The postal code of the party responsible for the charge.

typeOfCharge

String

The type of charge for which the party will be billed. Possible values:

  • TRANSPORTATION_CHARGES

  • DUTIES_AND_TAXES

  • ALL_CHARGES

Sample Request

FedEx Domestic Shipment Sample Request
curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-Shipper-Carrier-AccountId: <unique_carrier_account_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Emporium",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false,
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 20
        }
    },
    "rates": [ {
        "carrier": "FEDEX",
        "serviceId": "2DA",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "INS",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "printDialogOption": "NO_PRINT_DIALOG",
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "fileFormat": "PDF"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

Sample Response

FedEx Domestic Shipment Sample Response
{
    "fromAddress": {
        "company": "Emporium",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "carrierRoute": "C010",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false,
        "addressLines": [
            "284 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846-5352",
        "countryCode": "US",
        "carrierRoute": "C007",
        "deliveryPoint": "84"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 20.0
        }
    },
    "rates": [ {
        "carrier": "FEDEX",
        "parcelType": "PKG",
        "inductionPostalCode": "36830",
        "specialServices": [ {
            "fee": 0.0,
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ],
            "specialServiceId": "INS"
        } ],
        "deliveryCommitment": {
            "estimatedDeliveryDateTime": "2020-12-18 16:30:00",
            "guarantee": "FULL"
        },
        "serviceId": "2DA",
        "baseCharge": 24.38,
        "currencyCode": "USD",
        "surcharges": [ {
            "fee": 2.85,
            "name": "DELIVERY_AREA"
        },{
            "fee": 2.04,
            "name": "FUEL"
        } ],
        "totalCarrierCharge": 29.27,
        "totalTaxAmount": 0.0
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../d7efae383834ed19a6b733a3818a4.pdf",
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumber": "79487353815",
    "shipmentId": "FEDEX220012345678182"
}

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.