Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Shippo to Fondoo

local_post_officeLive4 min readUpdated

Shippo is a shipping platform for comparing carrier rates and buying postage labels. Connecting it lets your AI agent quote shipping rates for an order, buy a label once you approve it, and look up tracking. Every label purchase spends money on your Shippo account, so Fondoo always asks you first.

What Fondoo can do with it

ActionFondoo operationShippo callRisk
Quote ratesget_shipping_rates({connectionId, shipment})POST /shipments/ (synchronous), which returns the available ratesread
Buy a labelbuy_shipping_label({connectionId, shipment})POST /transactions/ (synchronous), which purchases the label for a chosen ratemoney
Track a parcelget_shipment_tracking({connectionId, tracking:{carrier, trackingNumber}})GET /tracks/{carrier}/{tracking_number}read

You pass Shippo's own request fields in shipment. For rates, that is the from and to addresses and the parcels. For a label, it is the rate's object_id from the quote, plus options such as the label file type. See Shippo's API reference.

Approvals:

  • buy_shipping_label is a money action. When an agent calls it, Fondoo returns pending_approval with a link, and nothing is bought until you approve.
  • Over MCP, this approval step applies even to your own signed-in session.
  • Rates and tracking are reads and need no approval.
  • Agents need Fondoo's commerce:read or commerce:write scope.

Before you start

  • A Shippo account. On the API Starter plan, Shippo lists $0 a month with 30 free labels a month, then 7 cents per label. Tracking calls are listed at 2 cents each and rating calls at 1 cent each, in addition to postage (Shippo API pricing). Prices can change; check that page.
  • A default payment method in Shippo before buying live labels: credit card, debit card or US bank account. Prepaid cards are not accepted (payment methods).
  • Carriers. You can use Shippo's own carrier accounts, or connect your own carrier accounts in Shippo first.
  • A Fondoo site to attach the connection to.

Step by step: get your credentials

Shippo has test keys (shippo_test_...) and live keys (shippo_live_...). Start with a test key.

  1. Sign in at https://portal.goshippo.com .
  2. Open API Configuration → Developer keys (authentication).
  3. Choose Test keys and select Create new test key. Later, use Live keys → Create new live key for real labels.
  4. Copy the key right away. Shippo shows it only once.

Shippo keys have no permission scopes. A key can do anything your account can, so keep it private and use a dedicated key for Fondoo.

Fondoo sends the key as Authorization: ShippoToken <key> with SHIPPO-API-VERSION: 2018-02-08, the version Shippo lists as latest and default. The version header overrides your account setting, so Fondoo's requests behave the same even if your account uses a different version.

Connect it in Fondoo

In the dashboard:

  1. Open Connections. Under Available → Shipping, find Shippo.
  2. Click Use a key, then Open secure key entry.
  3. Paste the key into apiKey and click Save connection securely. The link lasts 15 minutes and works once.
  4. Click Check connection on the Shippo card.

By asking your agent. For example:

"Connect Shippo with a test key and quote shipping for order 1042."

The agent calls add_connection_key({provider:"shippo", siteId}) without fields and gives you the secure link. Keys placed in fields trigger a chat-log warning, so avoid that. The agent can also send a signed 15-minute guide link with connect_service({provider:"shippo", siteId}). After you save the key, it runs test_connection({connectionId}).

REST: POST https://api.getfondoo.com/v1/ops/add_connection_key with Authorization: Bearer <your Fondoo key> and {"provider":"shippo","siteId":"<site UUID>"}.

Test that it works

  1. test_connection calls GET /carrier_accounts/. Status connected means the key is accepted. Other actions stay "unknown" until used.
  2. With a test key, ask for rates on a sample shipment. Then approve one test label. Test labels are free and marked "SAMPLE - DO NOT MAIL" (testing).
  3. For tracking in test mode, Shippo documents the carrier shippo with numbers such as SHIPPO_TRANSIT or SHIPPO_DELIVERED. Shippo's docs show these with its POST tracking call, so the GET form Fondoo uses may behave differently. Tracking numbers from test labels do not get updates.
  4. When you are ready, rotate to a live key with rotate_connection_key.

Troubleshooting

  • Status invalid or "Provider request failed (401)". The key is missing, deleted or expired. Create a new one.
  • Test and live mixed up. Carrier accounts connected while using a test key only work in test mode. Reconnect them with the live key. A test key never buys real postage.
  • The label purchase fails. Check that you have a default payment method and that the rate you passed is still valid. Rates can expire, so quote again.
  • "Provider request failed (429)". Shippo limits are per minute and differ by object and mode. For example, live shipment creation is 500 per minute and test is 50 (rate limits). Fondoo also budgets about 60 actions per minute per connection.
  • "Connector request failed... Do not blindly retry". A label request may or may not have gone through. Check your Shippo dashboard before trying again, so you do not buy twice.

Limits, data and security

  • What Fondoo stores: the encrypted key, connection status, last test and last use. list_connections shows the key as [redacted]. Rates, labels and tracking results are returned to the caller.
  • Rotate: rotate_connection_key({connectionId}) without fields gives a secure paste link. Use it to switch from test to live or to replace a key.
  • Disconnect: delete_connection({connectionId}) removes the key from Fondoo. Agents need your approval. Also delete the key in Shippo's Developer keys page.