Add a UPS account

Required roles:

AdminAccount Manager

Updated June 20, 20268 min read GlobalExpress ups.com

This guide walks through setting up a UPS account in the Carriyo Dashboard. It covers the required roles, the credentials to collect, and every field UPS expects.

At a glance

Cross-border

International

Returns

Supported

Shipping rates

Live carrier rates

Document upload

Supported

Real-time status

Polling only

Labels

PDF · ZPL

Before you start

A UPS account in good standing, plus its API credentials. The required fields are listed in All UPS settings below.
Decide the account country and the default service and label format this account uses.

Open the carrier accounts page

In the Carriyo Dashboard, open Settings in the left sidebar. Under Carrier Management, choose Carrier Accounts, then click the + add icon to start a new account.

Pick UPS

In the carrier picker, search for UPS and click Select. Carriyo creates a UPS account and opens the credential step.

Enter the basics

The first wizard page collects two fields:

Account name: A label that's meaningful to your team (e.g. UPS your country). Keep it short and unique.
Account country: The country this account ships from. Determines the routes and services available.

Fill in the account name and country.
1Account Name
2Account Country

Enter your UPS account details

Enter the required UPS account details, then click Next. Every field is documented in All UPS settings below, with examples and accepted values.

Fill in the UPS account details.
1Shipper Number
2Client ID
3Client Secret

Configure the account

The new account opens on its detail page. General settings work the same way for every carrier: the Active toggle, default label and service, and currency. See Add a carrier account for the full reference to these shared settings — default label, merchant access, going live, and common mistakes.

Merchant access

On multi-merchant tenants, restrict the account to specific merchants via the Permissions tab, then Save.

All UPS settings

Every field UPS exposes in the carrier account, grouped by section. Carriyo stores secrets encrypted and never shows them after saving.

Authentication

3 fields

Account identifiers and API credentials used to connect to the carrier.

Field	Type	What to enter
Shipper NumberRequired	Text	Your 6-character UPS account number that shipments are billed against. Find it on your UPS invoice or UPS.com account. Example: `3N99N2`
Client IDRequired	Text	OAuth client ID for the UPS API. Generate it for your app in the UPS Developer Portal. Example: `ODFBJq25tqMi4mWyJuQVsZk1irPgordb…`
Client SecretRequired	Secret	OAuth client secret paired with your Client ID. Copy it from your UPS Developer Portal app credentials. Example: `91srXL7mwVhcP9hpgL53ggLaupVFgJTV…` The Client ID and Secret together generate the access token UPS uses to book shipments and print labels.

Account Details

8 fields

Account-level configuration and defaults applied to shipments.

Field	Type	What to enter
Tax IDRequired	Text	Your business tax/VAT identification number used on customs paperwork and billing. Example: `678901`
Service CodeRequired	Select	Select the default UPS service level to book shipments with on this account. Example: UPS SAVER("65") NEXT DAY AIR("01")SECOND DAY AIR("02")GROUND("03")EXPRESS("07")EXPEDITED("08")UPS STANDARD("11")
Packaging CodeOptional	Select	The default packaging type applied to shipments on this account. Example: Customer Supplied Package("02") UPS Letter("01")Customer Supplied Package("02")Tube("03")PAK("04")UPS Express Box("21")UPS 25KG Box("24") Defaults to Customer Supplied Package (02) if left empty.
Shipment Service OptionsOptional	Multi	Select optional delivery features (e.g. Saturday delivery/pickup) to apply by default to shipments on this account. Saturday DeliverySaturday PickupDirectDeliveryOnly
Signature TypeOptional	Select	Require a signature on delivery. Leave blank for no signature requirement. Delivery Confirmation SignatureDelivery Confirmation Adult Signature
Other Shipment Charge TypesOptional	Multi	Extra charges applied to every shipment booked on this account. Example: Select charge types 02 - Duties and Taxes
Documents OnlyOptional	Toggle	—
Enable Consolidated Shipping (UPS World Ease Service)Optional	Toggle	Enable UPS World Ease for consolidated shipping. Turn this on only if you've negotiated World Ease with UPS. Extra World Ease settings appear once it's enabled.

Billing & Payment

8 fields

Configure who pays duties, taxes, and transportation charges for UPS shipments.

