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¶

For an overview of available services and operations, see the FedEx reference page.
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.
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.
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.
Labels retrieved through URLs are available for 24 hours after label creation.
If your request returns the HTTP 500 Internal Server Error, see these troubleshooting steps.
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:

name: The shipment option.
value: The option’s value.

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.