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:00format: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
timeoutparameter is specified. Thetimeoutparameter 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 |
|---|---|
| Authenticate | For carriers that require oauth temp tokens (FedEx-REST) |
| 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) |
| PickupState | Check the status of a 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 |
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 |
PickupState
| 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 :) |
string: "joe@email.com" | ||
| 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 |