Only needed when a party other than the shipper pays duties, taxes, or transportation. UPS requires the payor's account number, country code, and postal code (for US/Canada origins).

Field	Type	What to enter
Duties & Taxes PayorOptional	Select	Choose who is billed for import duties and taxes. Defaults to Shipper. Example: Select duties & taxes payor ShipperRecipientThird Party
Duties & Taxes Payor NumberOptional	Text	UPS account number of the duties & taxes payor. Required when the payor is not the shipper. Example: e.g., 123456
Payor Postal CodeOptional	Text	— Example: e.g., 10001
Payor Country CodeOptional	Text	— Example: e.g., 10001
Transportation Charges PayorOptional	Select	Choose who is billed for freight/transportation charges. Leave blank to bill the shipper. Example: Select recipient or third-party payor RecipientThird Party
Transportation Charges Payor NumberOptional	Text	UPS account number of the transportation charges payor. Required when the payor is not the shipper. Example: e.g., 123456
Transportation Charges Payor Country CodeOptional	Text	— Example: e.g., 10001
Transportation Charges Payor Postal CodeOptional	Text	— Example: e.g., 10001

Commercial Invoice

4 fields

Configure settings for international shipments requiring commercial invoices.

Field	Type	What to enter
Terms of ShipmentOptional	Select	Select the Incoterms that define cost and risk responsibility between buyer and seller on international shipments. Example: Select terms of shipment CFR: Cost and FreightCIF: Cost Insurance and FreightCIP: Carriage and Insurance PaidCPT: Carriage Paid ToDAF: Delivered at FrontierDDP: Delivery Duty Paid Common values: DDP (Delivery Duty Paid), DDU, and CIF. Pick what your contract with the consignee specifies.
Export ReasonOptional	Select	Select why the goods are being exported, as declared on the commercial invoice for customs. Example: Select reason to export SaleGiftSampleReturnRepairIntercompanydata
Invoice RemarksOptional	Text	— Example: Enter invoice remarks
Invoice DeclarationOptional	Text	— Example: Enter invoice declaration

Import Control Settings

2 fields

Configure settings related to ImportControl shipments. When Import Control is enabled, the Import Label Delivery Method becomes mandatory.

Field	Type	What to enter
Import Control IndicatorOptional	Toggle	—
Import Label Delivery MethodRequired	Select	Choose one of: Example: Select import label delivery method ImportControl Print and Mail("01")ImportControl One-Attempt("02")ImportControl Three-Attempt("03")ImportControl Electronic Label("04")ImportControl Print Label("05")

UPS Return Settings

3 fields

Configure how return shipments will be handled and how return labels will be generated.

These apply only to return (reverse) shipments. Set the Return Service Code if you book returns through UPS.

Field	Type	What to enter
Return Service CodeOptional	Select	The return service UPS uses for reverse shipments (print and mail, electronic return label, pack-and-collect, and more). Example: Select return service PRINT AND MAIL("2")RETURN SERVICE ONE ATTEMPT("3")RETURN SERVICE THREE ATTEMPT("5")ELECTRONIC RETURN LABEL("8")PRINT RETURN LABEL("9")EXCHANGE PRINT RETURN LABEL("10")
From Email Address for LabelOptional	Email	The sender email address shown on the return label. Example: `sender@example.com` Leave empty to use the contact email from the dropoff details.
To Email Address for LabelOptional	Email	The email address the return label is sent to. Example: `recipient@example.com` Leave empty to use the contact email from the pickup details.

UPS World Ease Settings

12 fields

Configure World Ease Settings (required for consolidated shipping).

Field	Type	What to enter
Destination CountryRequired	Text	Choose one of: AfghanistanAlbaniaAlgeriaAmerican SamoaAndorraAngola
Destination Postal CodeRequired	Text	—
Master Shipment Charge TypeRequired	Select	Choose one of: Example: Select charge type Cost And Freight("CAF")Freight Collect("COL")Delivered Duty Paid("DDP")Free On Board("FOB")Prepaid("PRE")Free Domicile("SDT")
Port Of Entry NameRequired	Text	—
Port Of Entry Consignee NameRequired	Text	—
Port Of Entry Clearance Port CodeRequired	Text	—
Port Of Entry CountryRequired	Text	Choose one of: AfghanistanAlbaniaAlgeriaAmerican SamoaAndorraAngola
Port Of Entry StateRequired	Text	—
Port Of Entry CityRequired	Text	—
Port Of Entry Postal CodeRequired	Text	—
Port Of Entry Address 1Required	Text	—
Port Of Entry Address 2Optional	Text	—

