API documentation

Overview

The Shipper REST API connects your online shop, ERP or logistics software to your Shipper account. It lets you:

• get offers from several carriers in a single request;
• order the shipment from the offer you choose;
• download labels, the invoice and customs documents;
• track and cancel a shipment.

You open the access from your Shipper account. Your developer builds the integration in a test environment, the sandbox, then you go live.

Get started in 4 steps

1. Invite your developer to the sandbox

   In Account details › API, section “Development environment access”, enter your developer's e-mail address. They receive an invitation, choose a password and sign in to the sandbox with that address.

   The sandbox is entirely fictitious: your developer has no access to your account or your data. To remove their access, delete their address; to hand the sandbox to someone else, replace it. The person removed is notified by e-mail.

2. Develop and test

   In the sandbox, your developer enters a billing address, adds credits (simulated payments), then creates a key in Account details › API. They can then request quotes and order test shipments without anything being shipped.

3. Request production access

   When the integration is ready, open Account details › API in your Shipper account and click the production request button. A ticket follows the request; allow 48 to 72 hours. You are notified as soon as access is active.

4. Create your production keys

   Once access is active, the add key button generates a key and its password. The password is shown only once: write it down, otherwise you will have to create a new key.

   Each key can be restricted to a list of IP addresses, which you can change later. You can create as many keys as you need, for example one per system.

Servers

Keys belong to one environment: a sandbox key does not work in production.

Authentication

Every request authenticates with HTTP Basic using the key and its password: an Authorization: Basic header followed by key:password encoded in base64. HTTP tools do this for you:

curl -u "YOUR_KEY:YOUR_PASSWORD" \
     -H "Accept: application/json" \
     https://api.sandbox.shipper.ch/quotation/12345

A key restricted to IP addresses rejects requests from anywhere else. Keep the password on your server: never in a web page's JavaScript or in an application installed at your customers' premises.

Shipment workflow

1. Quote: send the sender, recipient and packages to POST /quotation. The response gives a quotationId and the carriers' offers.
2. Choice: pick the offer that suits you (its quoteId).
3. Order: POST /order with the quoteId, the pickup date and, if the shipment goes through customs, the customs items.
4. Documents: GET /order/{orderId}/document/{type} returns the file: labels, invoice or customs.
5. Tracking: GET /order/{orderId}/tracking.

Routes

• POST /quotation Create a quotation (offers from several carriers)
• GET /quotation/{quotationId} Read a quotation
• POST /order Order a shipment from an offer
• GET /order/{orderId} Read an order
• GET /order/{orderId}/tracking Track the shipment
• GET /order/{orderId}/document/{type} Download a document
• GET /order/{orderId}/cancel Cancel the order

Fields, allowed values and full examples: API reference.

Requests and responses

POST requests send a JSON body (Content-Type: application/json); GET requests pass their parameters in the URL. Ask for JSON in return with Accept: application/json.

Except for a downloaded document (the body is then the file), the response is a JSON object that always contains header: error and endpoint, plus errorCode, errorMessage and errorField on error. The HTTP status code tells you the result:

EU product identifiers

For a shipment from Switzerland (or another non-EU country) to a private person in the EU, the EU requires two identifiers per customs item:

• merchantProductId: your own item reference (SKU);
• manufacturerProductId: the manufacturer's reference (model or part number). If you make the product yourself, repeat your item reference.

standardProductId (GTIN or EAN code) is optional. The recipient is a private person when quotation.to.isCompany is false.

In your customer area

Quotes requested through the API appear in your quotes, with sender, recipient and the rates offered. Shipments ordered through the API appear in your shipments, marked “API”, and a filter separates them from shipments made on the website.

Help

A question about the integration? Open a ticket from your account or write to us at Email: our technical team will answer.