{"openapi":"3.1.0","info":{"title":"Returnship API","version":"0.1.0","description":"A fully local return-shipping cost estimator and keep/return/donate/resell decision framework: illustrative general cost ranges by size/weight/distance tier, a worth-it calculator netting refund against restocking fee and shipping cost, a broader decision comparison, free-return and packaging tips, an international-returns orientation, and a glossary. No real carrier's live rates are used.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://returnship.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/returnship/docs"},"termsOfService":"https://connectorbay.com/returnship/terms"},"servers":[{"url":"https://returnship.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/returnship/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/estimate_return_cost":{"post":{"operationId":"estimate_return_cost","summary":"An illustrative, general cost range for shipping a return, based on package size category, weight and","description":"An illustrative, general cost range for shipping a return, based on package size category, weight and\n    distance tier — a ballpark for the keep-vs-return decision, not a live quote from any real carrier. Use for\n    \"roughly what would it cost to ship back a medium box across the country\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size_category":{"description":"'envelope', 'small_box', 'medium_box', 'large_box', or 'oversized'.","examples":["medium_box"],"title":"Size Category","type":"string"},"weight_lb":{"description":"Approximate weight in pounds.","examples":[8],"exclusiveMinimum":0,"title":"Weight Lb","type":"number"},"distance_tier":{"description":"'local', 'regional', 'cross_country', or 'international'.","examples":["cross_country"],"title":"Distance Tier","type":"string"}},"required":["size_category","weight_lb","distance_tier"],"title":"estimate_return_costArguments","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/size_category_guide":{"post":{"operationId":"size_category_guide","summary":"The package size categories used by estimate_return_cost, with example contents and typical weight range","description":"The package size categories used by estimate_return_cost, with example contents and typical weight range\n    for each. Use for \"what counts as a medium box\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"size_category_guideArguments","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/distance_tier_guide":{"post":{"operationId":"distance_tier_guide","summary":"The distance tiers used by estimate_return_cost, with what each roughly covers. Use for \"what's the","description":"The distance tiers used by estimate_return_cost, with what each roughly covers. Use for \"what's the\n    difference between regional and cross-country for shipping\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"distance_tier_guideArguments","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/worth_it_decision":{"post":{"operationId":"worth_it_decision","summary":"Nets a refund against any restocking fee and your own return-shipping cost (if the seller doesn't cover it)","description":"Nets a refund against any restocking fee and your own return-shipping cost (if the seller doesn't cover it)\n    to show what you'd actually net back, with a verdict on whether returning is worth it on the numbers. Use for\n    \"is it worth returning this $40 item if shipping costs $12 and there's a 15% restocking fee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_value":{"description":"What the item is worth to you (roughly its price).","examples":[40],"minimum":0,"title":"Item Value","type":"number"},"estimated_return_cost":{"description":"What return shipping would cost you.","examples":[12],"minimum":0,"title":"Estimated Return Cost","type":"number"},"refund_amount":{"description":"The refund you'd receive before any fees.","examples":[40],"minimum":0,"title":"Refund Amount","type":"number"},"restocking_fee_pct":{"default":0,"description":"A restocking fee percentage, if any.","maximum":100,"minimum":0,"title":"Restocking Fee Pct","type":"number"},"seller_pays_return_shipping":{"default":false,"description":"True if the seller provides a prepaid/free return label.","title":"Seller Pays Return Shipping","type":"boolean"}},"required":["item_value","estimated_return_cost","refund_amount"],"title":"worth_it_decisionArguments","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/donate_vs_sell_vs_return":{"post":{"operationId":"donate_vs_sell_vs_return","summary":"Compares the net value of returning it, keeping it, donating it, or reselling it yourself, side by side, and","description":"Compares the net value of returning it, keeping it, donating it, or reselling it yourself, side by side, and\n    names the best option by net value. Use for \"should I return this or just donate it\", \"return vs. sell it\n    myself, which nets more\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item_value":{"description":"What the item is worth to you.","examples":[40],"minimum":0,"title":"Item Value","type":"number"},"return_cost":{"description":"Cost to ship it back.","examples":[12],"minimum":0,"title":"Return Cost","type":"number"},"refund_amount":{"description":"Refund you'd get back.","examples":[40],"minimum":0,"title":"Refund Amount","type":"number"},"resale_estimate":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"What you think you could net reselling it yourself, after fees.","title":"Resale Estimate"},"restocking_fee_pct":{"default":0,"description":"A restocking fee percentage, if any.","maximum":100,"minimum":0,"title":"Restocking Fee Pct","type":"number"}},"required":["item_value","return_cost","refund_amount"],"title":"donate_vs_sell_vs_returnArguments","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/free_return_check_tips":{"post":{"operationId":"free_return_check_tips","summary":"General things to check before assuming you have to pay for return shipping — prepaid labels, free in-store","description":"General things to check before assuming you have to pay for return shipping — prepaid labels, free in-store\n    returns, restocking fees, return windows, and damaged/wrong-item exceptions. Use for \"do I have to pay to\n    return this\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"free_return_check_tipsArguments","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/packaging_tips":{"post":{"operationId":"packaging_tips","summary":"General packing guidance for a smoother return — reusing original packaging, covering old labels, weighing","description":"General packing guidance for a smoother return — reusing original packaging, covering old labels, weighing\n    the package yourself to avoid dimensional-weight surprises, and protecting against a damage-related refund\n    denial. Use for \"how should I pack this for a return\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"packaging_tipsArguments","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/international_return_note":{"post":{"operationId":"international_return_note","summary":"General orientation on what's different about an international return — typical added costs (customs,","description":"General orientation on what's different about an international return — typical added costs (customs,\n    duties, brokerage), added time, and practical tips. Not a specific country's customs rules. Use for \"what's\n    different about returning something internationally\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"international_return_noteArguments","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/glossary":{"post":{"operationId":"glossary","summary":"Definitions of return-shipping terms — restocking fee, dimensional weight, RMA, prepaid return label,","description":"Definitions of return-shipping terms — restocking fee, dimensional weight, RMA, prepaid return label,\n    return window, drop-off vs. pickup. Use for \"what's dimensional weight\", \"what's an RMA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"glossaryArguments","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}}}}