Create a United Parcel Service (UPS) Shipment

HTTP Request

POST /v1/shipments

Summary

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

Prerequisites

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

Considerations

1. The UPS page provides reference information for using UPS with the ECommerce APIs.

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

4. When shipping to Puerto Rico from the U.S., you must set the following:

   • Set rates.serviceId to a U.S. domestic service.

   • Include the customs object.

   • Set both toAddress.stateProvince and toAddress.countryCode to PR.

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: company name phone addressLines cityTown postalCode countryCode
toAddress	Address Object	Required. The destination address. The toAddress object requires the following fields: company name phone addressLines cityTown 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 UPS serviceId See UPS Services. parcelType See UPS Parcels. specialServices Optional. See UPS 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, see UPS Labels. Note: For shipments with a declared value above $1,000.00, only PDF is available for the fileFormat. For details, see 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.
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. This is required if you use the customs object.
customs.customsItems	Array[Customs Items Object]	Customs clearance information for each commodity. This is required if you use the customs object. The array takes a maximum of 30 objects.
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. If this object is used, the following fields are required: company name phone addressLines cityTown postalCode countryCode
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 by the system.

Customs Info Object for UPS

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	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.
fromCustomsReference	String	Free form reference information provided by the requestor of the shipment. Depending on the carrier this information may or may not be rendered on the customs documents.
importerCustomsReference	String	A reference number used by the importer, such as a VAT number, PO number, or insured number. Pitney Bowes does not print the number on the customs form. Required for shipments to the EU from outside the EU. Enter a VAT or IOSS number. Specify which type of number in the importerCustomsReferenceType field. Required for 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
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.
reasonForExport	String	Required. The reason the commodity is being exported. Valid values are: GIFT COMMERCIAL_SAMPLE MERCHANDISE DOCUMENTS (If using this value, see also this related FAQ) 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 UPS

Name	Data Type	Description
description	String	Required. A detailed description of the commodity, up to 255 characters. Maximum length: 255 characters.
hSTariffCode	String	The destination country’s tariff-classification number for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail. Maximum length: 14 characters.
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 UPS

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 Requests

See the following examples:

• UPS Domestic Shipment

• UPS Shipment to Puerto Rico

• UPS International Shipment

UPS Domestic Shipment Request

The following is a sample request for a UPS domestic shipment:

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": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "545 Market St" ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Jane Wilson",
        "phone": "620-555-0000",
        "email": "jane@example.com",
        "residential": false,
        "addressLines": [ "643 Greenway RD" ],
        "cityTown": "Boone",
        "stateProvince": "NC",
        "postalCode": "28607",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "weight": 38,
            "unitOfMeasurement": "OZ"
        },
        "dimension": {
            "length": 6,
            "width": 4,
            "height": 6,
            "unitOfMeasurement": "IN"
        },
        "currencyCode": "USD"
    },
    "rates": [ {
        "carrier": "UPS",
        "serviceId": "NDA_AM",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "INS",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "100.00"
            } ]
        } ]
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "printDialogOption": "NO_PRINT_DIALOG",
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "fileFormat": "PDF"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

UPS Domestic Shipment Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "545 Market St" ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105-2847",
        "countryCode": "US",
        "deliveryPoint": "45",
        "carrierRoute": "C002"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Jane Wilson",
        "phone": "620-555-0000",
        "email": "jane@example.com",
        "residential": false,
        "addressLines": [ "643 Greenway Rd" ],
        "cityTown": "Boone",
        "stateProvince": "NC",
        "postalCode": "28607-4819",
        "countryCode": "US",
        "deliveryPoint": "99",
        "carrierRoute": "C010"
    },
    "parcel": {
        "weight": {
            "weight": 38,
            "unitOfMeasurement": "OZ"
        },
        "dimension": {
            "length": 6,
            "width": 4,
            "height": 6,
            "unitOfMeasurement": "IN"
        },
        "currencyCode": "USD"
    },
    "rates": [ {
        "carrier": "UPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "INS",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "100.00"
            } ]
        } ],
        "serviceId": "NDA_AM",
        "totalCarrierCharge": 133.23,
        "totalTaxAmount": 0,
        "baseCharge": 134.58,
        "currencyCode": "USD"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../ups/258459135/outbound/label/9dbc524171674d4f9b38a17d011664aa.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "shipmentId": "UPS2200167767266327",
    "parcelTrackingNumber": "<tracking-number>"
}

