Overview Delivery Quotes Booking References Return Codes Test Harness
This API is used to lookup a list of shipping rates for parcels and pallets. The results are ordered from the cheapest delivery option to other specialist delivery services that are available.
<lookup>
<header>
<apikey>testapikey</apikey>
<key>publickey</key>
<token>e8beca07478a92507b4f91bc36638bdd09ad691f</token>
<uniqueid>64664664645125484</uniqueid>
</header>
<shipment>
<type>PARCEL</type>
<collection>
<town>Wethersfield</town>
<postcode>CM7 4AY</postcode>
<countrycode>UK_M</countrycode>
</collection>
<destination>
<town>Heathfield</town>
<postcode>TN21 0AW</postcode>
<countrycode>UK_M</countrycode>
</destination>
<parcels>
<parcel>
<weight>1</weight>
<length>82</length>
<width>6</width>
<height>82</height>
</parcel>
</parcels>
</shipment>
</lookup>
The Schema for this API can be downloaded from here.
| Element | Req | Description | |
|---|---|---|---|
<header> | Yes | Holder for header element. | |
<apikey> | Yes | This is the APIKey as provided by ParcelBroker. | |
<key> | Yes | This is your Public Key that use use to create the <token> value. | |
<token> | Yes | SHA1 hash of "SharedSecret_PublicKey". | |
<uniqueid> | Yes | A unique ID for every successful request. Duplicate requests with the same ID will be rejected. | |
</header> | |||
<shipment> | Yes | Holder for shipment element. | |
<type> | Yes | Possible values are DOCUMENT, PARCEL, PALLET. | |
<collection> | Yes | Holder for collection address. | |
<town> | Yes | The collection town. | |
<postcode> | Yes | The collection postcode. | |
<countrycode> | Yes | The collection country code. Please see here for possible values. | |
</collection> | |||
<destination> | Yes | Holder for destination address. | |
<town> | Yes | The destination town. | |
<postcode> | Yes | The destination postcode. | |
<countrycode> | Yes | The destination country code. Please see here for possible values. | |
</destination> | |||
<parcels> | Yes | Holder for parcels. | |
<parcel> | Yes | Holder for a parcel (Can have more than 1). | |
<weight> | Yes | The weight in KG. | |
<length> | Yes | The length in CM. | |
<width> | Yes | The width in CM. | |
<height> | Yes | The height in CM. | |
</parcel> | |||
</parcels> | |||
</shipment> |
<response>
<header>
<status>Success</status>
</header>
<shipment>
<type>PARCEL</type>
<collection>
<town>Wethersfield</town>
<postcode>CM7 4AY</postcode>
<countrycode>UK_M</countrycode>
</collection>
<destination>
<town>Heathfield</town>
<postcode>TN21 0AW</postcode>
<countrycode>UK_M</countrycode>
</destination>
<parcels>
<parcel>
<weight>1</weight>
<length>82</length>
<width>6</width>
<height>82</height>
</parcel>
</parcels>
</shipment>
<services>
<service>
<rate_id>51</rate_id>
<hash>a9bf04b84ae31084b80148ffd0a15ddec0c80963</hash>
<name>UK Premium</name>
<cutoff>14:00:00</cutoff>
<printer>true</printer>
<business_only>false</business_only>
<type>ROAD</type>
<messages>
<message>Carry on strike, disruption from 11th June 2013 for 2 days.</message>
</messages>
<customs>false</customs>
<price>6.99</price>
<vatrate>20.00</vatrate>
<surcharge>0.00</surcharge>
<net>6.99</net>
<vat>1.40</vat>
<total>8.39</total>
</service>
<service>
<id>55</id>
<hash>ec7ef94d05e09a234b1d648a17d633af9e4f982f</hash>
<name>Business Standard UK</name>
<cutoff>12:00:00</cutoff>
<printer>true</printer>
<business_only>true</business_only>
<type>ROAD</type>
<price>9.99</price>
<vatrate>20.00</vatrate>
<surcharge>0.00</surcharge>
<net>9.99</net>
<vat>2.00</vat>
<total>11.99</total>
</service>
</services>
</response>
The Success response status returns a list of services. Each service is comprised of the following:
| Element | Description |
|---|---|
<service> | Holder for service element. |
<id> | This is the ID of this service. |
<hash> | Hash identifying this service. |
<name> | This is the name of the service. |
<cutoff> | This is the cutoff time for the collection postcode. |
<printer> | Flag to indicate whether a printer is required. |
<business_only> | Flag to indicate that this service can only be delivered to a business premises. |
<type> | Indicates how the service operates. Possible values are ROAD, AIR, OTHER. |
<messages> | Any service messages for this carrier, can contain 0 or more message elements. |
<customs> | Indicates whether this carrier/country requires any customs paperwork. Valid values are "required", "optional", "false". Required indicates that the carrier requires paperwork when calling the booking API, optional means that the country requires paperwork but does not need to be sent with the booking API. |
<price> | The users base net price. |
<vatrate> | The VAT rate for this service. |
<surcharge> | A list of surcharges for this service, there can be multiple of these elements. |
<net> | The users net price including surcharges. |
<vat> | The VAT charged. |
<total> | The total price to the user including all charges and VAT. |
</service> |
Along with the common response codes this API has the following:
| Code | Reason |
|---|---|
| 155 | Missing address data information. |
| 160 | Incorrect or missing parcel data. |
| 180 | No services returned. |
This section gives you some data that you can use for testing purposes.
Some carriers have a surcharge for remote areas. You can use the following data to return services that have remote areas applied:
Delivery Address: UK - Scottish Highlands & Islands (UK_SH), Town: KIRKWALL, Postcde: KW151NF
Delivery Address: Italy (IT), Town: Badia al Pino, Postcode: 52041
Some carriers have a surcharge for customs clearance.
Delivery Address: Andorra (AD), Town: Principat d'Andorra, Postcde: AD-500
Delivery Address: Switzerland (CH), Town: Zürich, Postcde: 8003