Service Lookup

Listing a Carrier’s Available Services — Non-Visual Shipping API Quick Start Guide

What is Service Lookup?

The Service Lookup call takes one carrier and returns the shipping services that carrier advertises for a specific ShipRush account. You POST a GetServiceTypesRequest containing a <CarrierType>, and get back a list of service codes. Because the response is scoped by the account’s shipping token, it reflects exactly what that account can use for that carrier.

The endpoint is POST /shipmentservice.svc/shipment/lookup/services, part of the Non-Visual Shipping API (the XML shipping API).

Works with Carrier Lookup: Run lookup/carriers first to get the account’s carrier codes, then call lookup/services once per carrier to enumerate its services. See the Carrier Lookup Quick Start Guide for that step.

When to Use This

• You have a carrier and need the list of services it offers before rating or shipping.

• You are populating a service picker in your UI and want the live, per-account list.

• You want to validate a specific service (e.g. USPS Priority = U02) is available before using it.

• You need the input for the next calls — lookup/packaging and shipment/rate both take a service type.

Prerequisites

• A Shipping Token and a Developer Token for the account (see the Carrier Lookup guide, Step 1, for how to obtain these).

• A carrier code to look up — typically one returned by lookup/carriers.

• An HTTP client able to POST XML (any language; a C# example is included).

Step 1 — Know the Endpoint

Method & path: POST /shipmentservice.svc/shipment/lookup/services

Base URL (prepend to the path above):

• Production: https://api.my.shiprush.com

• Sandbox: https://sandbox.api.my.shiprush.com

Required and optional HTTP headers (identical to the other shipping-API lookups):

Header	Required	Value
X-SHIPRUSH-SHIPPING-TOKEN	Yes	Your account's shipping token. Scopes the response to that account.
X-SHIPRUSH-DEVELOPER-TOKEN	Yes	Your developer/application token, issued to your developer account.
Content-Type	Yes	application/xml (or text/xml)
Accept-Encoding	Yes	gzip, deflate — your client must accept compressed responses.
User-Agent	Yes	Identifies your app clearly, e.g. Acme-OrderSystem. Spaces → hyphen/underscore.
X-SHIPRUSH-VERSION	No	Desired XML response version, e.g. 84114. Omit to use the server default.
User-Agent-Version	No	Full build of your app, e.g. 1.0.0.1234.

Step 2 — Build and POST the Request

The body is a GetServiceTypesRequest with a single required child, <CarrierType>, using a carrier code (e.g. 17 = ShipRush USPS, 1 = FedEx). The account’s shipping token still scopes the result.

Request body (services for carrier 17, ShipRush USPS):

<?xml version="1.0" encoding="utf-8"?>
<GetServiceTypesRequest>
<CarrierType>17</CarrierType>
</GetServiceTypesRequest>

Step 3 — Read the Response

A valid call returns HTTP 200. Service codes come back inside <ServiceTypes> as a list of <TUPSService> elements. Inspect <IsSuccess> and <Messages> to confirm success.

Element naming: The list element is <TUPSService> for every carrier — it is a legacy name, not USPS-specific. The codes inside it are carrier-specific: querying FedEx returns FedEx codes, UPS returns UPS codes, and so on.

Sample response (carrier 17, domestic services):

<GetServiceTypesResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<IsSuccess>true</IsSuccess>
<Messages />
<ServiceTypes>
<TUPSService>U01</TUPSService> <!-- USPS First Class -->
<TUPSService>U02</TUPSService> <!-- USPS Priority -->
<TUPSService>U03</TUPSService> <!-- USPS Media Mail -->
<TUPSService>U05</TUPSService> <!-- USPS Express -->
<TUPSService>U07</TUPSService> <!-- USPS Library Mail -->
<TUPSService>USPSGNDADV</TUPSService> <!-- USPS Ground Advantage -->
</ServiceTypes>
</GetServiceTypesResponse>

Step 4 — Common USPS Service Codes

The codes a carrier can return vary by carrier and by account. The table below lists the documented USPS services for carrier 17 (ShipRush USPS). For other carriers, treat the lookup response itself as authoritative.

Service Code	Service	Scope
U01	USPS First Class	Domestic
U02	USPS Priority	Domestic
U03	USPS Media Mail	Domestic
U05	USPS Express	Domestic
U07	USPS Library Mail	Domestic
USPSGNDADV	USPS Ground Advantage	Domestic
UI01	USPS Intl First Class	International
UI02	USPS Intl Priority	International
UI05	USPS Intl Express	International

USPS Ground Advantage: Ground Advantage uses the wire code USPSGNDADV, not a Uxx code. It replaced U04 (Retail Ground / Parcel Post) and U08 (Parcel Select) when USPS retired those in 2023 — migrate old integrations to USPSGNDADV. U06 (Bound Printed Matter) is obsolete and is not returned. For international on carrier 17, expect UI01, UI02, and UI05.

Step 5 — Handle Errors

The Non-Visual Shipping API uses a two-level result model:

• HTTP 200 — structurally accepted. Read <IsSuccess> / <Messages> in the body for the real outcome.

• HTTP 401 — authentication failed (bad or missing token).

• HTTP 500 — a structural or authentication failure; the body is a JSON error object, not XML.

• A carrier not configured on the account may return an empty <ServiceTypes> list — handle that as “no services available.”

C# / .NET Example

Requests the services for one carrier, prints the HTTP status, then lists the returned service codes. Swap in your tokens and change the carrier code / base URL as needed.

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using System.Xml.Linq;

class ShipRushServiceLookup
{
// Sandbox base URL. For production use https://api.my.shiprush.com
const string BaseUrl = "https://sandbox.api.my.shiprush.com";
const string ShippingToken = "YOUR-SHIPPING-TOKEN-GUID";
const string DeveloperToken = "YOUR-DEVELOPER-TOKEN";

static async Task Main()
{
// Ask for one carrier's services. 17 = ShipRush USPS.
const int carrierType = 17;
string requestXml =
"<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
$"<GetServiceTypesRequest><CarrierType>{carrierType}</CarrierType>" +
"</GetServiceTypesRequest>";

using var client = new HttpClient();
var req = new HttpRequestMessage(
HttpMethod.Post,
$"{BaseUrl}/shipmentservice.svc/shipment/lookup/services");

req.Headers.Add("X-SHIPRUSH-SHIPPING-TOKEN", ShippingToken);
req.Headers.Add("X-SHIPRUSH-DEVELOPER-TOKEN", DeveloperToken);
req.Headers.Add("Accept-Encoding", "gzip, deflate");
req.Headers.UserAgent.ParseAdd("Acme-OrderSystem/1.0");
req.Content = new StringContent(requestXml, Encoding.UTF8, "application/xml");

var resp = await client.SendAsync(req);
var body = await resp.Content.ReadAsStringAsync();
Console.WriteLine($"HTTP {(int)resp.StatusCode}");

// Service codes come back as <TUPSService> elements inside <ServiceTypes>.
var doc = XDocument.Parse(body);
foreach (var s in doc.Descendants("TUPSService"))
Console.WriteLine($"Service code: {s.Value}");
}
}

Prefer a wrapper? The ShipRush .NET SDK ships proxy assemblies (ShipRush.SDK.Proxies.dll, ShipRush.BusinessLayer.dll) you can reference instead of hand-rolling the HTTP call.

Quick Reference

The Call at a Glance

• Endpoint: POST /shipmentservice.svc/shipment/lookup/services

• Request body: <GetServiceTypesRequest><CarrierType>17</CarrierType></GetServiceTypesRequest>

• Response: <GetServiceTypesResponse><ServiceTypes><TUPSService>…</TUPSService></ServiceTypes></GetServiceTypesResponse>

• Auth: X-SHIPRUSH-SHIPPING-TOKEN + X-SHIPRUSH-DEVELOPER-TOKEN headers.

Next Steps

• Feed a returned service into POST /shipmentservice.svc/shipment/lookup/packaging (carrier + service) to list packaging options.

• Then call shipment/rate or shipment/ship with the carrier, service, and packaging you selected.