---

UPS Shipment to Puerto Rico Request

The following is a sample request for a UPS shipment to Puerto Rico:

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": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "545 Market St" ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
        },
    "toAddress": {
        "company": "Museum",
        "name": "Director",
        "phone": "787 000 0000",
        "email": "museum@example.com",
        "residential": false,
        "addressLines": ["Av. de Diego 299"],
        "cityTown": "San Juan",
        "stateProvince": "PR",
        "postalCode": "00909",
        "countryCode": "PR"
    },
    "soldToAddress": {
        "company": "Solutions",
        "name": "Supervisor",
        "phone": "787 000 0000",
        "email": "solutions@example.com",
        "residential": false,
        "addressLines": ["70 Hanlan RD"],
        "cityTown": "San Juan",
        "stateProvince": "PR",
        "postalCode": "00915",
        "countryCode": "PR"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 32.0
        },
        "dimension": {
            "length": 6.0,
            "width": 4.0,
            "height": 6.0,
            "unitOfMeasurement": "IN"
         }
    },
    "rates": [ {
        "carrier": "UPS",
        "serviceId": "NDA",
        "rateTypeId": "COMMERCIAL",
        "parcelType": "PKG"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "originCountryCode": "US",
            "quantity": 1,
            "quantityUOM": "PCS",
            "unitPrice": 10.00,
            "unitWeight": {
                "unitOfMeasurement": "OZ",
                "weight": 16.0
            }
        } ]
    },
    "documents": [ {
        "size": "DOC_8X11",
        "printDialogOption": "NO_PRINT_DIALOG",
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "fileFormat": "PDF"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

UPS Shipment to Puerto Rico Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "545 Market St"
        ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105-2847",
        "countryCode": "US",
        "carrierRoute": "C002",
        "deliveryPoint": "45"
    },
    "toAddress": {
        "company": "Museum",
        "name": "Director",
        "phone": "787 000 0000",
        "email": "museum@example.com",
        "residential": false,
        "addressLines": [
            "Av. de Diego 299"
        ],
        "cityTown": "San Juan",
        "stateProvince": "PR",
        "postalCode": "00909",
        "countryCode": "PR"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 32.0
        },
        "dimension": {
            "length": 6.0,
            "width": 4.0,
            "height": 6.0,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.0
        }
    },
    "rates": [ {
        "carrier": "UPS",
        "parcelType": "PKG",
        "inductionPostalCode": "94105",
        "specialServices": [],
        "serviceId": "NDA",
        "baseCharge": 75.4,
        "currencyCode": "USD",
        "rateTypeId": "COMMERCIAL",
        "surcharges": [ {
            "fee": 3.02,
            "name": "FUEL"
        } ],
        "totalCarrierCharge": 77.64,
        "totalTaxAmount": 0.0
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../ups/258459135/outbound/label/b14f7e241d5448eb1fb7900822150c4.pdf"
        "fileFormat": "PDF",
        "size": "DOC_8X11",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "freightCharge": 0.0,
            "handlingCosts": 0.0,
            "otherCharge": 0.0,
            "packingCosts": 0.0,
            "reasonForExport": "MERCHANDISE"
        },
        "customsItems": [ {
            "description": "Books",
            "originCountryCode": "US",
            "quantity": 1,
            "quantityUOM": "PCS",
            "unitPrice": 10.0,
            "unitWeight": {
                "unitOfMeasurement": "OZ",
                "weight": 16.0
            }
        } ]
    },
    "parcelTrackingNumber": "<tracking-number>",
    "shipmentId": "UPS2200255488613798",
    "soldToAddress": {
        "company": "Solutions",
        "name": "Supervisor",
        "phone": "787 000 0000",
        "email": "solutions@example.com",
        "residential": false,
        "addressLines": [
            "70 Hanlan RD"
        ],
        "cityTown": "San Juan",
        "stateProvince": "PR",
        "postalCode": "00915",
        "countryCode": "PR"
    }
}

---

UPS International Shipment Request

