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

 
 
 
 

• next
• previous |

© Copyright 2023, PB.