OpenAPI Specification
openapi: 3.0.3
info:
title: UPS Address Validation Shipping API
description: The UPS Shipping API enables developers to create and manage shipments, generate shipping labels, validate addresses, retrieve rates, track packages, schedule pickups, manage returns, and access time-in-transit information. UPS uses OAuth 2.0 with client credentials for authentication.
version: v1
contact:
name: UPS Developer Support
url: https://developer.ups.com/
termsOfService: https://www.ups.com/us/en/help-center/legal-terms-conditions/developer-terms-of-service.page
servers:
- url: https://onlinetools.ups.com/api
description: UPS Production API
- url: https://wwwcie.ups.com/api
description: UPS Customer Integration Environment (CIE - Testing)
security:
- BearerAuth: []
tags:
- name: Shipping
description: Shipment creation and label generation
paths:
/shipments/v1/ship:
post:
operationId: createShipment
summary: Create Shipment
description: Create a new shipment and generate a shipping label. Returns a tracking number, label image, and shipment confirmation details.
tags:
- Shipping
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentRequest'
responses:
'200':
description: Shipment created with label
content:
application/json:
schema:
$ref: '#/components/schemas/ShipmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/shipments/v1/void/cancel/{shipmentIdentificationNumber}:
delete:
operationId: voidShipment
summary: Void Shipment
description: Cancel/void a shipment by its tracking number before it is tendered to UPS.
tags:
- Shipping
parameters:
- name: shipmentIdentificationNumber
in: path
required: true
schema:
type: string
description: UPS tracking number / shipment identification number
responses:
'200':
description: Shipment voided successfully
content:
application/json:
schema:
$ref: '#/components/schemas/VoidResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: OAuth token missing or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ShipmentResponse:
type: object
properties:
ShipmentResponse:
type: object
properties:
Response:
type: object
ShipmentResults:
type: object
properties:
ShipmentIdentificationNumber:
type: string
description: UPS tracking number
PackageResults:
type: array
items:
type: object
properties:
TrackingNumber:
type: string
ShippingLabel:
type: object
properties:
ImageFormat:
type: object
properties:
Code:
type: string
GraphicImage:
type: string
description: Base64-encoded label image
BillingWeight:
type: object
properties:
UnitOfMeasurement:
type: object
properties:
Code:
type: string
Weight:
type: string
ShipmentCharges:
type: object
properties:
TotalCharges:
type: object
properties:
CurrencyCode:
type: string
MonetaryValue:
type: string
ShipmentRequest:
type: object
required:
- ShipmentRequest
properties:
ShipmentRequest:
type: object
properties:
Request:
type: object
properties:
RequestOption:
type: string
enum:
- validate
- nonvalidate
Shipment:
type: object
properties:
Shipper:
$ref: '#/components/schemas/ShipperInfo'
ShipTo:
type: object
properties:
Name:
type: string
AttentionName:
type: string
Phone:
type: object
properties:
Number:
type: string
Address:
$ref: '#/components/schemas/Address'
Service:
$ref: '#/components/schemas/ServiceCode'
Package:
$ref: '#/components/schemas/PackageInfo'
LabelSpecification:
type: object
properties:
LabelImageFormat:
type: object
properties:
Code:
type: string
enum:
- GIF
- EPL
- ZPL
- PNG
LabelStockSize:
type: object
properties:
Height:
type: string
Width:
type: string
Address:
type: object
properties:
AddressLine:
type: array
items:
type: string
description: Street address lines
City:
type: string
StateProvinceCode:
type: string
description: Two-letter state/province code
PostalCode:
type: string
CountryCode:
type: string
description: Two-letter ISO country code
example: US
ResidentialAddressIndicator:
type: string
description: Presence indicates residential address
VoidResponse:
type: object
properties:
VoidShipmentResponse:
type: object
properties:
Response:
type: object
SummaryResult:
type: object
properties:
Status:
type: object
properties:
Code:
type: string
Description:
type: string
ErrorResponse:
type: object
properties:
response:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
ShipperInfo:
type: object
required:
- Name
- ShipperNumber
- Address
properties:
Name:
type: string
AttentionName:
type: string
ShipperNumber:
type: string
description: UPS account number
Phone:
type: object
properties:
Number:
type: string
Address:
$ref: '#/components/schemas/Address'
PackageInfo:
type: object
properties:
PackagingType:
type: object
properties:
Code:
type: string
description: 02 = customer supplied package
Dimensions:
type: object
properties:
UnitOfMeasurement:
type: object
properties:
Code:
type: string
enum:
- IN
- CM
Length:
type: string
Width:
type: string
Height:
type: string
PackageWeight:
type: object
properties:
UnitOfMeasurement:
type: object
properties:
Code:
type: string
enum:
- LBS
- KGS
Weight:
type: string
ServiceCode:
type: object
properties:
Code:
type: string
description: 'UPS service codes:
01=Next Day Air, 02=2nd Day Air, 03=Ground,
07=World Wide Express, 08=World Wide Expedited,
11=Standard, 12=3 Day Select, 13=Next Day Air Saver,
14=Next Day Air Early AM, 54=Worldwide Express Plus,
59=2nd Day Air A.M., 65=UPS Saver, 82=Today Standard,
83=Today Dedicated Courier, 84=Today Intercity,
85=Today Express, 86=Today Express Saver
'
Description:
type: string
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://onlinetools.ups.com/api/security/v1/oauth/token
scopes: {}
BearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 bearer token from /security/v1/oauth/token