Quickstart

Five calls from nothing to a shipment with a label. Set two variables first:

export TMS=https://vibe.holiostage.com/api/tms/v1/organizations/$ORG/tms
export AUTH="Authorization: Bearer $TOKEN"

1. Find the product

curl -s -H "$AUTH" "$TMS/catalogue/carriers"
curl -s -H "$AUTH" "$TMS/catalogue/products?carrierId=bring"

A product lists its rules (maximum weight and measurements, whether a pickup point is required) and its additional services.

2. Price it

curl -s -H "$AUTH" -H 'Content-Type: application/json' "$TMS/internal-quotes" -d @quote.json

The quote uses the price lists of your own carrier agreement. The agreementId is one of your organization's carrier agreements.

3. Check, then book

curl -s -H "$AUTH" -H 'Content-Type: application/json' "$TMS/internal-shipments/checks" -d @booking.json
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
     -H "Idempotency-Key: order-1001-1" "$TMS/internal-shipments" -d @booking.json

The check runs the product's rules without booking. The booking answers the shipment with its id and tracking numbers.

4. Get the label

curl -s -H "$AUTH" "$TMS/internal-shipments/$SHIPMENT/label"

The answer is a link valid for ten minutes. Fetch the file from it right away; don't store the link.

5. Follow it

curl -s -H "$AUTH" "$TMS/internal-shipments/$SHIPMENT/tracking"

Every source's events, oldest first: the booking, the carrier's API and webhooks, reports and invoices.

Each call is in the reference with its full request and answer, and can be run in the console.

Authentication

The TMS API takes a Holio access token: Authorization: Bearer <token>. The token says which organization it is for and which permissions it carries. The organization in the path must be that organization; an organization sent any other way is never trusted.

A system calling on its own behalf

Use a confidential client with a service account and the OAuth 2.0 client-credentials grant, asking for the scope organization:<organization id>:

curl -s https://vibe-auth.holiostage.com/realms/holio/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET \
  -d scope=organization:$ORG

Holio registers the client and the permissions it may use. Ask your Holio contact for one; tell us which organization and which of the calls in this reference you need.

A person signed in to Holio

An application acting for a person signs them in with Holio (OpenID Connect, authorization code with PKCE) and asks for the same organization: scope. The person's roles in the organization decide what the token may do.

Permissions

Tokens live for minutes. Ask for a new one when the old one expires rather than storing it.

Idempotency

A booking, a pickup, an order shipment and a return each take a header Idempotency-Key, matching [A-Za-z0-9._:-]{1,100}. Choose it from your own data, such as your order number and a counter, so a retry after a crash sends the same key.

• The booking is recorded under its key before the carrier is asked.
• The same key with the same body answers the first booking (200, marked as a replay). It never books twice.
• When the organization's booking policy asks for approval, the booking answers 202 with the approval and nothing goes to the carrier until it is approved; the same key answers the same approval meanwhile.
• A carrier that couldn't be reached at all answers 503 and nothing was booked.
• The same key with another body is refused with 409 tms_idempotency_key_reused.
• A carrier that refuses books nothing (422 tms_upstream_rejected); the same key may book again once you have fixed the request.
• A carrier that gave no clear answer leaves the booking booking_unknown (409 tms_booking_unknown). It is never sent again by itself: read the shipment list before booking with a new key.

Reads, checks and quotes take no key: they change nothing and are always safe to repeat.

Errors

Every refusal is a problem document (application/problem+json, RFC 9457). Act on status and code; the English detail is for logs, not for your users.

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "A booking with this Idempotency-Key got no clear answer",
  "code": "tms_booking_unknown"
}

Codes are a contract: new ones are added, none is ever renamed.

Checkout rates

A web shop asks POST /checkout/rates with the cart and the delivery address, and shows what comes back. The delivery methods, their prices and rules are set up by the merchant in Holio, not in the request.

• Each rate has a durable code (such as bring-3584, or with a pickup point appended). Keep it on the order: shipping the order later names the method by it.
• priceMinor is in the checkout's currency, VAT included. A request in another currency gets no rates; nothing is converted.
• Methods that don't apply are listed in skipped with a reason, for the merchant's own test page. Don't show them to the customer.
• When the checkout's pickup mode is selector, a rate stands for the method and the customer picks the point with GET /checkout/pickup-points?code=.

A carrier that can't be asked in time (four seconds by default) gets the method's fallback price instead of no rate.

Shipping web shop orders

Once a customer has paid, ship the order with POST /order-shipments. Weights, customs and the method come from the order lines and the merchant's settings in Holio, not from free text a browser typed.

1. Preview what will be booked, if a person confirms it.
2. Ship with an Idempotency-Key made from your order, for example myshop:1001:1.
3. Read the order's shipments with GET /order-shipments?externalOrderId=, and print again with reprint.
4. Book a return with POST /order-returns.

Shopify shops use Holio's own Shopify app, which makes these calls. Build directly on them for other platforms.