The following is a sample request for a UPS shipment to Germany:

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": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "545 Market St" ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Imports",
        "name": "Manager",
        "phone": "49 89 00000",
        "email": "imports@example.com",
        "residential": "false",
        "addressLines": [ "Prinzregentenstraße 3" ],
        "cityTown": "Munchen",
        "stateProvince": "",
        "postalCode": "80331",
        "countryCode": "DE"
    },
    "soldToAddress": {
        "company": "Museum",
        "name": "Director",
        "phone": "49 89 0000000",
        "email": "museum@example.com",
        "residential": "false",
        "addressLines": [ "Museumsinsel 1" ],
        "cityTown": "Munchen",
        "stateProvince": "",
        "postalCode": "80538",
        "countryCode": "DE"
    },
    "parcel": {
        "weight": {
            "weight": 38,
            "unitOfMeasurement": "OZ"
        },
        "dimension": {
            "length": 31,
            "width": 25,
            "height": 25,
            "unitOfMeasurement": "IN"
        }
    },
    "rates": [ {
        "carrier": "UPS",
        "serviceId": "XPP",
        "parcelType": "PKG",
        "specialServices": []
    } ],
    "documents": [ {
        "size": "DOC_8X11",
        "printDialogOption": "EMBED_PRINT_DIALOG",
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "fileFormat": "PDF"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "reasonForExport": "GIFT"
        },
        "customsItems": [ {
            "description": "Product no 1 - Type A",
            "hSTariffCode": "49011000",
            "originCountryCode": "US",
            "quantity": 1,
            "quantityUOM": "EA",
            "unitPrice": 245.0,
            "unitWeight": {
                "weight": 1.0,
                "unitOfMeasurement": "OZ"
            }
        } ]
    },
    "shipmentOptions": [ {
        "name": "PRINT_CUSTOM_MESSAGE_1",
        "value": "Geschenk"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

UPS International Shipment Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "415-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [ "545 Market St" ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105-2847",
        "countryCode": "US",
        "carrierRoute": "C002",
        "deliveryPoint": "45"
    },
    "toAddress": {
        "company": "Imports",
        "name": "Manager",
        "phone": "49 89 00000",
        "email": "imports@example.com",
        "residential": false,
        "addressLines": [ "Prinzregentenstraße 3" ],
        "cityTown": "Munchen",
        "stateProvince": "",
        "postalCode": "80331",
        "countryCode": "DE"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 38.0
        },
        "dimension": {
            "length": 31.0,
            "width": 25.0,
            "height": 25.0,
            "unitOfMeasurement": "IN"
        }
    },
    "rates": [ {
        "carrier": "UPS",
        "parcelType": "PKG",
        "inductionPostalCode": "94105",
        "specialServices": [],
        "serviceId": "XPP",
        "baseCharge": 1649.06,
        "currencyCode": "USD",
        "surcharges": [ {
            "fee": 147.19,
            "name": "FUEL"
        },{
            "fee": 95.0,
            "name": "LARGE_PACKAGE"
        } ],
        "totalCarrierCharge": 1911.94,
        "totalTaxAmount": 0.0
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../ups/258499135/outbound/label/3fdc7fa973d748c19fa1c697d1a12eda.pdf",
        "fileFormat": "PDF",
        "size": "DOC_8X11",
        "type": "SHIPPING_LABEL"
        }
    ],
    "shipmentOptions": [ {
        "name": "PRINT_CUSTOM_MESSAGE_1",
        "value": "Geschenk"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD",
            "freightCharge": 0.0,
            "handlingCosts": 0.0,
            "otherCharge": 0.0,
            "packingCosts": 0.0,
            "reasonForExport": "GIFT"
        },
        "customsItems": [ {
            "description": "Product no 1 - Type A",
            "hSTariffCode": "49011000",
            "originCountryCode": "US",
            "quantity": 1,
            "quantityUOM": "EA",
            "unitPrice": 245.0,
            "unitWeight": {
                "unitOfMeasurement": "OZ",
                "weight": 1.0
            }
        } ]
    },
    "parcelTrackingNumber": "1Z06XZ245495105936",
    "shipmentId": "UPS2200171201666166",
    "soldToAddress": {
        "company": "Museum",
        "name": "Director",
        "phone": "49 89 0000000",
        "email": "museum@example.com",
        "residential": false,
        "addressLines": [ "Museumsinsel 1" ],
        "cityTown": "Munchen",
        "stateProvince": "",
        "postalCode": "80538",
        "countryCode": "DE"
    }
}

---

Sample UPS Label

---

Sample UPS Control Log

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2023, PB.