Request/Response Format

The default request/response format is JSON. Successful requests will return a 200 OK HTTP status.

Some general information about responses:

All fields are generally included in responses even if that shipping carrier doesn't support that field. These fields will be blank.
Dates are returned in RFC3339 format: YYYY-MM-DDTHH:MM:SSZ. Some shipping carriers don't indicate a timezone, in this case it will be assumed to be in local time indicated by -00:00 format: 2006-01-02T15:04:05-00:00.
Any decimal monetary amount, such as prices or totals, will be returned as floats with at least two decimal places.
Other amounts, such as package counts, are returned as integers.
When self-hosting, requests have no timeout unless the timeout parameter is specified. The timeout parameter is in milliseconds. The Cloud API has a hard timeout of 30 seconds which can be shortened but not extended.

Request Properties#

Field	Type	Description
carrier	`string`: `"ups"`	the shipping carrier the request is intended for
action	`string`: `"SubmitShipment"`	API action you wish to take i.e. `SubmitShipment`, `Track`, `GetAllRates` See: Available Actions
params	`object`: `{}`	Parameters for the API action you are taking

Carrier#

Carrier	Description
UPS	UPS (legacy) SOAP based API
UPS-REST	UPS Newer REST/oauth based API
FedEx	FedEx (legacy) SOAP based API
FedEx-FIMS	FedEx International MailService
FedEx-REST	FedEx REST/oauth based API
USPS	USPS direct API (no paid postage)
USPS-eVS	USPS eVS (direct USPS postage paid)
Stamps	Stamps.com
DHL	DHL XML PI API
DHL-GlobalMail	DHL Global Mail / eCommerce
DHL-DE	DHL Germany
DHL-PL	DHL Poland
Canada	Canada Post
Purolator	Purolator
GSO	Golden State Overnight now GLS
OnTrac	OnTrac
RoyalMail	Royal Mail
DPD	DPD
Dicom	Dicom
OD	Old Dominion Freight API

Action#

Action	Description
AcceptanceAuditPrecheck	Pre-check dangerous goods shipments before shipping
Authenticate	For carriers that require oauth temp tokens (FedEx-REST)
ChemicalReferenceLookup	Look up hazardous material reference information
Track	Track packages or shipments
GetAllRates	Get live rates for all services
SubmitShipment	Create shipping label
AddressValidate	Validate an address to get address suggestions
VoidShipment	Cancel a shipment
TimeInTransit	Get detailed transit time information and estimated delivery times
PickupRate	Determine cost of a pickup
CreatePickup	Schedule a carrier to pickup package(s)
DeliveryIntercept	Intercept or redirect a shipment while in transit
PickupStatus	Check the status of a pickup
CancelPickup	Cancel a previously scheduled pickup
GetSubscription	Download UPS Quantum View data as CSV
PurchasePostage	Purchase USPS postage (Stamps.com only)
CreateManifest	Create end-of-day report (USPS Scan Form)
FindLocations	Find drop-off locations, Access Points, etc.
AccountInfo	Get carrier account info (Stamps.com only)
UploadDocument	Upload user-defined customs documents
LinkDocument	Link user-defined customs documents to a shipment
Notify	Add email notifications to a package after it has been shipped
LabelRecovery	Recover (reprint) labels for a previously created shipment
GetTrackingDocuments	Retrieve tracking documents such as signature proof of delivery
LandedCost	Calculate the all-inclusive cost of an international shipment (duties, taxes, fees)
UploadImages	Upload letterhead/signature images for use in shipping paperwork
TrackAlert	Subscribe to tracking webhook notifications

Response Properties#

