Shippo
Test Connection
Checks a Shippo API token live against Shippo before it is saved. Nothing is persisted. Use it to validate a token before creating the integration instance.
Create Integration Instance
Connects a Shippo account. The token is verified live with Shippo first — an invalid token creates nothing. Only one Shippo connection is allowed per account.
Get Integration Instance
Returns a Shippo integration instance: its name, masked API token, test/live mode, settings (auto_push_orders, record_shipping_costs, label_file_type plus the available label_file_type_options, sync_start_date, is_automatic_sync_enabled) and health/sync state (auth_error_at and is_healthy, last_synced_at, last_webhook_at, webhook_subscribed_at, webhook_events_registered).
Update Integration Instance
Updates the connection name, API token and/or any settings. Only the keys present in the body are applied, so partial payloads never wipe other values. PATCH is also accepted on this path. Settings may also be sent nested under an integration_settings object; they are flattened before validation.
Delete Integration Instance
Disconnects Shippo. The disconnect is recorded immediately and the teardown runs in the background: the webhook registrations at Shippo are removed first, then the instance and its synced data are deleted.
Update Integration Settings
Saves integration settings only (no name or token). Partial payloads are merged over the current settings — only keys present in the body change. Settings may also be sent nested under an integration_settings object.
Test Saved Connection
Checks the instance's saved API token live against Shippo. A rejected token flags the instance as unhealthy (auth_error_at is set); a successful check clears that flag.
Sync Tracking
Queues a background reconcile that polls Shippo for the latest tracking status of in-flight labels and completes any label purchases or refunds still pending at Shippo. Webhooks normally keep tracking current; use this to catch up after missed deliveries.
Get Dashboard Metrics
Returns live summary metrics for the instance:
List Activity
Paginated audit feed of actions across the Shippo integration: connect/disconnect, connection failures, settings changes, syncs triggered and completed, warehouse and service-level mapping changes, order pushes and recalls, label purchases, refunds and cost reversals.
List Orders
Paginated Shippo orders for the instance. An order is created at Shippo for each fulfillment order pushed to it (or imported by the order sync). Each row includes the recipient address, totals, status (raw order_status plus a readable order_status_label), the label count (transactions_count), tracking_numbers (tracking numbers of the order's live labels — bought and not refunded), a 'View in Shippo' link (external_url) and cross-link fields to the originating fulfillment order and sales order.
Sync Orders
Queues a background import of orders from Shippo for the chosen window.
Get Order
Returns one Shippo order with its recipient, totals, status, label count, tracking_numbers (live labels) and cross-links to the fulfillment order and sales order.
Get Raw Order Payload
Fetches the order live from Shippo and returns Shippo's payload verbatim under data.product, with fetched_at (ISO-8601, UTC) set to the time of the fetch.
List Order Activity
Paginated activity log for a single Shippo order (submitted, recalled, label purchased, …), newest first.
List Labels
Paginated Shippo labels (transactions) for the instance — one row per parcel. Each list row also carries parcel_count: how many labels were bought from the same rate (the M in 'parcel N of M', with parcel_index giving N), counted across all pages. Includes labels bought through SKU.io and labels bought directly in Shippo (imported by the label sync). Each label carries its status (raw status plus status_label), carrier and service level, postage (rate_amount/rate_currency and the local-currency amount), tracking (number, status, substatus, carrier tracking URL, eta, delivered_at), the label format, download_url (streams the stored label document; null until purchased), refund state (refund_status, refund_requested_at), is_live (purchased and not refunded) and is_refundable (live and not yet scanned by the carrier), plus cross-links to the fulfillment order, sales order, sales order fulfillment and Shippo order.
Sync Labels
Queues a background import of labels (transactions) from Shippo for the chosen window, including labels bought directly in Shippo.
Get Label
Returns one Shippo label. Each label carries its status (raw status plus status_label), carrier and service level, postage (rate_amount/rate_currency and the local-currency amount), tracking (number, status, substatus, carrier tracking URL, eta, delivered_at), the label format, download_url (streams the stored label document; null until purchased), refund state (refund_status, refund_requested_at), is_live (purchased and not refunded) and is_refundable (live and not yet scanned by the carrier), plus cross-links to the fulfillment order, sales order, sales order fulfillment and Shippo order.
Get Raw Label Payload
Fetches the transaction live from Shippo and returns Shippo's payload verbatim under data.product, with fetched_at (ISO-8601, UTC) set to the time of the fetch. Note label_url is Shippo's short-lived signed link — use Download Label for a stable copy.
Download Label
Streams the label document inline for printing or re-printing. It never buys postage again. The document is served from SKU.io's stored copy; if no copy is stored yet it is fetched from Shippo and stored first.
Refund Label
Requests a void/refund of a purchased label at Shippo. Refunds are asynchronous: the label is returned in its refund-pending state (status REFUNDPENDING, refund_status QUEUED or PENDING) and resolves to REFUNDED or REFUNDREJECTED later via webhook or the tracking reconcile — live refunds can take up to 14 days. Test-mode refunds usually resolve immediately.
List Carrier Accounts
Returns every carrier account connected in Shippo (Shippo-managed master accounts and the merchant's own carrier accounts), active accounts first, each with service_levels_count and mapped_service_levels_count. The response also includes shipping_methods: the SKU.io shipping methods (id, name, full_name) available as mapping targets for service levels.
Sync Carriers
Queues a background refresh of carrier accounts and their service levels from Shippo. Existing service-level mappings are preserved.
List Service Levels
Paginated carrier service levels (e.g. UPS Ground, USPS Priority Mail) with their carrier account and the SKU.io shipping method each is mapped to. Rates returned for a mapped service level carry its shipping_method_id.
Auto-Match Service Levels
Maps every unmapped service level whose name matches an SKU.io shipping method name. Already-mapped service levels are never changed.
Bulk Map Service Levels
Applies one SKU.io shipping method to many service levels at once, or clears their mapping.
Export Service Level Mappings
Downloads every service level and its mapping as a CSV file that can be edited and re-imported with Import Service Level Mappings.
Import Service Level Mappings
Applies a mapping CSV (the format produced by Export Service Level Mappings). Send as multipart/form-data.
Update Service Level
Enables/disables a service level and/or sets its mapped SKU.io shipping method. Only keys present in the body change.
List Warehouse Mappings
Returns every active (non-archived) SKU.io warehouse, sorted by name, with its address and its Shippo sender-address mapping (mapping is null when unmapped). Row id equals the warehouse id.
Save Warehouse Mapping
Creates or replaces the Shippo sender (ship-from) address for a warehouse. The address is registered at Shippo and reused for rate quotes and label purchases. US addresses are validated by Shippo; its messages come back as warnings and never block saving.
Unmap Warehouse
Removes a warehouse's Shippo sender-address mapping. Fulfillment orders from that warehouse can no longer buy Shippo labels until it is mapped again.
Toggle Warehouse Mapping
Flips the enabled flag of a warehouse's sender-address mapping. A disabled mapping cannot be used to buy labels.
Get Webhook Subscription
Returns the webhook registration status, checked live against Shippo's webhook list. The status lists each event SKU.io subscribes to (transaction_created, transaction_updated, track_updated) with whether it is registered at Shippo, its Shippo webhook id, active and is_test flags; plus webhook_url (this instance's inbound URL), subscribed (all events registered), subscribed_at, last_webhook_received_at, failed_event_count and signature_verification (whether HMAC signatures are verified for this instance). If Shippo cannot be reached, registration falls back to the locally stored ids and error carries the reason.
Subscribe Webhooks
Registers (or re-registers) this instance's webhook URL at Shippo — one registration per subscribed event. Webhooks are registered automatically on connect; use this to repair a missing registration. Runs synchronously.
Unsubscribe Webhooks
Removes this instance's webhook registrations at Shippo. Tracking and label updates then only arrive through scheduled syncs. Runs synchronously.
List Webhook Events
Paginated log of inbound webhook events received from Shippo. processing_state is processed, failed (error is set) or pending. signature_valid is null when no HMAC secret is configured for the instance. The raw body is returned by Get Raw Webhook Event Payload.
Get Webhook Event
Returns one inbound webhook event: type, Shippo object id, tracking number, signature and source-IP details, processing_state, error and attempts. The raw body is returned by Get Raw Webhook Event Payload.
Get Raw Webhook Event Payload
Returns the webhook body exactly as Shippo delivered it, under data.product, with fetched_at set to when the event was received (ISO-8601, UTC). This is the stored copy; Shippo is not called.
Retry Webhook Event
Clears the event's processed/error state and queues it for reprocessing in the background. Use it after fixing the cause of a failed event.
Get Label Eligibility
Reports whether a fulfillment order can buy a Shippo label and returns everything needed to request rates. The Shippo instance and the ship-from address are resolved from the fulfillment order (its Shippo instance and its warehouse's sender-address mapping) — they are never passed by the client. Requires a token with the orders read/write scope.
Get Shipping Rates
Creates a Shippo shipment for the given parcels (from the warehouse's sender address to the fulfillment order's ship-to address) and returns its rates. The Shippo instance and the ship-from address are resolved from the fulfillment order (its Shippo instance and its warehouse's sender-address mapping) — they are never passed by the client. Requires a token with the orders read/write scope.
Purchase Label
Buys the label(s) for a rate returned by Get Shipping Rates. The Shippo instance and the ship-from address are resolved from the fulfillment order (its Shippo instance and its warehouse's sender-address mapping) — they are never passed by the client. Requires a token with the orders read/write scope. When the label is bought a sales order fulfillment is created with the tracking number and, if record_shipping_costs is on, the postage cost.
List Fulfillment Order Labels
Returns every Shippo label bought for the fulfillment order, in any status (including refunded and failed), one row per parcel. Each label carries its status (raw status plus status_label), carrier and service level, postage (rate_amount/rate_currency and the local-currency amount), tracking (number, status, substatus, carrier tracking URL, eta, delivered_at), the label format, download_url (streams the stored label document; null until purchased), refund state (refund_status, refund_requested_at), is_live (purchased and not refunded) and is_refundable (live and not yet scanned by the carrier), plus cross-links to the fulfillment order, sales order, sales order fulfillment and Shippo order.
Receive Webhook
The endpoint Shippo calls to deliver events for one Shippo integration instance. SKU.io registers this URL at Shippo automatically (see Webhook Subscription) — you do not call it yourself except to test. It is not under /api and takes no Bearer token: the opaque webhook_token path segment (wh_ followed by letters and digits, shown as webhook_url in Get Webhook Subscription) identifies and authenticates the instance.