Shiptheory
Test Shiptheory Connection
Validates a Shiptheory account email + password without saving a connection. The credentials are exchanged for a short-lived Shiptheory token and a delivery-services probe is run, so you can confirm the login is correct before creating an instance.
Create Shiptheory Instance
Creates and connects a new Shiptheory integration instance for the current account, then returns it together with a live dashboard summary. The initial delivery-services, orders and shipments syncs are started in the background, plus the package-sizes download unless sync_package_sizes is false.
Get Shiptheory Instance
Returns a single Shiptheory integration instance together with a live dashboard summary: per-status order counts, KPI totals (awaiting booking, booked last 7 days, failed, ignored), entity counts, per-entity last-sync timestamps, and the connection state. The stored password is never returned — only the account email and a has_password flag.
Update Shiptheory Instance
Patches any subset of name, credentials, and settings on the instance. Every field is optional and applied per section — omitted keys keep their current values; an empty password keeps the stored one. Returns the updated instance with a refreshed dashboard summary.
Delete Shiptheory Instance
Disconnects and removes a Shiptheory integration instance. The teardown of cached orders, shipments, delivery services, package sizes, and mappings runs in the background; this endpoint records the disconnect and returns immediately.
Test Saved Shiptheory Connection
Validates the credentials stored on a saved Shiptheory instance (no body) and records the outcome so the connection panel reflects it.
Get Shiptheory Dashboard Metrics
Returns just the live dashboard summary for a Shiptheory instance — the lightweight refresh for the dashboard widget without the full instance settings payload. The 'data' object contains per-status order counts, KPI totals (awaiting_booking_count, booked_last_7_days_count, failed_count, ignored_count, methods_on_rules_engine_count), entity counts, per-entity last-sync timestamps, the connection state, is_connected, and a polling_notice (Shiptheory is polling-only — there are no webhooks).
List Shiptheory Orders
Paginated, filterable list of Shiptheory orders for the integration instance. Each row carries the provider identifiers (reference, status, tracking_number), carrier and delivery fields, price/cost, a deep link to the Shiptheory portal (external_url), and cross-link fields to the originating fulfillment order and its parent sales order.
Get Shiptheory Order
Returns the full details for a single Shiptheory order scoped to the integration instance. Includes the provider identifiers, carrier and delivery fields, price/cost, the provider messages log (info/success/error entries), the portal deep link (external_url), and cross-links to the originating fulfillment order and parent sales order.
Get Shiptheory Order Raw JSON
Fetches the live provider payload for the order on demand (a real-time call to Shiptheory keyed on the order's reference) and returns it wrapped as { data: { product: {...} }, fetched_at }. Useful for inspecting the raw shipment record exactly as Shiptheory returns it.
Get Shiptheory Order Label
Proxies the shipment's shipping label from Shiptheory and streams it back as a PDF file download (Content-Type: application/pdf). The label is fetched live and never stored — it is re-downloadable at any time once the order is Complete.
Sync Shiptheory Orders
Starts a background sweep that reconciles the current state of existing Shiptheory orders for this instance (Shiptheory has no bulk order list, so each non-terminal order is refreshed by its reference). The response returns the tracked job id, which you can poll for progress.
List Shiptheory Shipments
Paginated, filterable list of Shiptheory shipments (booked consignments) for the integration instance. Each row carries the booked-side data (carrier, service, tracking, carrier cost, parcel count, booked_at) plus cross-links to the parent Shiptheory order and the sales order fulfillment the shipment realized. One consignment carries one tracking number even when it spans multiple parcels.
Get Shiptheory Shipment
Returns the full details for a single Shiptheory shipment scoped to the integration instance. Includes carrier, service, tracking, carrier cost, parcel count, booked_at, the parent order context and portal deep link, and the cross-link to the sales order fulfillment. When include_json=1 is supplied, the stored provider payload is included as json_object.
Get Shiptheory Shipment Raw JSON
Fetches the live provider payload for the shipment on demand, resolved through its parent order's reference (Shiptheory has no shipment-level endpoint), and returns it wrapped as { data: { product: {...} }, fetched_at }.
Get Shiptheory Shipment Label
Proxies the shipping label from Shiptheory (resolved via the parent order) and streams it back as a PDF file download (Content-Type: application/pdf). The label is fetched live and never stored.
Sync Shiptheory Shipments
Starts a background reconcile that backfills carrier costs and mints any missed shipment rows for recently completed Shiptheory orders on this instance. Carrier cost data can lag booking, so this re-polls the affected orders and updates in place. The response returns the tracked job id, which you can poll for progress.
List Shiptheory Delivery Services
Paginated, filterable list of the Shiptheory delivery services synced for the instance, each with its optional mapping to a SKU shipping method. An unmapped service (sku_shipping_method_id = null) is a valid default — Shiptheory's rules engine picks the carrier at booking.
Sync Shiptheory Delivery Services
Starts a background discovery of the instance's Shiptheory delivery services (the enabled carriers/services on the account) and upserts them into the mirror without disturbing existing shipping-method mappings. The response returns the tracked job id, which you can poll for progress.
Auto-Match Shiptheory Delivery Services
Auto-links still-unmapped delivery services to the SKU shipping method whose name matches after normalizing case, whitespace and punctuation. Never overwrites an existing (manual) mapping. Returns a summary of how many were matched and how many were left on the rules engine.
Bulk Map Shiptheory Delivery Services
Applies one SKU shipping method (or null to clear back to the rules-engine default) to every selected delivery service in a single call.
Export Shiptheory Delivery Service Mappings CSV
Streams the current delivery-service to SKU shipping-method mappings as a re-importable CSV file (Content-Type: text/csv). The columns are service_id, carrier_name, service_name, enabled, sku_shipping_method_id, sku_shipping_method_name. Blank shipping-method columns clear the mapping on re-import.
Import Shiptheory Delivery Service Mappings CSV
Applies a CSV of mapping rows. Rows are keyed by Shiptheory's own service_id; the SKU method resolves by sku_shipping_method_id (authoritative) or sku_shipping_method_name (fallback); both blank clears the mapping back to the rules engine. The response summarizes rows created, updated, removed, and any per-line errors.
Map Shiptheory Delivery Service
Sets (or clears) a single delivery service's SKU shipping-method mapping. Clearing returns the service to the rules-engine default.
List Shiptheory Package Sizes
Paginated, filterable list of the Shiptheory package sizes synced for the instance. These feed the instance's default package size setting and the dispatch payload.
Sync Shiptheory Package Sizes
Starts a background discovery of the instance's Shiptheory package sizes and upserts them into the mirror. The response returns the tracked job id, which you can poll for progress.
List Shiptheory Warehouse Mappings
Returns every SKU warehouse zipped with its Shiptheory mapping on this instance. A null mapping (enabled=false, mapping_id=null) means the warehouse is not routed to Shiptheory. Each row carries sender_address — the warehouse's own address exactly as it is sent to Shiptheory as the shipment sender, or null when the address is incomplete (Shiptheory then uses the account's default Shipping Location) — plus sender_address_missing, the address fields still needed (address line 1, city, postcode, country). Each row also carries a cross-link to the SKU warehouse, the warehouse_type, and routable — true only for your own (direct) or 3PL warehouses, the only ones that can ship through Shiptheory. There is no provider-side location catalog to sync — the list reflects your SKU warehouses.
Map Shiptheory Warehouse
Sets or updates a SKU warehouse's mapping on this instance (idempotent upsert). enabled=true also points the SKU warehouse's fulfillments at this Shiptheory instance, so dispatched fulfillment orders are submitted to Shiptheory; enabled=false clears the routing and returns the warehouse to manual fulfillment if this instance owned it. Shipments from a routed warehouse use the warehouse's own address as the sender; nothing address-related is set here.
List Shiptheory Activity Log
Paginated, filterable audit trail of Shiptheory integration actions for the instance — connect, settings update, sync, booked, and mapping events. Each entry carries the event name, a human description, the acting user (causer, plus causer_name — null for system entries), any recorded properties, and timestamps.