Field	Type	Description
meta	`object`: `{}`	`meta` holds metadata of the request
meta.code	`int`: `200`	`code` holds the RocketShipIt Response code
meta.error_message	`string`: `"Invalid JSON - invalid character '\"' after object key:value pair"`	`error_message` holds a RocketShipIt related (not a carrier error) error message
meta.debug_information	`object`: `{}`	`debug_information` holds information about the version of RocketShipIt used as well as all underlying API requests RocketShipIt made. This field is only returned when `debug:true`.
meta.debug_information.build_hash	`string`: `"02a0ba0ad38c644fcdb79a299ec9ec304cab91cc"`	`build_hash` is the computed hash of the code used to produce the version of RocketShipIt used
meta.debug_information.build_time	`string`: `"2018-12-14_06:18:28PM"`	`build_time` is the time in PST when RocketShipIt was built
meta.debug_information.request	`object`: `{}`	`request` is the request JSON made to RocketShipIt
meta.debug_information.version	`string`: `2.8.1.273`	`version` is the named version of RocketShipIt
meta.debug_information.transactions	`array`: `[]`	`transactions` holds a list of all transactions RocketShipIt made in association with the request (some actions require multiple underlying transactions)
transaction.duration	`int`: `441696573`	`duration` is nanoseconds it took to make the transaction with the carrier or 441696573 / 1,000,000,000 = 0.44 seconds
transaction.request	`string`: `JSON/XML`	`request` is the request body sent to the carrier
transaction.response	`string`: `JSON/XML`	`response` is the response body received from the carrier
transaction.status_code	`int`: `200`	`status_code` is the status code returned from the carrier
transaction.url	`string`: `https://ws.fedex.com:443/web-services/rate`	`url` is the endpoint/url RocketShipIt sent the request/transaction to
data	`object`: `{}`	`data` holds action response data

Action Response Properties#

Track#

Field	Type	Description
errors	`array`: `[]Error`	A list of errors
shipment_id	`string`: `"9361289878130102925130"`	shipment ID, for UPS this is the first tracking number in a multi-package shipment
destination	`object`: `{}`	Destination address of the shipment
destination.addr1	`string`: `"123 Main St."`	Address line 1
destination.addr2	`string`: `"Apt 2"`	Address line 2
destination.city	`string`: `"San Francisco"`	City
destination.state	`string`: `"CA"`	ISO state code
destination.postal_code	`string`: `"94115"`	zip/postal code
destination.country	`string`: `"US"`	ISO country code
origin	`object`: `{}`	Origin address of the shipment
origin.addr1	`string`: `"123 Main St."`	Address line 1
origin.addr2	`string`: `"Apt 2"`	Address line 2
origin.city	`string`: `"San Francisco"`	City
origin.state	`string`: `"CA"`	ISO state code
origin.postal_code	`string`: `"94115"`	zip/postal code
origin.country	`string`: `"US"`	ISO country code
estimated_delivery	`string`: `"2018-11-03T00:00:00-00:00"`	Datetime when the package should be delivered
delivered_time	`string`: `"2018-11-03T00:00:00-00:00"`	Datetime when the package was delivered
weight	`object`: `{"unit": "LB", "amount": 10.2}`	Weight of shipment
dimensions	`object`: `{}`	Dimensions of the shipment/package
service	`object`: `{"code": "013", "description": "UPS Saver"}`	Service type of the shipment
reference_numbers	`object`: `{"code": "PO", "value": "order123"}`	A list of reference number/values (Invoice, Purchase Order, etc) associated with the shipment
pickup_date	`string`: `"2018-11-03T00:00:00-00:00"`	Datetime when the shipment was picked up
packages	`array`: `[]`	A list of packages within the shipment
delivery_detail	`object`: `{}`	Details about when and how the package was delivered
activity	`array`: `[]`	A list of activity a shipment has experienced

