{"openapi":"3.1.0","info":{"title":"ShipBob (BYOK) API","version":"0.1.0","description":"ShipBob (BYOK) lets an AI assistant read your own ShipBob data through the ShipBob API with a key you supply (personal access token (PAT)). Read-only: 9 tools (get_channels, get_orders, get_order, get_products, get_inventory_items, get_return_orders, get_receiving_orders, get_locations, get_invoices). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-shipbob.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shipbob/docs"},"termsOfService":"https://connectorbay.com/byok-shipbob/terms"},"servers":[{"url":"https://byok-shipbob.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shipbob/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/get_channels":{"post":{"operationId":"get_channels","summary":"List the channels (API applications and store connections) of the account with id, name, owning application and granted ","description":"List the channels (API applications and store connections) of the account with id, name, owning application and granted scopes. Use for \"Which ShipBob channels does my token belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"records_per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page (default 50).","title":"Records Per Page"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next link.","title":"Cursor"}},"title":"get_channelsArguments","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_orders":{"post":{"operationId":"get_orders","summary":"List orders with order number, reference id, status, type, dates, shipping method and total price. Filter by date, refer","description":"List orders with order number, reference id, status, type, dates, shipping method and total price. Filter by date, reference ids or tracking state; pages by number. Use for \"Which ShipBob orders were placed this week and have no tracking yet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (default 50; this connector allows up to 250).","title":"Limit"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders inserted later than this ISO 8601 date-time, for example 2026-01-01T00:00:00Z.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders inserted earlier than this ISO 8601 date-time.","title":"End Date"},"sort_order":{"anyOf":[{"enum":["Newest","Oldest"],"type":"string"},{"type":"null"}],"default":null,"description":"Newest (default) or Oldest first.","title":"Sort Order"},"has_tracking":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for orders with a tracking number, false for those without.","title":"Has Tracking"},"reference_ids":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated reference ids to filter by.","title":"Reference Ids"}},"title":"get_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 order by id with status, type, dates, tags, total price, products (SKU and quantity) and its shipments with trac","description":"Get one order by id with status, type, dates, tags, total price, products (SKU and quantity) and its shipments with tracking details. Use for \"Show ShipBob order 4455667 with its shipments\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"ShipBob order id (a number) as returned by get_orders.","title":"Order Id","type":"integer"}},"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/get_products":{"post":{"operationId":"get_products","summary":"List products with name, type, creation and update times, taxonomy and variants (SKU, status). Search by name or SKU; up","description":"List products with name, type, creation and update times, taxonomy and variants (SKU, status). Search by name or SKU; up to 250 per page. Use for \"Which ShipBob products match 'mug'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search products by name, SKU, inventory id or product id.","title":"Search"},"sku":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only products matching this SKU.","title":"Sku"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Products per page (1 to 250).","title":"Page Size"},"sort_by":{"anyOf":[{"enum":["Id","Name","Category","TotalOnHandQty"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: Id, Name, Category or TotalOnHandQty.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Order"}},"title":"get_productsArguments","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_inventory_items":{"post":{"operationId":"get_inventory_items","summary":"List inventory items with id, name, SKU, barcode, dimensions, weight and active and bundle flags; search by name or SKU.","description":"List inventory items with id, name, SKU, barcode, dimensions, weight and active and bundle flags; search by name or SKU. Use for \"Which inventory items do I have in ShipBob\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search inventory by name or SKU.","title":"Search By"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active items, false for only inactive ones.","title":"Is Active"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page.","title":"Page Size"}},"title":"get_inventory_itemsArguments","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_return_orders":{"post":{"operationId":"get_return_orders","summary":"List return orders with status, type, dates, original shipment, tracking number and fulfillment center. Filter by status","description":"List return orders with status, type, dates, original shipment, tracking number and fulfillment center. Filter by status or dates. Use for \"Which ShipBob returns are still awaiting arrival\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses, for example 'AwaitingArrival,Arrived'.","title":"Status"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only returns created on or after this ISO 8601 date.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only returns created on or before this ISO 8601 date.","title":"End Date"},"cursor":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number to fetch (starting at 1).","title":"Cursor"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Records per page.","title":"Limit"},"sort_order":{"anyOf":[{"enum":["Asc","Desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Desc (default, newest first) or Asc.","title":"Sort Order"}},"title":"get_return_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_receiving_orders":{"post":{"operationId":"get_receiving_orders","summary":"List warehouse receiving orders (inbound shipments) with status, purchase order number, expected arrival, package type a","description":"List warehouse receiving orders (inbound shipments) with status, purchase order number, expected arrival, package type and fulfillment center. Use for \"Which inbound ShipBob receiving orders are still awaiting arrival\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (default 50; this connector allows up to 250).","title":"Limit"},"statuses":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses such as Awaiting, Processing, Completed, Cancelled, Arrived.","title":"Statuses"},"insert_start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created on or after this ISO 8601 date.","title":"Insert Start Date"},"insert_end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created on or before this ISO 8601 date.","title":"Insert End Date"}},"title":"get_receiving_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_locations":{"post":{"operationId":"get_locations","summary":"List ShipBob fulfillment center locations with name, region, time zone and active, receiving and shipping flags. Use for","description":"List ShipBob fulfillment center locations with name, region, time zone and active, receiving and shipping flags. Use for \"Which ShipBob fulfillment centers can I ship to or receive at\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_inactive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include inactive locations.","title":"Include Inactive"},"receiving_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only locations enabled for receiving.","title":"Receiving Enabled"}},"title":"get_locationsArguments","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_invoices":{"post":{"operationId":"get_invoices","summary":"List invoices with type, date, amount, currency and running balance for a date range (default last month); up to 1000 pe","description":"List invoices with type, date, amount, currency and running balance for a date range (default last month); up to 1000 per page. Use for \"What ShipBob invoices did I get last month and for how much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Invoice date from, ISO 8601 (default: one month ago).","title":"From Date"},"to_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Invoice date to, ISO 8601 (default: today).","title":"To Date"},"invoice_types":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated types: Shipping, WarehouseStorage, Inbound Fee, Return, AdditionalFee, Credits.","title":"Invoice Types"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Invoices per page (1 to 1000, default 100).","title":"Page Size"},"sort_order":{"anyOf":[{"enum":["Ascending","Descending"],"type":"string"},{"type":"null"}],"default":null,"description":"Ascending or Descending (default) by invoice date.","title":"Sort Order"}},"title":"get_invoicesArguments","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}}}}