Shipper Details

10 fields

Enter the shipper's contact and address information if it differs from the pickup (ship-from) address. This information will appear on shipping labels and documentation. If left blank, the pickup details will be used by default.

Field	Type	What to enter
Contact NameRequired	Text	— Example: e.g., John Smith
Contact PhoneRequired	Text	— Example: e.g., +971234456567
Company NameRequired	Text	— Example: e.g., ABC Company Ltd.
CountryRequired	Text	Choose one of: AfghanistanAlbaniaAlgeriaAmerican SamoaAndorraAngola
StateRequired	Text	—
CityRequired	Text	—
AreaOptional	Text	— Example: e.g., Downtown, Business District
Address 1Required	Text	— Example: e.g., 123 Main Street
Address 2Optional	Text	— Example: e.g., Suite 456, Floor 2
Post CodeRequired	Text	— Example: e.g., 12345

Sold To Details

11 fields

Enter the sold to contact and address information if it differs from the dropoff (ship-to) address. This information will appear on shipping labels and documentation. If left blank, the importer or dropoff or details will be used by default.

Field	Type	What to enter
Account NumberOptional	Text	— Example: e.g., 123456
Contact NameRequired	Text	— Example: e.g., John Smith
Contact PhoneRequired	Text	— Example: e.g., +971234456567
Company NameRequired	Text	— Example: e.g., ABC Company Ltd.
CountryRequired	Text	Choose one of: AfghanistanAlbaniaAlgeriaAmerican SamoaAndorraAngola
StateOptional	Text	—
CityRequired	Text	—
AreaOptional	Text	— Example: e.g., Downtown, Business District
Address 1Required	Text	— Example: e.g., 123 Main Street
Address 2Optional	Text	— Example: e.g., Suite 456, Floor 2
Post CodeRequired	Text	— Example: e.g., 12345

UPS Label Configuration

2 fields

Configure how your UPS shipping labels will be generated and formatted for printing.

Field	Type	What to enter
Label FormatOptional	Select	Choose the label file format. GIF is delivered as a PDF; use ZPL/SPL/EPL for thermal printers. Defaults to GIF (PDF). Example: GIF (PDF) GIF (PDF)ZPLSPLEPL
Label HeightOptional	Select	Select the label height (6 or 8 inches) to match your printer and label stock. Example: 6 inches 6 inches8 inches

Reference Mappings

3 fields

Map Carriyo fields to the reference values the carrier expects.

Field	Type	What to enter
Order ReferenceOptional	Select	Choose which Carriyo reference becomes the UPS Shipment ID. Example: Select reference field for UPS Shipment ID Order ReferenceShipment Reference
Customer Context ReferenceOptional	Select	Choose which Carriyo reference is sent as the UPS transaction customer context. Defaults to Order Reference. Example: Order Reference (Default) Order ReferenceShipment Reference
Invoice ReferenceOptional	Select	Choose which Carriyo reference appears on UPS invoices and billing documents. Defaults to Order Reference. Example: Order Reference (Default) Order ReferenceShipment ReferenceAlternate Reference

Document Upload

1 field

Customs and shipping documents to attach to shipments.

Field	Type	What to enter
Required	Text	Choose one of: Commercial InvoiceCertificatePacking ListOther

Capability notes

Behavior that follows from UPS's capabilities. Read these before you go live.

Status via polling

This carrier has no push callback. Carriyo polls on a schedule, so tracking can lag the carrier's own system by a few minutes.

ZPL labels available

Returns ZPL in addition to PDF. Set the label format to print to thermal printers.

Customs document upload

You can attach commercial invoices and customs docs to international shipments via the API.

Next steps

Manage account settingsLabels, services, and the Active toggle.Set up costing profilesOverride carrier rates with your own.Add a custom carrierConnect a private fleet or unlisted carrier.Browse all carriersCompare capabilities across the directory.

Was this page helpful?