GetAllRates#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
rates	`array`: `[]rate`	A list of rates for various services offered
restrictions	`array`: `[]restriction`	A list of shipping restrictions for this origin/destination pair (USPS only)
rate.desc	`string`: `"UPS Next Day Air Early AM"`	Description of the service
rate.rate	`float`: `15.42`	Total rate of the shipment including all surcharges
rate.commercial_rate	`float`: `14.49`	(USPS only) Total rate of the online (discounted) shipment including all surcharges
rate.negotiated_rate	`float`: `12.15`	Total rate of the your cost including all surcharges
rate.currency	`string`: `"USD"`	ISO currency code of rate
rate.service_code	`string`: `"FEDEX_GROUND"`	Service identifier
rate.est_delivery_time	`string`: `"2018-12-15T09:30:00-00:00"`	Estimated time until delivery (usually in destination timezone)
rate.delivery_days	`int`: `1`	Number of business/shipping days (non-holiday/non-shipping days) estimated until delivery
rate.package_type	`string`: `"YOUR_PACKAGING"`	Type of packaging
rate.rate_detail	`array`: `[]rate_detail`	Surcharges, taxes, fuel charges etc.
rate.taxes	`array`: `[]taxes`	Detailed tax charges with types
rate.billing_weight	`float`: `5.4`	Carrier calculated dimensional/billing weight
rate.guaranteed	`bool`: `true`	Indicates if service has guaranteed delivery
rate.saturday_delivery	`bool`: `true`	Indicates if service has saturday delivery special service
rate.zone	`string`: `"5"`	Zone where destination address is (USPS only)

SubmitShipment#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
charges	`float`: `14.49`	estimated actual charges for the shipment
tracking_number	`string`: `"1Z0W4A787299041353"`	tracking number for the shipment
shipment_id	`string`: `"1Z0W4A787299041353"`	shipment ID for the shipment, often the same as `tracking_number` for most carriers
billing_weight	`float`: `5.0`	calculated dimensional/billing weight of the shipment
packages	`array`: `[]package`	A list of packages in the shipment
package.tracking_number	`string`: `"1Z0W4A787299041353"`	tracking number for the package
package.label_format	`string`: `"image/png"`	MIME type of the resulting label
package.label	`string`: `"iVBORw0KGgoAAAANSUh..."`	base64 encoded label data
documents	`array`: `[]document`	A list of documents (usually customs paperwork) associated with the shipment
document.code	`string`: `"01"`	carrier code for document type
document.type	`string`: `"application/pdf"`	MIME type of the resulting document
document.media	`string`: `"iVBORw0KGgoAAAANSUh..."`	base64 encoded document data

AddressValidate#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
name	`string`: `"John Doe"`	Recipient name
addr1	`string`: `"123 Main St."`	Address line 1
addr2	`string`: `"Apt 2"`	Address line 2
addr3	`string`: `"building 9"`	Address line 3
city	`string`: `"San Francisco"`	City
state	`string`: `"CA"`	ISO state code
zipcode	`string`: `"94115"`	zip/postal code
zipcode_addon	`string`: `"1646"`	zip code addon
match	`bool`: `true`	`true` if address is high quality or considered valid
city_state_zip_match	`bool`: `true`	`true` if address has valid city, state, and zip combination
residential	`bool`: `true`	`true` if address is considered residential, not all carriers return this data
po_box	`bool`: `true`	`true` if address is a PO box
country	`string`: `"US"`	ISO country code
suggestions	`array`: `[]address`	A list of suggested addresses
checks	`array`: `[]check`	A list of checks ran for that address (FedEx only)
check.type	`string`: `"StreetRangeValidated"`	Type of address validation check `StreetRangeValidated`, `MissingOrAmbiguousDirectional`, etc
check.result	`bool`: `true`	the result of the check

VoidShipment#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
status_code	`string`: `"1"`	carrier void code
status	`string`: `"Voided"`	description of the void code

TimeInTransit#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
services	`[]service`: `[]`	a list of services offered by the carrier
service.desc	`string`: `"UPS Next Day Air Early"`	description of the service
service.service_code	`string`: `"1DM"`	the carrier's service code
service.is_guaranteed	`bool`: `true`	`true` when service has guaranteed delivery
service.eta	`int`: `1545040800`	timestamp when delivery is expected
service.formatted_eta	`string`: `"Mon December 17 by 10:00 am"`	formatted date and time when delivery is expected
service.delivery_days	`int`: `1`	number of shipping/business days until expected delivery

PickupRate#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
total_charge	`float64`: `10.33`	total charge for the pickup

