Terms / Glossary
Developer That is you, the developer who is consuming the ShipRush Web Non-Visual API in a Web or desktop application
"Your Application" is the app you (the developer reading this) are responsible for. This API supports both desktop and browser applications.
Client Application or Client App same as above
Customer or User This is your customer or user. AKA "end user"
HTTP REST is a standard way of presenting an API on the Internet. RFC's, details, etc. are discussed in many places on the Internet, including Wikipedia http://en.wikipedia.org/wiki/Representational_State_Transfer
-
Fiddler Is a free tool that is very useful for working with and understanding a REST API. It is available at http://www.fiddler2.com/fiddler2/
Alternate tool: HTTP Analyzer
Alternative tool: curl
Date Time format: The My.ShipRush API uses the ISO 8601 Date/Time Format http://en.wikipedia.org/wiki/ISO_8601
What Is in this Kit
This PDF documentation
XSD that describes constants and the TShipment schema
cURL examples that work (in development)
C# code that has all enums and constants
C# Sample exe that can rate, ship, void
Persistence
ShipRush Desktop is on premise, and the ShipRush database is under your control.
In ShipRush Web, you get the same hybrid of rich-ShipRush-application plus your customization.
However, for API use (which in many cases will be high volume), there will be some limits on how long ShipRush Web saves shipping history. (Longer retention will be available for a subscription fee.) Initially, you should expect that shipping history will only be available in cloud for seven days. High volume sites should be aware that the non-visual platform may offer little to no persistence. That is the job of the calling application.
Quick Start: Get Shipping!
This Quick Start assumes you already are certain that this is the tool set for you. To understand the breadth and depth of developer tools available, please skip down to the Introduction.
Just Use the Ready-to-Run Curl Examples
\example-transactions\curl\
You need:
Access Token
Note: The token used on Sandbox, does not work on production. When moving to production, new tokens will be used.
curl, Fiddler or a similar tool to interactively run transactions (do this before writing code)
Knowledge of which URL to hit: Sandbox or Production
A Request Looks Like This
Requests are HTTP POST requests. (If you are not familiar with Fiddler or cURL, now is the time!)
POST /shipmentservice.svc/shipment/ship HTTP/1.1
X-SHIPRUSH-SHIPPING-TOKEN: #############################
X-SHIPRUSH-DEVELOPER-TOKEN: ##################
X-SHIPRUSH-VERSION: 84114
Content-Type: application/xml
Accept-Encoding: gzip, deflate
Host: sandbox.api.my.shiprush.com
Expect: 100-continue
Connection: Close
Content-Length: 3387
<?xml version="1.0" encoding="utf-8"?>
<RateRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<UPSServiceType>U02</UPSServiceType>
<Residential>0</Residential>
<Carrier>3</Carrier>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<InsuranceAmount>50</InsuranceAmount>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Doe</FirstName>
<Company>Acme Roofing</Company>
<Address1>120 Lakeside ave suite 101</Address1>
<Address2 />
<City>Seattle</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98122</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<FirstName>Mark White</FirstName>
<Company>Cat Food Unlimited</Company>
<Address1>3000 Landerholm Cir SE</Address1>
<Address2 />
<City>Bellevue</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98007</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
<ShipmentId />
</Shipment>
</ShipTransaction>
</RateRequest>
Do This
If you are not familiar with cURL, now is the time. (Did we mention that?)
Save the rate example below to a file: rate.txt
-
Using cURL, run this command (-k is required, at least on the Windows version of cURL we are using, to suppress SSL validation)
curl -k -X POST https://sandbox.api.my.shiprush.com/shipmentservice.svc/shipment/rate -H "X-SHIPRUSH-SHIPPING-TOKEN:a3673eb6-0f59-447f-ae62-aade23ec6229" -H "Content-Type:application/xml" -d @rate_usps.txt See the RateResponse
We hope that was quick!
What Just Happened
The cURL command does an HTTP POST against the specified endpoint. (The -X is how we specify the HTTP operation curl should do.)
-
We have added switches to add two required headers with the -H switch:
Content-Type:application/xml
X-SHIPRUSH-SHIPPING-TOKEN
-k is to suppress SSL enforcement (curl can be pesky in this way, in production code do NOT use such hacks!)
-d is to pull the POST input from a file
That is it.
Rate Example for cURL
<?xml version="1.0" encoding="utf-8"?>
<RateRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<Carrier>3</Carrier>
<UPSServiceType>U02</UPSServiceType>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<InsuranceAmount>50</InsuranceAmount>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Doe</FirstName>
<Company>Acme Roofing</Company>
<Address1>120 Lakeside ave suite 101</Address1>
<Address2 />
<City>Seattle</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98122</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<FirstName>Mark White</FirstName>
<Company>Cat Food Unlimited</Company>
<Address1>3000 Landerholm Cir SE</Address1>
<Address2 />
<City>Bellevue</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98007</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
</Shipment>
</ShipTransaction>
</RateRequest>More Curl Examples
Can be found in the \example-transactions\curl\ part of this kit.
URLs to Hit
Sandbox is: https://sandbox.my.shiprush.com
Production is: https://my.shiprush.com
Production shipping may never be done on Sandbox. All shipments on Sandbox are test shipments.
If production labels are created on SandBox, deliberately or by accident, your access to SandBox will be suspended.
Introduction - What Is the ShipRush Web Non-Visual API?
What Does It Solve?
The Non-Visual Web API offers a single entry point to create shipping labels for several shipping carriers. The API offers rates and labels. The intention is to surface all the carriers supported by ShipRush Web non visually. At this time, the list is:
FedEx
FedEx International Mail Service (aka FIMS)
UPS
USPS with postage
Direct Link
Amazon Buy Shipping
ShipRush Global (cross border shipping)
LTL shipping and rating
For ecommerce data, use the My.ShipRush Ecommerce API. The Ecommerce API gives a single REST entry point to access 36+ ecommerce systems, marketplaces and carts.
What Developer Entry Points Are Available?
ShipRush Web offers four developer entry points. Use the entry point best suited to your needs.
Javascript Visual Tool Kit
This tool kit is a visual tool. Instead of building a full shipping UI, this tool embeds the ShipRush Web UI in your Web application. This tool is for Web applications.
The Javascript entry point is to embed the ShipRush Web visual UI in any Web site or Web app. It takes minimal development effort (initial integration can usually be done in just an hour or two).
Pros: Quick, fast, little code, full ShipRush GUI and feature set for shipping, 2-way data flow.
Cons: Single label flow. Shipper must click through the ShipRush GUI for every shipment.
Ecommerce Integration Path, AKA Custom Web Store
This path lets ShipRush Web import orders/invoices/sales receipts from your system. This data feed is per ShipRush user and is automatic, in the background. To ship, the shipper uses ShipRush Web interactively. ShipRush Web sends shipment data (tracking numbers, service, etc.) back to your system.
To get started, simply request the Custom Web Store development kit. See the set up by going through the ShipRush Web "Add Web Store" wizard and select Custom Web Store.
Pros: Clear division of labor. Relatively easy to implement. Full ShipRush feature set surfaced for shippers. Batch shipping, etc. 2-way data flow (e.g., tracking #s are sent back to your application).
Cons: Shippers must use the ShipRush Web application to do shipping
Multi-Order Post In to ShipRush
Similar to the Javascript tool kit. This allows your system to, on a button click in your Web application, send multiple orders into ShipRush Web. Then they are shipped interactively in ShipRush Web.
This path is still being documented.
Pros: Simple to implement one way communication to ShipRush Web
Cons: Once the user has pressed the button in your application, you lose track of what the user is looking at.
Non-Visual Shipping API
This document! REST API in the cloud, for your application to generate labels, singly or in bulk.
Pros: More control. Users stay in your application. Access to ShipRush Web only needed for account setup (and possibly print set up). Supports ShipRush Cloud Print.
Cons: You need to build shipping UI elements. You may need to handle printing flow. Larger development effort.
What Are the Restrictions on It?
Generally speaking: The shipping account holder (or authorized agent) must interactively set up shipping accounts. In some cases, this can be waived, and/or API access can be used to create accounts.
For Users of the ShipRush Desktop SDK
Existing SOAP SDK Developers: Please review this section!
A design goal of the ShipRush Web API is to be as compatible as possible with the ShipRush SDK SOAP entry point. Preserving the TShipment schema and existing enumerations & constants is a key goal of the ShipRush Web API.
The overall payload does differ in a couple of respects:
XML Elements Are Used, not Attributes
The Desktop SOAP entry point requires that data be passed in as an XML Attribute:
<FirstName Value="Jane Smith"/>Most developers using the desktop SOAP API pass data as both Attribute and Element:
<FirstName Value="Jane Smith">Jane Smith</FirstName>Passing both is fine, but only the Attribute is read by the Desktop SOAP entry point. (The element data is ignored for most elements.)
In ShipRush Web, only the Elements is read. Attributes are optional (and will be ignored):
<FirstName>Jane Smith</FirstName>ShipRush Web is REST, not SOAP
The ShipRush SDK SOAP entry point had you pass a TShipment request wrapped in a SOAP envelope. Now you pass the TShipment block to the appropriate REST endpoint and wash that SOAP down the drain.
Printing, and the Settings Block Are Different or Gone
The great thing about ShipRush Web is that you can manage the response in your code or let ShipRush Cloud Print do the driving. But the way this is done is new and different. See the section below titled "Printing and label type control."
What About a Visual Shipping Component?
ShipRush Web has it. Just a few lines of Javascript, and you can embed the rich ShipRush Web UI in most any Web application.
Overview - How to Use
Structure of a Call
The REST calls are HTTPS calls to an endpoint. The body of the request describes the required object. Headers are required to pass required security tokens.
Calls Available
The API has the following calls:
rate
rateshopping
ship
void
validateaddress
eod (end of day)
getshippingaccounts
Understanding Responses
Valid calls will always return HTTP 200. HTTP 500 means the call was itself invalid in some way (structurally, or in terms of auth). 200 means that the call was processed. 200 does not mean the request generated a useful response. For example, if you have an otherwise valid call that is missing a required data element (e.g., address1), the call will return HTTP 200, and the actual status of the request will be in the IsSuccess element.
To find out whether the call succeeded, examine two areas:
<Messages/>
<IsSuccess>true</IsSuccess>The Messages block is where warnings and errors are passed to you. (e.g., "Address1 required")
The IsSuccess boolean tells you whether the call went through or not. (e.g., false because address1 omitted)
There may be Warnings and Messages even on (IsSuccess==true). Why? Because some shipment or rate operations will have additional information. In ShipRush Web interactively, this information is shown on message/warning panels at the top of the UI. In the API, it is passed in these message blocks.
Understanding Rates in Responses
Responses for shipping and rating include multiple elements related to the rate.
Rate related element |
Explanation |
CarrierRate |
This is the estimated total charge for the shipment, and includes charges, surcharges, carrier-calculated discounts (typically excluding variable volume based discounts), taxes and fees. It includes Declared Value coverage if that coverage is provided by the shipping carrier. |
ShippingCharges |
Same as above, with rate markup, if rate markup is configured in ShipRush settings. |
RateBaseCharge |
Legacy element in schema, from ShipRush Desktop. Not applicable to ShipRush Web. |
Understanding Time in Transit Information in Responses
<TimeInTransit>by end of Nov 16</TimeInTransit>
<TimeInTransitDays>1</TimeInTransitDays>
<TimeInTransitBusinessDays>1</TimeInTransitBusinessDays>All rate transactions return this, for services with delivery commitments across top tier carriers.
For ship transactions, it is returned only for USPS related shipping.
Security
Authentication for ShipRush Web Shipping API Calls
The My.ShipRush platform surfaces two sets of APIs: ecommerce-related API calls and shipping-related API calls. All the calls in this document use the X-SHIPRUSH-SHIPPING-TOKEN.
Two security tokens required to authenticate API call. Tokens should be passed as HTTP headers
Token |
HTTP Header |
Description |
ShippingToken |
X-SHIPRUSH-SHIPPING-TOKEN |
Identifies end-user and grants access to the shipping APIs. |
A developer token for the sandbox is included in the SDK sample apps. This is fine for exploring the API, but in most cases should not be used for real development. Check with your My.ShipRush support contact if you should use a specific sandbox token.
Production tokens are issued self-serve.
Please do not include production tokens in emails. Replace all but the last 3 digits with ### symbols. Also be careful with saved fiddler sessions, as these can contain production tokens!
Keep all tokens secure!
About Tokens
Note that all tokens are specific to a system (sandbox or production). Configure your system to use the tokens appropriate to the platform it is calling.
Authentication Sample
X-SHIPRUSH-SHIPPING-TOKEN: c5d0223d-3c38-4738-####-#############How To Get a Token
Because shipping labels are tied to a shipping account and will incur an actual dollar charge, there are a couple of steps to get a token.
Step One: Set up a ShipRush Web Account with One or More Shipping Accounts
This ShipRush Web account is where the shipping accounts and shipping history will reside. It should be set up by the actual shipper, or authorized agent of the shipper.
Need help setting up a ShipRush account? Check out our Web documentation, Add Shipping Accounts in Help Guide.
Step Two: Set ShipRush Web to Require Two Factor Authentication
If you do not have the "Google Authenticator" app on your cell phone, get it from the relevant app store.
Log in to ShipRush Web, go to Settings | User Settings | Change Password
Enable 2-Step verification
Follow the prompts
Step Three: Request Access
Log in to ShipRush Web, go to Settings | User Settings | Developer Tokens
Click to Apply to the Shipping Developer Program
Please enter complete information to identify your company and product
You will get an email from Z-Firm within one or two business days with approval.
Step Four: Retrieve Your Shipping Token
Log in to ShipRush Web, go to Settings | User Settings | Developer Tokens
Use the Show Token option to see the token
Notes:
Save the token securely (e.g., in encrypted storage that requires multi factor access). This token can ship against your shipping accounts and cause billing.
The token is only shown once. It is complex to regain access to it. Take care of it properly.
HTTP Headers: Required and Optional Headers
HTTP Header |
Required |
Expected value |
X-SHIPRUSH-SHIPPING-TOKEN |
Y |
See Authentication |
X-SHIPRUSH-VERSION |
N |
Desired version of XML response (similar to "Compatibility level"). If not specified - defaults to v.__________ |
Content-Type |
Y |
application/xml or text/xml |
Content-Length |
Y |
length of the request body |
Accept-Encoding |
Y |
gzip, deflate (Your application must be able to accept compressed responses. The ShipRush Web sandbox may allow omission of this element, but production may make it a hard requirement at any time.) |
User-Agent |
Y |
Application name of your application. This must clearly identify you, the developer. Valid values include: Your company name, Web site, or product name. Replace spaces with a hyphen or underscore. |
User-Agent-Version |
N |
Full version and build of the calling application (e.g., 2.0.0.1234) |
At this time, response are not compressed, but this is expected in a future version. In all cases, it is required that the calling application support compressed responses.
API Versioning in My.ShipRush X-SHIPRUSH-VERSION and More
<this section under development>
Using from Curl & Fiddler
Curl
The following syntax can be used, with all the curl examples.
The curl command does an HTTP POST against the specified endpoint. (the -X is how we specify the HTTP operation curl should do)
-
We have added switches to add two required headers with the -H switch:
Content-Type:application/xml
X-SHIPRUSH-SHIPPING-TOKEN:
-k is to suppress SSL enforcement (curl can be pesky in this way, in production code do NOT use such hacks!)
-d is to pull the POST input from a file
That is it.
Curl Example
curl -k -X POST https://sandbox.api.my.shiprush.com/shipmentservice.svc/shipment/rate -H "X-SHIPRUSH-SHIPPING-TOKEN:a3673eb6-0f59-447f-ae62-aade23ec6229" -H "Content-Type:application/xml" -d @rate_usps.txtMore Curl Examples
Can be found in the \samples\curl\ part of this kit.
Provided Sample Code
The .NET SDK can be used as a wrapper for the endpoints. Use the tool found in this location within the SDK: \ShipRush.SDK.Proxies\bin\Release\
If working in .NET, you can pull these assemblies into your project:
ShipRush.SDK.Proxies.dll
ShipRush.BusinessLayer.dll
If using ShipRush.SDK.Proxies\bin\Release\ShipRush.Tests.GUI.exe, take these steps:
Click the Show More Options button (center right)
Go to the Shipping tab (right hand)
Enter "Set urls to Sandbox"
Paste in a working shipping token
Use the options in the Shipping tab
API Calls
CreateShippingAccount
All Shipping API calls require fully configured Shipping Account. There are three ways to add and configure Shipping Account.
First Option: Interactive by Using the ShipRush Web Application
Log in to the My.ShipRush account.
Go to settings and click Add Shipping Account button.
Second Option: CreateShippingAccount API
This call returns a pre-authenticated URL that you can embed in your Web page or run in a new tab. Then call GetShippingAccount periodically to check if setup wizard completed or not. If you have full control over browser then instead of calling GetShippingAccount you can check that browser URL changed to "/ShipSettings/Account".
ShipRush.Tests.GUI.exe has a tab called "Shipping Account" that shows CreateShippingAccount workflow.
Sample Request
<?xml version="1.0" encoding="utf-8"?>
<CreateShippingAccountRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CarrierType>3</CarrierType>
</CreateShippingAccountRequest>Sample Response
<?xml version="1.0" encoding="utf-8"?>
<CreateShippingAccountResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ShippingAccountId>7d3b46e6-657f-47ad-9416-a617010de9eb</ShippingAccountId>
<SetupUrl>https://my.shiprush.com/CreateAccount/StartSetupEmbedded?SessionId=34b3571e-77bd-4aac-91e5-e2a37050c1c6&shippingAccountId=7d3b46e6-657f-47ad-9416-a617010de9eb</SetupUrl>
</CreateShippingAccountResponse>Third Option: CreateShippingAccountGetEulas + CreateShippingAccountGetEulas API
This option allows you to skip ShipRush UI and create shipping account without interaction with the Web browser or ShipRush UI. These call use eCommerce-style authentication (DeveloperToken + UserToken in the headers). Your developer token must be explicitly enabled for these calls (contact ShipRush support if you get "This API call is not allowed" error).
Access to the CreateShippingAccountGetEulas & CreateShippingAccountGetEulas calls is by special arrangement. These calls are not generally accessible.
Using this method is a multi-step operation:
-
Call CreateShippingAccountGetEulas(), in the response there are 2 end-user license agreements (Company_EndUserAgreement and Carrier_EndUserAgreement). You need to show them to the user. Your UI must present these EULAs to the shipper for acceptance. Depending on arrangement with ShipRush, the shipper must agree to one or both of these eulas before proceeding to next step.
For certain carriers it is possible that Carrier_EndUserAgreement is empty, in this case you should only show one agreement (Company_EndUserAgreement).
-
Collect new account information from the user. This form must have a checkbox with the text "I certify that all information is accurate and truthful". You should pass this value as "UserCertifiesThatAllInformationIsAccurateAndTruthful" to the next call.
If your application has authenticated access, and your application has done multiple financial transactions with the shipper (e.g., monthly subscription fee charges, other charges) over at least thirty days, the "UserCertifiesThatAllInformationIsAccurateAndTruthful" is not required in your UI.
Call CreateShippingAccountComplete(). Pass all account info + 2 eula signatures from step #1 in order to confirm that user accepted both agreements + "UserCertifiesThatAllInformationIsAccurateAndTruthful" = true.
From the response save ShippingAccountId for future references.
CreateShippingAccountGetEulas
https://<url>/accountservice.svc/shippingaccount/create_geteulas
<?xml version="1.0" encoding="utf-8"?>
<CreateShippingAccountGetEulasRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CarrierType>1</CarrierType>
</CreateShippingAccountGetEulasRequest>
<CreateShippingAccountGetEulasResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Company_EndUserAgreement>h1. MY.SHIPRUSH TERMS OF USE
..........
</Company_EndUserAgreement>
<Company_EndUserAgreement_Signature>18681ed6cad9ccb7abc9be80f7c294b13c8bdf3fabfc421e7916ee54c1ba9a64</Company_EndUserAgreement_Signature>
<Carrier_EndUserAgreement>h1. FedEx TERMS OF USE
..........
</Carrier_EndUserAgreement>
<Carrier_EndUserAgreement_Signature>ed6cad9ccb7abc9be80f7c294b13c8bdf3fabfc421e7916ee54c1ba9a6418681</Carrier_EndUserAgreement_Signature>
</CreateShippingAccountGetEulasResponse>CreateShippingAccountComplete
https://<url>/accountservice.svc/shippingaccount/create_complete
<?xml version="1.0" encoding="utf-8"?>
<CreateShippingAccountCompleteRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Company_EndUserAgreement_AcceptedByUser>true</Company_EndUserAgreement_AcceptedByUser>
<Company_EndUserAgreement_Signature>18681ed6cad9ccb7abc9be80f7c294b13c8bdf3fabfc421e7916ee54c1ba9a64</Company_EndUserAgreement_Signature>
<Carrier_EndUserAgreement_AcceptedByUser>true</Carrier_EndUserAgreement_AcceptedByUser>
<Carrier_EndUserAgreement_Signature>ed6cad9ccb7abc9be80f7c294b13c8bdf3fabfc421e7916ee54c1ba9a6418681</Carrier_EndUserAgreement_Signature>
<UserCertifiesThatAllInformationIsAccurateAndTruthful>true</UserCertifiesThatAllInformationIsAccurateAndTruthful>
<ShippingAccount>
<CarrierType>1</CarrierType>
<AccountNumber>44XXXXXX</AccountNumber>
<AccountAddress>
<FirstName>Test</FirstName>
<LastName>User</LastName>
<Company>ACME llc</Company>
<Address1>120 Lakeside ave ste 101</Address1>
<City>Seattle</City>
<State>WA</State>
<StateOrEmpty>WA</StateOrEmpty>
<Country>US</Country>
<StateAsString>WA</StateAsString>
<CountryAsString>US</CountryAsString>
<PostalCode>98122</PostalCode>
<Phone>2062066666</Phone>
<EMail>test@zfirmllc.com</EMail>
</AccountAddress>
<IsSandbox>false</IsSandbox>
</ShippingAccount>
</CreateShippingAccountCompleteRequest>
<CreateShippingAccountCompleteResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShippingAccount>
<ShippingAccountId>d46cc97c-64fa-4970-bf9e-a67200af7317</ShippingAccountId>
<CarrierType>1</CarrierType>
<IsSandbox>false</IsSandbox>
<Status>Activated</Status>
<AccountRates>NegotiatedRates</AccountRates>
<CreatedAt>2016-08-30T17:38:47.5399638Z</CreatedAt>
<AccountNumber>44XXXXX</AccountNumber>
</ShippingAccount>
</CreateShippingAccountCompleteResponse>Lookup Services & Packaging Types
The API surfaces two functions that return a list of available services and packaging types for a carrier you specify.
Lookup Services Request
Specify a carrier, get a list of available shipping services.
http://<url>/shipmentservice.svc/shipment/lookup/services
<GetServiceTypesRequest>
<CarrierType>17</CarrierType>
</GetServiceTypesRequest>Lookup Services Response
<GetServiceTypesResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ServiceTypes>
<TUPSService>U01</TUPSService>
<TUPSService>U02</TUPSService>
<TUPSService>U05</TUPSService>
<TUPSService>U04</TUPSService>
<TUPSService>U03</TUPSService>
<TUPSService>U07</TUPSService>
<TUPSService>U08</TUPSService>
</ServiceTypes>
</GetServiceTypesResponse>Lookup PackagingType Request
http://<url>/shipmentservice.svc/shipment/lookup/packaging
Requires:
Carrier
Service Type (shipping service)
Some options (like USPS Regional Rate boxes and Letter packaging) will not always work. For example, the ultimate shipment may not be in a zone range that fits the Regional Rate box, or the shipment may be too heavy for FedEx/UPS/USPS Letter packaging.
The list of packaging options is the full list of what is possible for the carrier and service (as many packaging types are specific to a carrier or to a service). It is not a guarantee that the given packaging will work with the other shipping options.
<GetPackagingTypesRequest>
<CarrierType>17</CarrierType>
<ServiceType>U02</ServiceType>
</GetPackagingTypesRequest>Lookup PackagingType Response
<GetPackagingTypesResponse>
<PackagingTypes>
<TPackageType>02</TPackageType>
<TPackageType>U2</TPackageType>
<TPackageType>U6</TPackageType>
<TPackageType>U1</TPackageType>
<TPackageType>U8</TPackageType>
<TPackageType>U0</TPackageType>
<TPackageType>U7</TPackageType>
<TPackageType>UB</TPackageType>
<TPackageType>EWS1</TPackageType>
<TPackageType>EWS6</TPackageType>
<TPackageType>EWS7</TPackageType>
</PackagingTypes>
</GetPackagingTypesResponse>Lookup Available Shipment Options (Retrieve Available Enums)
The API (and the .NET SDK) surfaces function that gives list of available service, package & accessorial options based on the partial shipment template. The more information you pass in request (more shipment fields are filled in) the more detailed response you get. (see Rate for a full Shipment details).
You may use this call multiple times, where in the first call you get broad list of available services/options and then (as customer makes or your business logic makes a selection about accessorials) you make the same call again, only providing more details (service and packaging) in the request.
At minimum we recommend specifying for the first request:
Carrier
ShipTo Country
GetShipmentOptionsResponse will include shipmentOptions that are not availalbe for every carrier. For example, LimitedAccessDeliveryItems is only available for freight carriers. But possible values will be displayed for all carriers.
If you are unsure of valid shipment options, or what elements are required for a given shipment/service combination, there is a solution: Use the ShipRush GUI interactively. What we mean here is: Use the ShipRush GUI as the documentation of what is available for a given shipment. The ShipRush GUI is the definitive benchmark for what is allowed on any given shipment. If an option is not available in the ShipRush UI, you should not make it available to your shippers.
The ShipRush GUI is enhanced, often multiple times a month, to accurately reflect what is available (and what is required) for specific shipment types. To our knowledge, it is the most complete documentation available.
Request
http://<url>/shipmentservice.svc/shipment/lookup/shipmentoptions
.NET wrapper function: APICommand SHIPMENT_LOOKUP_SHIPMENTOPTIONS
<GetShipmentOptionsRequest>
<ShipTransaction>
<Shipment>
<Carrier>1</Carrier>
<DeliveryAddress>
<Address>
...
<Country>US</Country>
</Address>
</DeliveryAddress>
...
</Shipment>
</ShipTransaction>
</GetShipmentOptionsRequest>Response
<GetShipmentOptionsResponse>
<UIFeatures>
<HidePackaging>false</HidePackaging>
<ShowWeight>true</ShowWeight>
<ShowWeightOunces>false</ShowWeightOunces>
...
</UIFeatures>
<ServiceTypeItems>
<TUPSService>I06</TUPSService>
<TUPSService>I01</TUPSService>
<TUPSService>FDXIPE</TUPSService>
<TUPSService>I03</TUPSService>
<TUPSService>I92</TUPSService>
</ServiceTypeItems>
<ShipToCountryItems>
<TCountry>US</TCountry>
<TCountry>CA</TCountry>
<TCountry>AL</TCountry>
<TCountry>DZ</TCountry>
<TCountry>AS</TCountry>
...
</ShipToCountryItems>
<PackagingTypeItems>
<TPackageType>02</TPackageType>
<TPackageType>01</TPackageType>
...
</PackagingTypeItems>
...
</GetShipmentOptionsResponse>Rate
Get a single rate for a specific service, packaging, shipment.
Request http://<url>/shipmentservice.svc/shipment/rate
http://<url>/shipmentservice.svc/shipment/rate
<?xml version="1.0" encoding="utf-8"?>
<RateRequest>
<ShipTransaction>
<Shipment>
...
</Shipment>
</ShipTransaction>
</RateRequest>
<RateResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<ShipTransaction>
<Shipment>
<ShippingCharges>5.75</ShippingCharges>
<InsuranceRate>0</InsuranceRate>
<ClearPathRate>0</ClearPathRate>
<CarrierRate>5.75</CarrierRate>
<InsuranceCharges>0</InsuranceCharges>
<FreightCharges>0</FreightCharges>
<OtherCharges>0</OtherCharges>
....
</Shipment>
</ShipTransaction>
</RateResponse>Different carriers have different requirements for how much details do you need to pass about shipment. For example, Deliv.co requires package Dimensions and Reference1 even for rating. Here is an example of the Deliv.co Rate request.
<?xml version="1.0" encoding="utf-8"?>
<RateRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
...
<Carrier>15</Carrier>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<PkgLength>4</PkgLength>
<PkgWidth>4</PkgWidth>
<PkgHeight>4</PkgHeight>
<PackageReference1>ShipRush Socks 2x Pack</PackageReference1>
<InsuranceAmount>50</InsuranceAmount>
</Package>
...
</Shipment>
</ShipTransaction>
</RateRequest>Response
<RateResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<ShipTransaction>
<Shipment>
<UnitsOfMeasureLinear>IN</UnitsOfMeasureLinear>
<PostbackContentType>Unknown</PostbackContentType>
<ShippingCharges>5.75</ShippingCharges>
<AccountId>00000000-0000-0000-0000-000000000000</AccountId>
<InsuranceRate>0</InsuranceRate>
<ClearPathRate>0</ClearPathRate>
<CarrierRate>5.75</CarrierRate>
<InsuranceCharges>0</InsuranceCharges>
<FreightCharges>0</FreightCharges>
<OtherCharges>0</OtherCharges>
<UPSServiceType>U02</UPSServiceType>
<Residential>0</Residential>
<DocInd>3</DocInd>
<FDXSPIndicia>0</FDXSPIndicia>
<FDXSPAncillaryEndorsement>0</FDXSPAncillaryEndorsement>
<ShipDate>2015-12-08T08:00:00.000Z</ShipDate>
<FDXHomeDeliverySignReq>0</FDXHomeDeliverySignReq>
<Carrier>3</Carrier>
<CargoAircraftOnly>0</CargoAircraftOnly>
<Package>
<DangerousGoodsType>0</DangerousGoodsType>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<AdditionalHandling>0</AdditionalHandling>
<InsuranceType>Unknown</InsuranceType>
<InsuranceAmount>50</InsuranceAmount>
<InsuranceCurrency>USD</InsuranceCurrency>
<FDXPriorityAlert>0</FDXPriorityAlert>
<NonStandardContainerFlag>0</NonStandardContainerFlag>
</Package>
<Shipper3PartyBillingAddress>
<Address>
<Country>US</Country>
<StateAsString>Unknown</StateAsString>
<CountryAsString>US</CountryAsString>
</Address>
</Shipper3PartyBillingAddress>
<DeliveryAddress>
<Address>
<LastName>John Doe</LastName>
<Company>Acme Roofing</Company>
<Address1>120 Lakeside ave suite 101</Address1>
<Address2/>
<City>Seattle</City>
<State>WA</State>
<Country>US</Country>
<StateAsString>WA</StateAsString>
<CountryAsString>US</CountryAsString>
<PostalCode>98122</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<LastName>Mark White</LastName>
<Company>Cat Food Unlimited</Company>
<Address1>3000 Landerholm Cir SE</Address1>
<Address2/>
<City>Bellevue</City>
<State>WA</State>
<Country>US</Country>
<StateAsString>WA</StateAsString>
<CountryAsString>US</CountryAsString>
<PostalCode>98007</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
<HALAddress/>
<ShipmentStatus>Unknown</ShipmentStatus>
<ShipmentType>Pending</ShipmentType>
<CESFlag>0</CESFlag>
<ITARFlag>0</ITARFlag>
<ReturnsClearanceFlag>0</ReturnsClearanceFlag>
<AlcoholRecipient>0</AlcoholRecipient>
<FreightRole>Unknown</FreightRole>
<FreightCollectTerms>Unknown</FreightCollectTerms>
<FreightDeclaredValuePerUnitAmount>0</FreightDeclaredValuePerUnitAmount>
<FreightDeclaredValuePerUnitCurrency>USD</FreightDeclaredValuePerUnitCurrency>
<FreightDeclaredValueUnits>0</FreightDeclaredValueUnits>
<FreightTotalHandlingUnits>0</FreightTotalHandlingUnits>
<FreightClientDiscountPercent>0</FreightClientDiscountPercent>
<FreightPalletWeight>0</FreightPalletWeight>
<FreightSizeL>0</FreightSizeL>
<FreightSizeW>0</FreightSizeW>
<FreightSizeH>0</FreightSizeH>
<FreightCoverageType>Unknown</FreightCoverageType>
<FreightCoverageAmount>0</FreightCoverageAmount>
<FreightCoverageCurrency>USD</FreightCoverageCurrency>
<ItemFreightClass>Unknown</ItemFreightClass>
<ItemClassProvidedByCustomer>false</ItemClassProvidedByCustomer>
<ItemHandlingUnits>0</ItemHandlingUnits>
<ItemPackaging>Unknown</ItemPackaging>
<ItemPieces>0</ItemPieces>
<ItemWeight>0</ItemWeight>
<ItemSizeL>0</ItemSizeL>
<ItemSizeW>0</ItemSizeW>
<ItemSizeH>0</ItemSizeH>
</Shipment>
</ShipTransaction>
</RateResponse>Several carriers (FusionLogistics, Deliv.co, Banyan) require you to save ShipmentQuoteId from the Rate response and pass it back to Ship transaction. A good practice to follow: if Rate or RateShopping response has data in the ShipmentQuoteId field - always pass it to the future Ship transaction.
Example: Deliv.co Rate Response
<RateResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<ShippingCharges>8.5</ShippingCharges>
<ShipmentQuoteId>e9c1edd2-7b0e-4e2b-8ec3-8908e6e541f7</ShipmentQuoteId> // The relevant value to pass into the shipment
...
</Shipment>
</ShipTransaction>
</RateResponse>RateShopping
New in ShipRush Web
Returns all relevant rates for the shipment across multiple services. Follows settings in ShipRush Web. For example, by default, it returns all services for the carrier requested. However, if the ShipRush Web account is configured to rate shop across multiple carriers, this call will return the same payload. See the product documentation for details: http://my.shiprush.com/docs/zfirm/EN-US/#Reference/Rate_Shopping.htm
Some carriers REQUIRE RateShopping before Ship is possible. Carriers include:
WWEX Freight
Banyan
Request: http://<url>/shipmentservice.svc/shipment/rateshopping
http://my.shiprush.com/shipmentservice.svc/shipment/rateshopping
<?xml version="1.0" encoding="utf-8"?>
<RateShoppingRequest>
<ShipTransaction>
<Shipment>
...
</Shipment>
</ShipTransaction>
</RateShoppingRequest>Similar to Rate transaction, RateShopping may require additional information about package. For example Deliv.co always requires package dims and reference. LTL carriers require FreightCommodities.
RateShopping for Most Carriers
General RateShopping Request
<?xml version="1.0" encoding="utf-8"?>
<RateShoppingRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<InsuranceAmount>50</InsuranceAmount>
<PkgLength>4</PkgLength>
<PkgWidth>4</PkgWidth>
<PkgHeight>4</PkgHeight>
<PackageReference1>ShipRush Socks 2x Pack</PackageReference1>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Doe</FirstName>
<Company>Acme Roofing</Company>
<Address1>120 Lakeside ave suite 101</Address1>
<Address2 />
<City>Seattle</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98122</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<FirstName>Mark White</FirstName>
<Company>Cat Food Unlimited</Company>
<Address1>3000 Landerholm Cir SE</Address1>
<Address2 />
<City>Bellevue</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98007</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
</Shipment>
</ShipTransaction>
</RateShoppingRequest>General RateShopping Response
<RateShoppingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages>
</Messages>
<IsSuccess>true</IsSuccess>
<AvailableServices>
<AvailableService>
<ShippingAccountId>4137853b-46eb-4cd1-9436-a4e600cdd94b</ShippingAccountId>
<Name>USPS Priority Mail</Name>
<ServiceType>U02</ServiceType>
<PackagingType>02</PackagingType>
<OneRate>false</OneRate>
<Currency>USD</Currency>
<CarrierRate>12.59</CarrierRate>
<Markup>0</Markup>
<Total>12.59</Total>
<TimeInTransitText>2-8 days</TimeInTransitText>
<TimeInTransitDays>0</TimeInTransitDays>
<ExpectedDelivery>12/16/2015 8:00:00 PM</ExpectedDelivery>
</AvailableService>
<AvailableService>
......
</AvailableService>
</AvailableServices>
</RateShoppingResponse>LTL/Freight RateShopping
Freight Requests require an additional "FreightCommodities" element.
Banyan Request
<?xml version="1.0" encoding="utf-8"?>
<RateShoppingRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<Carrier>31</Carrier>
...
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>18</PackagingType>
<PkgLength>4</PkgLength>
<PkgWidth>4</PkgWidth>
<PkgHeight>4</PkgHeight>
<FreightCommodity>
<ItemFreightClass>CLASS_050</ItemFreightClass>
<ItemDescription>ShipRush Socks 2x Pack</ItemDescription>
<ItemNMFC>103300</ItemNMFC>
<ItemPackaging>BUNDLE</ItemPackaging>
<ItemWeight>15</ItemWeight>
<ItemPieces>6</ItemPieces>
</FreightCommodity>
<FreightCommodity>
...
</FreightCommodity>
</Package>
</Shipment>
</ShipTransaction>
</RateShoppingRequest>Banyan Response
<RateShoppingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages></Messages>
<IsSuccess>true</IsSuccess>
<AvailableServices>
<AvailableService>
<ShippingAccountId>a225eb9f-b332-4fd3-9aec-a9dd000574b0</ShippingAccountId>
<Name>not selected</Name>
<ServiceType>@@</ServiceType>
<PackagingType>02</PackagingType>
<OneRate>false</OneRate>
<Currency>USD</Currency>
<CarrierRate>236.35</CarrierRate>
<Markup>0</Markup>
<Total>236.35</Total>
<TimeInTransitText>2 days</TimeInTransitText>
<TimeInTransitDays>2</TimeInTransitDays>
<TimeInTransitBusinessDays>0</TimeInTransitBusinessDays>
<ExpectedDelivery>2/5/2019 8:00:00 PM</ExpectedDelivery>
<IsEstimated>false</IsEstimated>
<ShipmentQuoteId>202737789</ShipmentQuoteId>
<ShipmentLoadId>21964115</ShipmentLoadId>
<UseServiceAsString>true</UseServiceAsString>
<ServiceAsString>UPS Ground Freight Inc.</ServiceAsString>
</AvailableService>
<AvailableService>
<ShippingAccountId>a225eb9f-b332-4fd3-9aec-a9dd000574b0</ShippingAccountId>
<Name>not selected</Name>
<ServiceType>@@</ServiceType>
<PackagingType>02</PackagingType>
<OneRate>false</OneRate>
<Currency>USD</Currency>
<CarrierRate>242.35</CarrierRate>
<Markup>0</Markup>
<Total>242.35</Total>
<TimeInTransitText>2 days</TimeInTransitText>
<TimeInTransitDays>2</TimeInTransitDays>
<TimeInTransitBusinessDays>0</TimeInTransitBusinessDays>
<ExpectedDelivery>2/5/2019 8:00:00 PM</ExpectedDelivery>
<IsEstimated>false</IsEstimated>
<ShipmentQuoteId>202737790</ShipmentQuoteId>
<ShipmentLoadId>21964115</ShipmentLoadId>
<UseServiceAsString>true</UseServiceAsString>
<ServiceAsString>Old Dominion Frt Line</ServiceAsString>
</AvailableService>
</AvailableServices>
</RateShoppingResponse>Deliv.co RateShopping
Deliv.co Request
<?xml version="1.0" encoding="utf-8"?>
<RateShoppingRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<Carrier>15</Carrier>
...
<Package>
<PackagingType>02</PackagingType>
<PkgLength>4</PkgLength>
<PkgWidth>4</PkgWidth>
<PkgHeight>4</PkgHeight>
<PackageReference1>ShipRush Socks 2x Pack</PackageReference1>
<InsuranceAmount>50</InsuranceAmount>
</Package>
</Shipment>
</ShipTransaction>
</RateShoppingRequest>Deliv.co RateShopping Response
Deliv.co RateShopping response has extra info "PickupAt" that indicates earliest time when Deliv driver can show up. To pick specific service from RateShopping response you need to pass "ShipmentQuoteId" to the Ship transaction.
<RateShoppingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<AvailableServices>
<AvailableService>
<ShippingAccountId>d5f43ce3-cc72-4afa-bd4d-a61300a42a6f</ShippingAccountId>
<Name>Deliv Same Day</Name>
<ServiceType>DELIVSAMEDAYSTD</ServiceType>
<PackagingType>02</PackagingType>
<OneRate>false</OneRate>
<Currency>USD</Currency>
<CarrierRate>8.5</CarrierRate>
<Markup>0</Markup>
<Total>8.5</Total>
<TimeInTransitText>Same Day</TimeInTransitText>
<TimeInTransitDays>1</TimeInTransitDays>
<TimeInTransitBusinessDays>1</TimeInTransitBusinessDays>
<ExpectedDelivery>6/9/2016 8:00:00 PM</ExpectedDelivery>
<IsEstimated>true</IsEstimated>
<PickupAt>Tomorrow from AM</PickupAt>
<ShipmentQuoteId>e9c1edd2-7b0e-4e2b-8ec3-8908e6e541f7</ShipmentQuoteId>
<UseServiceAsString>true</UseServiceAsString>
<ServiceAsString>Deliv Same Day, delivery Jan 15 from 1:00 PM to 4:00 PM</ServiceAsString>
</AvailableService>
<AvailableService>
......
</AvailableService>
</AvailableServices>
</RateShoppingResponse>Printing and Label Type Control
Shipping API gives you full control over printing and label types. All printable documents are always available in the shipment response. You could also request for documents to be autoprinted by ShipRush Desktop Toolkit (separate desktop application, available for Windows and OSX). Desktop Toolkit supports both raster (PDF,PNG) and thermal (ZPL) label formats.
When using ShipRush Desktop Toolkit for printing you could use "default" printer name (configurable interactively at http://my.shiprush.com/ShipSettings) or send printer name with every transaction (you should use "/accountservice.svc/print/getprinters" call to get list of connected/available printers).
In Webshipping API you set printing options per "document group". There are eight document groups total. If you do not need a fine-grained control per document type, or if you are not sure which documents your shipment will generate - just set ALL of these to the same settings (see Ship example below).
PrinterShippingLabel
PrinterPackingList
PrinterInternationalDocuments
PrinterSmallInternationalItems
PrinterLargeEnvelopes
PrinterLetterPost
PrinterDownloadDocuments
PrinterPalletLabel
Note that when using AutoprintShippingLabels option you should check ShipResponse.Messages for messages with "Severity" = "warning". Printing errors (printer offline, unable to print, etc.) would go there.
Values Available for <LabelType>
The only supported LabelType values are:
PNG
PDF
ZPL
Getting List of Available Printers
https://url/accountservice.svc/print/getprinters
Request
Parameter ComputerId
Is name of the computer that is running ShipRush Desktop Toolkit.
How to get it:
Press Windows icon in toolbar
Type "CMD"
Click on "Command Prompt"
Write "hostname" into Command Prompt window and press Enter
<?xml version="1.0" encoding="utf-8"?>
<GetPrintersRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ComputerId>{COMPUTER_NAME}</ComputerId>
</GetPrintersRequest>Response
<?xml version="1.0" encoding="utf-8"?>
<GetPrintersResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Printers>
<CloudPrinter>
<ComputerId>DESKTOP-SHIPPING-11</ComputerId>
<ComputerName>DESKTOP-SHIPPING-11</ComputerName>
<PrinterId>LaserJet 2000</PrinterId>
<WebShippingPrinterId>e6a11d54-34d1-472b-b9ac-9c9300e9f3e4::DESKTOP-SHIPPING-11::LaserJet 2000</WebShippingPrinterId>
<IsOnline>true</IsOnline>
</CloudPrinter>
</Printers>
</GetPrintersResponse>Printing Examples
Download ZPL labels
<PrinterShippingLabel>
<LabelType>ZPL</LabelType>
</PrinterShippingLabel>Download PNG labels
<PrinterShippingLabel>
<LabelType>PNG</LabelType>
</PrinterShippingLabel>Autoprint raster shipping label using Desktop Toolkit on "LaserJet 2000" printer
<PrinterShippingLabel>
<PrintProcessorId>shiprush_cloud_print</PrintProcessorId>
<PrinterId>e6a11d54-34d1-472b-b9ac-9c9300e9f3e4::DESKTOP-SHIPPING-11::LaserJet 2000</PrinterId>
<LabelType>PNG</LabelType>
<LaserLabelType>Laser_4x6</LaserLabelType>
<AutoprintShippingLabel>true</AutoprintShippingLabel>
<Copies>1</Copies>
<HorizontalMargin>0.2</HorizontalMargin>
<VerticalMargin>0.2</VerticalMargin>
<RotateLabel>false</RotateLabel>
</PrinterShippingLabel>Autoprint ZPL shipping label using Desktop Toolkit on "ZEBRA 450" printer
<PrinterShippingLabel>
<PrintProcessorId>shiprush_cloud_print</PrintProcessorId>
<PrinterId>e6a11d54-34d1-472b-b9ac-9c9300e9f3e4::DESKTOP-SHIPPING-11::ZEBRA 450</PrinterId>
<LabelType>ZPL</LabelType>
<LabelStockType>Thermal_4x6</LabelStockType>
<AutoprintShippingLabel>true</AutoprintShippingLabel>
<Copies>1</Copies>
<HorizontalMargin>0</HorizontalMargin>
<VerticalMargin>0</VerticalMargin>
<PrintReverse>false</PrintReverse>
</PrinterShippingLabel>Complete Request with Printer Control
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipSettings>
<PrinterShippingLabel>
<AutoprintShippingLabel>false</AutoprintShippingLabel>
<LabelType>PNG</LabelType>
</PrinterShippingLabel>
</ShipSettings>
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<Carrier>1</Carrier>
<UPSServiceType>F92</UPSServiceType>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<InsuranceAmount>50</InsuranceAmount>
</Package>
<Package>
<PackageActualWeight>2</PackageActualWeight>
<PackagingType>02</PackagingType>
<InsuranceAmount>50</InsuranceAmount>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Doe</FirstName>
<Company>Acme Roofing</Company>
<Address1>120 Lakeside ave suite 101</Address1>
<Address2 />
<City>Seattle</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98122</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<FirstName>Mark White</FirstName>
<Company>Cat Food Unlimited</Company>
<Address1>3000 Landerholm Cir SE</Address1>
<Address2 />
<City>Bellevue</City>
<State>WA</State>
<Country>US</Country>
<PostalCode>98007</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
</Shipment>
</ShipTransaction>
</ShipRequest>Ship
Request http://<url>/shipmentservice.svc/shipment/ship
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest>
<ShipTransaction>
<Shipment>
...
</Shipment>
</ShipTransaction>
<ShipSettings>
<PrinterShippingLabel>
<LabelType>ZPL</LabelType>
</PrinterShippingLabel>
<PrinterPackingList>
<LabelType>ZPL</LabelType>
</PrinterPackingList>
<PrinterInternationalDocuments>
<LabelType>ZPL</LabelType>
</PrinterInternationalDocuments>
<PrinterSmallInternationalItems>
<LabelType>ZPL</LabelType>
</PrinterSmallInternationalItems>
<PrinterLargeEnvelopes>
<LabelType>ZPL</LabelType>
</PrinterLargeEnvelopes>
<PrinterLetterPost>
<LabelType>ZPL</LabelType>
</PrinterLetterPost>
<PrinterDownloadDocuments>
<LabelType>ZPL</LabelType>
</PrinterDownloadDocuments>
<PrinterPalletLabel>
<LabelType>ZPL</LabelType>
</PrinterPalletLabel>
</ShipSettings>
</ShipRequest>Note: For FusionLogistics LTL, the ShipRequest.ShipTransaction.Shipment.ShipmentQuoteId element is required. Set to to the value from the RateResponse. For Deliv.co it is recommended that you set ShipmentQuoteId (but if left blank - ShipRush will pick service with earliest possible pickup time, which may be tomorrow if it is too late in the day).
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<ShipmentQuoteId>e9c1edd2-7b0e-4e2b-8ec3-8908e6e541f7</ShipmentQuoteId>
<ReadyTimeType>ReadyTimeAdvanceMinutes</ReadyTimeType>
<ReadyTimeAdvanceMinutes>60</ReadyTimeAdvanceMinutes>
</Shipment>
</ShipTransaction>
</ShipRequest>Request - Amazon Buy Shipping
Amazon Buy Shipping is restricted for use with Amazon orders only. To use Amazon Buy Shipping as a carrier, the user must have an Amazon Web store fully configured in their ShipRush account.
Additional information required:
WebstoreId (found in ShipRush or via eCommerce API)
Amazon Order Number
Amazon Item Id (for each item)
Quantity being Shipped (for each item)
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<WebstoreId>e9c1edd2-7b0e-4e2b-8ec3-8908e6e541f7</WebstoreId>
</Shipment>
<Order>
<OrderNumber>AMAZON ORDER NUMBER</OrderNumber>
<OrderItems>
<OrderItem>
<ItemSKU>AMAZON ITEM ID</ItemSKU>
<Quantity>1<Quantity>
</OrderItem>
<OrderItem>
<ItemSKU>ANOTHER AMAZON ITEM ID</ItemSKU>
<Quantity>3<Quantity>
</OrderItem>
</OrderItems>
</Order>
</ShipTransaction>
</ShipRequest>Request - Banyan
Required fields: ShipmentQuoteId, ShipmentLoadId, ServiceAsString
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<Carrier>31</Carrier>
<ShipmentLoadId>21964115</ShipmentLoadId>
<ShipmentQuoteId>202737790</ShipmentQuoteId>
<ServiceAsString>Old Dominion Frt Line</ServiceAsString>
<Package>
<PackageActualWeight>1</PackageActualWeight>
<PackagingType>02</PackagingType>
<PkgLength>4</PkgLength>
<PkgWidth>4</PkgWidth>
<PkgHeight>4</PkgHeight>
<FreightServiceType>LTL</FreightServiceType>
<FreightEquipmentType>VT_STANDARD</FreightEquipmentType>
<FreightCommodity>
<ItemFreightClass>CLASS_050</ItemFreightClass>
<ItemDescription>ShipRush Socks 2x Pack</ItemDescription>
<ItemPackaging>BAG</ItemPackaging>
<ItemWeight>1</ItemWeight>
<ItemPieces>6</ItemPieces>
</FreightCommodity>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Doe</FirstName>
<Company>Acme Roofing</Company>
<Address1>3400 S Carrollton Ave</Address1>
<Address2 />
<City>New Orleans</City>
<State>LA</State>
<Country>US</Country>
<PostalCode>70118</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
<ShipperAddress>
<Address>
<FirstName>Mark White</FirstName>
<Company>Cat Food Unlimited</Company>
<Address1>233 S WACKER DR</Address1>
<Address2 />
<City>Chicago</City>
<State>IL</State>
<Country>US</Country>
<PostalCode>60606</PostalCode>
<Phone>206-400-0000</Phone>
</Address>
</ShipperAddress>
</Shipment>
</ShipTransaction>
</ShipRequest>Request - Banyan - Via QuoteId
This option allows you to ship/dispatch a Banyan shipment with minimal information. This will result in minimal information saved to the ShipRush, so if you expect your users to rely on My.Shiprush UI for shipment information, use the longer version above.
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<IsTest>1</IsTest>
<Carrier>31</Carrier>
<ShipmentLoadId>21964115</ShipmentLoadId>
<BOLNumber>DES1906500006</BOLNumber> <!-- Optional: If included will show up as tracking number in SR UI -->
<ShipmentQuoteId>202737790</ShipmentQuoteId>
<ShipViaQuoteId>true</ShipViaQuoteId>
</Shipment>
</ShipTransaction>
</ShipRequest>Response - Banyan
<ShipResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<ShipTransaction>
<Shipment>
<Documents>
<PaperDocument>
<PaperDocumentId>34751feb-1e36-4223-be58-a56800aeb4e1</PaperDocumentId>
<DocumentType>ShippingLabel</DocumentType>
<LabelFormat>PNG</LabelFormat>
<Width>1700</Width>
<Height>2200</Height>
<DPI>200</DPI>
<ContentMimeEncoded>iVBORw0KGgo...</ContentMimeEncoded>
</PaperDocument>
</Documents>
<ShippingAccount>
<ShippingAccountId>4137853b-46eb-4cd1-9436-a4e600cdd94b</ShippingAccountId>
<AccountNumber>USPS.com</AccountNumber>
<PostageBalance>0</PostageBalance>
...
</ShippingAccount>
<ShipmentId>74cc53fc-24a8-4fe6-8bd3-a56800b26022</ShipmentId>
<ShippingCharges>5.75</ShippingCharges>
<InsuranceRate>0</InsuranceRate>
<ClearPathRate>0</ClearPathRate>
<CarrierRate>5.75</CarrierRate>
<InsuranceCharges>0</InsuranceCharges>
<FreightCharges>0</FreightCharges>
<OtherCharges>0</OtherCharges>
<ShipmentNumber>420981229405501699320067259499</ShipmentNumber>
...
<Package>
<PackageTrackingNumber>420981229405501699320067259499</PackageTrackingNumber>
...
</Package>
</Shipment>
</ShipTransaction>
</ShipResponse>Request - PreferredLabelFormat
Optionally PreferredLabelFormat element can be added to the ShipRequest. If used like in example below, all printable documents will be converted from PDF to PNG format. Other ShipSettings are in this case overriden at the and of the call, although carrier specific processing is still performed as before. Only conversion from PDF to PNG is supported at this time.
<?xml version="1.0" encoding="utf-8"?>
<ShipRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
...
</ShipTransaction>
<ShipSettings>
...
</ShipSettings>
<PreferredLabelFormat>PNG</PreferredLabelFormat>
</ShipRequest>Void
http://my.shiprush.com/shipmentservice.svc/shipment/void
By default "void" will
Cancel shipping label and request a postage refund
Mark shipment and order as "cancelled"
If you want void to fully revert shipment and order to "Ready To Ship" status set "DoNotMarkVoidedOrderAsCancelled" to "true".
Request
<?xml version="1.0" encoding="utf-8"?>
<VoidRequest>
<DoNotMarkVoidedOrderAsCancelled>true</DoNotMarkVoidedOrderAsCancelled>
<ShipTransaction>
<Shipment>
<ShipmentId>74cc53fc-24a8-4fe6-8bd3-a56800b26022</ShipmentId>
</Shipment>
</ShipTransaction>
</VoidRequest>Response
<VoidResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
</VoidResponse>
<VoidResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages>
<ShippingMessage>
<Severity>ERROR</Severity>
<Text>Shipment '74cc53fc-24a8-4fe6-8bd3-a56800b26022' is not shipped or already voided.</Text>
</ShippingMessage>
</Messages>
<IsSuccess>false</IsSuccess>
</VoidResponse>ValidateAddress
http://my.shiprush.com/shipmentservice.svc/shipment/validateaddress
Request
<?xml version="1.0" encoding="utf-8"?>
<ValidateAddressRequest>
<ShipTransaction>
<Shipment>
<Carrier>3</Carrier>
<DeliveryAddress>
<Address>
<FirstName>JOHN DOE</FirstName>
<Company>ACME ROOFING</Company>
<Address1>10022 63RD AVE S</Address1>
<Address2 />
<City>SEATTLE</City>
<State>WA</State>
<Country>US</Country>
<StateAsString>WA</StateAsString>
<CountryAsString>US</CountryAsString>
<PostalCode>98178-2305</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
</Shipment>
</ShipTransaction>
</ValidateAddressRequest>Response
<ValidateAddressResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Messages/>
<IsSuccess>true</IsSuccess>
<ShipTransaction>
<Shipment>
<Residential>1</Residential>
<DeliveryAddress>
<Address>
<LastName>JOHN DOE</LastName>
<Company>ACME ROOFING</Company>
<Address1>10022 63RD AVE S</Address1>
<City>SEATTLE</City>
<State>WA</State>
<Country>US</Country>
<StateAsString>WA</StateAsString>
<CountryAsString>US</CountryAsString>
<PostalCode>98178-2305</PostalCode>
<Phone>206-300-0000</Phone>
</Address>
</DeliveryAddress>
...
</Shipment>
</ShipTransaction>
</ValidateAddressResponse>AddFunds
http://my.shiprush.com/accountservice.svc/shippingaccount/addfunds
This call adds money to shipping account using default payment method. For CreditCard payment method funds will be available right away, for ACH/eCheck it will take few days for funds to be available. If shipping account was created using CreateShippingAccountComplete call - there will be no default payment method associated with the shipping account and this call will fail. At the moment the only place to add/remove/manage payment methods is My.ShipRush.com.
Request
<?xml version="1.0" encoding="utf-8"?>
<AddFundsRequest>
<Amount>50</Amount>
<ShippingAccountId>33cc53fc-24a8-4fe6-8bd3-a56800b26022</ShippingAccountId>
</AddFundsRequest>Response
<GetShippingAccountResponse>
<ShippingAccountId>33dcc97c-64fa-4970-bf9e-a67200af7317</ShippingAccountId>
<CarrierType>1</CarrierType>
<PostageBalance>150.18</PostageBalance>
<AccountNumber>SR44XXXXX</AccountNumber>
....
</ValidateAddressResponse>EOD (End of Day)
https://<url>/shipmentservice.svc/shipment/eod
This call closes the shipping day for a given shipping account.
Call returns a document if
Carrier supports EOD documents (FedEx, for example, never returns EOD documents)
Shipments have been made since last EOD
EOD aka: Scan Form (USPS), Manifest, etc.
USPS Scan forms do not work with Test Shipments. Which means, USPS End of Day will never work for labels created via sandbox endpoints
USPS EOD can only be tested on production, with live labels.
Request
<EODRequest>
<ShippingAccountId>33dcc97c-64fa-4970-bf9e-a67200af7317</ShippingAccountId>
</EODRequest>Response
<EODResponse>
<Messages></Messages>
<IsSuccess>true</IsSuccess>
<Documents>
<PaperDocumentId>34751feb-1e44-4223-be58-a56800aeb4e1</PaperDocumentId>
<DocumentType>SCANForm</DocumentType>
<LabelFormat>PNG</LabelFormat>
<Width>1700</Width>
<Height>2200</Height>
<DPI>200</DPI>
<ContentMimeEncoded>iVBORw0KGgo...</ContentMimeEncoded>
</Documents>
</EODResponse>Tracking
https://<url>/shipmentservice.svc/shipment/tracking
This call returns tracking information for a given shipping account.
Request
<?xml version="1.0" encoding="utf-8"?>
<TrackingRequest>
<ShipmentId>75E0C3D0-20B2-432A-9B29-AAEE011A83D8</ShipmentId>
</TrackingRequest>Response
<TrackingResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipmentId>75E0C3D0-20B2-432A-9B29-AAEE011A83D8</ShipmentId>
<TrackingInfo>
<TrackingInfo>
<PackageId>9dfc8e94-1617-4dba-9736-aaee011a83d9</PackageId>
<Carrier>1</Carrier>
<EventDateTimeLocal>2019-10-18T11:17:00</EventDateTimeLocal>
<TrackingStatus>LabelPrinted</TrackingStatus>
<TrackingLocation> 28804 US</TrackingLocation>
<TrackingNotes>Shipment information sent to FedEx</TrackingNotes>
</TrackingInfo>
<TrackingInfo>
<PackageId>9dfc8e94-1617-4dba-9736-aaee011a83d9</PackageId>
<Carrier>1</Carrier>
<EventDateTimeLocal>2019-10-20T14:18:00</EventDateTimeLocal>
<TrackingStatus>InTransit</TrackingStatus>
<TrackingLocation>EDISON NJ 08817 US</TrackingLocation>
<TrackingNotes>Arrived at FedEx location</TrackingNotes>
</TrackingInfo>
<TrackingInfo>
<PackageId>9dfc8e94-1617-4dba-9736-aaee011a83d9</PackageId>
<Carrier>1</Carrier>
<EventDateTimeLocal>2019-10-21T00:30:00</EventDateTimeLocal>
<TrackingStatus>InTransit</TrackingStatus>
<TrackingLocation>LONG ISLAND CITY NY 11101 US</TrackingLocation>
<TrackingNotes>At local FedEx facility</TrackingNotes>
</TrackingInfo>
<TrackingInfo>
<PackageId>9dfc8e94-1617-4dba-9736-aaee011a83d9</PackageId>
<Carrier>1</Carrier>
<EventDateTimeLocal>2019-10-21T01:15:00</EventDateTimeLocal>
<TrackingStatus>OutForDelivery</TrackingStatus>
<TrackingLocation>LONG ISLAND CITY NY 11101 US</TrackingLocation>
<TrackingNotes>On FedEx vehicle for delivery</TrackingNotes>
</TrackingInfo>
<TrackingInfo>
<PackageId>9dfc8e94-1617-4dba-9736-aaee011a83d9</PackageId>
<Carrier>1</Carrier>
<EventDateTimeLocal>2019-10-21T09:51:26</EventDateTimeLocal>
<TrackingStatus>Delivered</TrackingStatus>
<TrackingLocation>Long Island City NY 11101 US</TrackingLocation>
<TrackingNotes>Delivered</TrackingNotes>
</TrackingInfo>
</TrackingInfo>
</TrackingResponse>FAQs
How to Do a COD Shipment?
There are COD-related fields available on the package level.
Example snippet:
<AddFreightChargesToCOD>1</AddFreightChargesToCOD>
<CODAmount>10</CODAmount>
<CODCurrency>USD</CODCurrency>
<CODType>COD</CODType>
<CODFunds>00</CODFunds>