{"openapi":"3.1.0","info":{"title":"Shippo (BYOK) API","version":"0.1.0","description":"Shippo (BYOK) lets an AI assistant read your own Shippo data through the Shippo API with a key you supply (API token (live or test)). Read-only: 8 tools (list_shipments, get_shipment, list_labels, get_label, list_orders, get_order, list_refunds, list_carrier_accounts). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-shippo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shippo/docs"},"termsOfService":"https://connectorbay.com/byok-shippo/terms"},"servers":[{"url":"https://byok-shippo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shippo/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_shipments":{"post":{"operationId":"list_shipments","summary":"List shipments (addresses, status, shipment date, messages) without their rates, newest first. Free to read. Use for \"Wh","description":"List shipments (addresses, status, shipment date, messages) without their rates, newest first. Free to read. Use for \"What shipments did I create recently in Shippo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"results":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 100).","title":"Results"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer's next field holds the URL of the following page, or null.","title":"Page"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time, for example 2026-02-01T00:00:00Z.","title":"Created Before"}},"title":"list_shipmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_shipment":{"post":{"operationId":"get_shipment","summary":"Get one shipment by id with addresses, parcels, status, messages and the rates that were returned for it. Use for \"Show ","description":"Get one shipment by id with addresses, parcels, status, messages and the rates that were returned for it. Use for \"Show me Shippo shipment adcfdddf8ec64b84ad22772bce3ea37a\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shipment_id":{"description":"Shipment object_id from list_shipments.","maxLength":64,"title":"Shipment Id","type":"string"}},"required":["shipment_id"],"title":"get_shipmentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_labels":{"post":{"operationId":"list_labels","summary":"List shipping labels (Shippo calls them transactions) with tracking number, tracking status, label URL and rate id. Use ","description":"List shipping labels (Shippo calls them transactions) with tracking number, tracking status, label URL and rate id. Use for \"Which Shippo shipping labels have been delivered\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"object_status":{"anyOf":[{"enum":["WAITING","QUEUED","SUCCESS","ERROR","REFUNDED","REFUNDPENDING","REFUNDREJECTED"],"type":"string"},{"type":"null"}],"default":null,"description":"Label status: WAITING, QUEUED, SUCCESS, ERROR, REFUNDED, REFUNDPENDING or REFUNDREJECTED.","title":"Object Status"},"tracking_status":{"anyOf":[{"enum":["UNKNOWN","PRE_TRANSIT","TRANSIT","DELIVERED","RETURNED","FAILURE"],"type":"string"},{"type":"null"}],"default":null,"description":"Tracking status: UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED or FAILURE.","title":"Tracking Status"},"rate_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only labels bought with this rate id.","title":"Rate Id"},"results":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 100).","title":"Results"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer's next field holds the URL of the following page, or null.","title":"Page"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time, for example 2026-02-01T00:00:00Z.","title":"Created Before"}},"title":"list_labelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_label":{"post":{"operationId":"get_label","summary":"Get one shipping label (transaction) by id with tracking number, tracking status, ETA, label URL and messages. Use for \"","description":"Get one shipping label (transaction) by id with tracking number, tracking status, ETA, label URL and messages. Use for \"Show me Shippo label 915d8b8cab7b4b8c8a3b2a1f5c1c1c1c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"transaction_id":{"description":"Transaction object_id from list_labels.","maxLength":64,"title":"Transaction Id","type":"string"}},"required":["transaction_id"],"title":"get_labelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_orders":{"post":{"operationId":"list_orders","summary":"List orders imported into Shippo from a shop or marketplace, with status, totals, shipping address and line items. Use f","description":"List orders imported into Shippo from a shop or marketplace, with status, totals, shipping address and line items. Use for \"What paid orders are waiting in Shippo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shop_app":{"anyOf":[{"enum":["Amazon","Bigcommerce","CSV_Import","eBay","ePages","Etsy","Godaddy","Magento","Shippo","Shopify","Spreecommerce","StripeRelay","Walmart","Weebly","WooCommerce"],"type":"string"},{"type":"null"}],"default":null,"description":"Only orders from this source.","title":"Shop App"},"results":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 100).","title":"Results"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1. The answer's next field holds the URL of the following page, or null.","title":"Page"}},"title":"list_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one Shippo order by id with status, totals, addresses, line items and linked labels. Use for \"Show me Shippo order 4","description":"Get one Shippo order by id with status, totals, addresses, line items and linked labels. Use for \"Show me Shippo order 4f2bc588e4e5475b9aaa6b4c1c4e4b9e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order object_id from list_orders.","maxLength":64,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_refunds":{"post":{"operationId":"list_refunds","summary":"List label refund requests with their status (QUEUED, PENDING, SUCCESS or ERROR) and the label they belong to. Use for \"","description":"List label refund requests with their status (QUEUED, PENDING, SUCCESS or ERROR) and the label they belong to. Use for \"Have my Shippo label refunds gone through\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_refundsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_carrier_accounts":{"post":{"operationId":"list_carrier_accounts","summary":"List the carrier accounts connected to Shippo (USPS, UPS, FedEx and so on) with active and test flags and their service ","description":"List the carrier accounts connected to Shippo (USPS, UPS, FedEx and so on) with active and test flags and their service levels. Use for \"Which carrier accounts are connected to my Shippo account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"carrier":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only accounts of this carrier code, for example 'usps' or 'ups'.","title":"Carrier"},"service_levels":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each account's service levels.","title":"Service Levels"},"results":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many records per page (1 to 100).","title":"Results"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_carrier_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}