CreatePickup#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
pickup_id	`string`: `"CL123"`	pickup confirmation ID

PickupStatus#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
pending_status	`[]pending_status`: `[]`	A list of pickups associated with your `account_number`
pending_status.pickup_id	`string`: `"2929AONCALL"`	pickup confirmation ID
pending_status.description	`string`: `"Received at dispatch"`	pickup description
pending_status.contact	`string`: `"Shipping Mgr."`	Contact name for person creating pickup
pending_status.reference_number	`string`: `"OnCallNextDayAir"`	User defined reference tag/ID

GetSubscription#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
events	`[]event`: `[]`	A list of shipping events
event.record_type	`string`: `""`	Event type code
event.shipper_number	`string`: `"abc123"`	shipper account number
event.shipper_name	`string`: `Acme Inc.`	the shipper's name
event.tracking_number	`string`: `"1Z0W4A780397852164"`	tracking number
event.to_name	`string`: `"John Doe"`	recipient contact name
event.pickup_date	`string`: `"2018-12-17T10:00:00-00:00"`	the date of the pickup
event.service	`string`: `"FEDEX_GROUND"`	service code
event.shipment_reference_value1	`string`: `""`	user-defined reference value
event.shipment_reference_value2	`string`: `""`	user-defined reference value
event.shipment_reference_value3	`string`: `""`	user-defined reference value
event.pkg_reference_value1	`string`: `""`	user-defined reference value
event.pkg_reference_value2	`string`: `""`	user-defined reference value
event.pkg_reference_value3	`string`: `""`	user-defined reference value

PurchasePostage#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
postage_purchased	`bool`: `true`	true if postage purchase request was successful
available_postage	`float64`: `120.00`	an updated postage balance

CreateManifest#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
documents	`[]document`: `example`	a list of documents
document.code	`string`: `""`	document code
document.type	`string`: `application/pdf`	MIME type of document
document.media	`string`: `"iVBORw0KGgoAAAANSUh..."`	base64 encoded contents of document

FindLocations#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
locations	`[]location`: `[]`	a list of locations
type	`string`: `"drop_location"`	location type code
name	`string`: `"THE UPS STORE"`	the name of the location
addr1	`string`: `"123 Main St."`	Address line 1
addr2	`string`: `"Apt 2"`	Address line 2
addr3	`string`: `"building 9"`	Address line 3
city	`string`: `"San Francisco"`	City
state	`string`: `"CA"`	ISO state code
zipcode	`string`: `"94115"`	zip/postal code
zipcode_addon	`string`: `"1646"`	zip code addon
country	`string`: `"US"`	ISO country code
phone_number	`string`: `"123-123-1234"`	phone number of location
fax_number	`string`: `"123-123-1235"`	fax number :)
email	`string`: `"[email protected]"`	email
distance	`distance`: `{}`	distance
distance.value	`float64`: `0.9`	distance value
distance.unit	`string`: `MI`	distance unit
id	`string`: `10518`	location ID
geocode	`geocode`: `example`	desc
geocode.lat	`float64`: `33.40742874`	latitude
geocode.long	`float64`: `-111.909774`	longitude
available_services	`[]loc_service`: `[]`	a list of available services the location supports
loc_service.code	`string`: `"008"`	service code
loc.service.desc	`string`: `"Early Pickup Delivery Time"`	description of service
normal_hours	`[]hours`: `[]`	normal shipping hours
desc	`string`: `""`	description of the location

AccountInfo#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
available_postage	`float64`: `50.0`	amount of available funds for postage

UploadDocument#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
document_id	`string`: `""`	document ID
status_code	`string`: `""`	document status code
status	`string`: `""`	description of status

LinkDocument#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
document_id	`string`: `""`	document ID
status_code	`string`: `""`	document status code
status	`string`: `""`	description of status

Notify#

Field	Type	Description
errors	`array`: `[]error`	A list of errors
tracking_number	`string`: `1Z0W4A780397852164`	tracking number of shipment