GoShippo¶

GoShippo multi-carrier rate quotes, labels, and tracking. Shippo is a rate aggregator: one API call returns live rates from every carrier the merchant has connected in their Shippo account (UPS, FedEx, USPS, DHL, and others). The extension also pushes orders to Shippo on placement and polls Shippo for tracking updates on a schedule. Use it when you manage carriers and labels through a Shippo account rather than direct carrier integrations.

What It Provides¶

• Live multi-carrier rate quotes — registers a ShippingCalculatorStrategy named goshippo that creates a Shippo shipment (POST /shipments) and maps the returned rates (carrier, service level, amount, estimated days) to checkout rate options. Package weights are sent in ounces (converted from pounds); if no packages are supplied, a default 10×8×6 in / 16 oz parcel is used.
• Order sync — an order.placed event handler (priority 80) starts ShippoOrderSyncWorkflow when auto_sync_orders is enabled and an API token is configured. The workflow pushes the order to Shippo via POST /orders, mapping line items, addresses, totals, and order status (fulfilled → SHIPPED, partially_fulfilled → PARTIALLY_FULFILLED, cancelled → CANCELLED, refunded → RETURNED, everything else → PAID).
• Tracking poll — ShippoTrackingPollWorkflow runs on Temporal schedule vectis-goshippo-tracking-poll every 15 minutes. It scans local shipments whose carrier matches %shippo% / %goshippo% and checks each box's tracking number via GET /tracks/{carrier}/{tracking_number}, mapping Shippo statuses to shipment box statuses (PRE_TRANSIT → label_created, TRANSIT → in_transit, DELIVERED → delivered, RETURNED → returned, FAILURE → exception).
• Label purchase — ShippoShippingStrategy.purchase_label buys a prepaid PDF label for the cheapest rate on a fresh shipment (POST /transactions), the shape the RMA return-label service looks for in label-capable carriers.
• GraphQL admin operations — query shippoSyncStatus; mutations testShippoConnection (lists the carrier accounts connected in Shippo), syncOrderToShippo (manual single-order push), triggerShippoTrackingPoll (manual poll), and validateShippoAddress (Shippo Addresses v2 validation).

Setup¶

1. Create (or edit) a shipping provider with carrier code goshippo under Settings > Shipping > Providers & Methods (the extension's manifest settings page is Fulfillment, /settings/fulfillment).
2. Enter your Shippo API token and the ship-from origin fields (postal code, country, state, city).
3. Click Test Connection on the Fulfillment settings page (/settings/fulfillment, GoShippo tab) — the testShippoConnection mutation validates the token you enter there by listing the carrier accounts connected in your Shippo account.
4. Optionally set auto_sync_orders in the provider config to push orders to Shippo on placement (the GoShippo panel on the providers page does not expose this flag as a form field — set it on the provider's config directly).
5. For the order-sync and tracking-poll activities (scheduled or manually triggered), set SHIPPO_API_TOKEN in the Temporal worker environment — the worker activities build their client from that variable and fail without it (see Operational Notes).

See Shipping & Fulfillment for how carrier strategies, zones, and methods fit together.

Configuration Reference¶

This extension declares no manifest config_schema. All settings live in the shipping provider's config (the ShippingProvider.config column for the provider whose carrier code is goshippo). The GoShippo panel under Settings > Shipping > Providers & Methods exposes the token and origin fields; the two boolean flags have no form field there. The keys read by the extension:

For local development the extension falls back to environment variables when no enabled provider row carries an api_token: SHIPPO_API_TOKEN, SHIPPO_ORIGIN_POSTAL, SHIPPO_ORIGIN_COUNTRY, SHIPPO_ORIGIN_STATE, SHIPPO_ORIGIN_CITY (plus SHIPPO_AUTO_SYNC and SHIPPO_TRACKING_POLL for the status flags).

Permissions¶

• fulfillment.goshippo.manage

Manifest permissions are upserted at boot; assigning them to roles is currently a manual step.

Operational Notes¶

• Worker credentials come from the environment — the Temporal activities (sync_order_to_shippo, poll_shippo_tracking) build their Shippo client from SHIPPO_API_TOKEN only and raise SHIPPO_API_TOKEN must be set when it is missing. They do not read the shipping provider config, so order sync and tracking polls (scheduled or manually triggered — both run as Temporal activities) require the env var on the worker even when the token is configured in the admin.
• Schedule runs regardless of the flag — the vectis-goshippo-tracking-poll schedule is registered unconditionally every 15 minutes; the tracking_poll_enabled key is only surfaced through the shippoSyncStatus query, it does not gate the poll.
• Rate limiting — the client retries up to 3 times on HTTP 429, honouring the Retry-After header (default backoff 2 s × attempt), then raises.
• API version pinned — requests send SHIPPO-API-VERSION: 2018-02-08 with Authorization: ShippoToken <token> against https://api.goshippo.com.
• Label purchase is implemented on the delegate class, not the registered proxy — the strategy instance registered for checkout (_ShippoProxyStrategy) exposes rate calculation only; purchase_label and supports_label_purchase live on ShippoShippingStrategy and are not currently reachable through the strategy registry.
• Order weights — line-item weights come from each order line's product snapshot weight_oz value; lines without a snapshot sync with zero weight.