{"inputSchema":{"type":"object","required":["items"],"additionalProperties":false,"properties":{"items":{"type":"array","minItems":1,"maxItems":500,"description":"The returns to decide on. Every amount is in the currency named at document level.","items":{"type":"object","required":["return_id"],"additionalProperties":false,"properties":{"return_id":{"type":"string","minLength":1,"maxLength":64,"description":"Your identifier for this return. Must be unique within the request."},"condition":{"type":"string","enum":["new","like_new","used","damaged","defective","unknown"],"description":"Condition as your inspection recorded it. Passed through unchanged; it does not change the arithmetic."},"resale_value":{"type":"number","minimum":0,"maximum":100000000,"description":"Expected proceeds from selling the item as it is."},"resale_probability":{"type":"number","minimum":0,"maximum":1,"default":1,"description":"Probability that the as-is resale actually happens within your planning window."},"refurb_resale_value":{"type":"number","minimum":0,"maximum":100000000,"description":"Expected proceeds after a successful repair."},"repair_cost":{"type":"number","minimum":0,"maximum":100000000,"description":"Cost of the repair attempt. Incurred whether or not the repair succeeds."},"repair_success_probability":{"type":"number","minimum":0,"maximum":1,"description":"Probability that the repair succeeds. A failed repair falls back to salvage_value."},"salvage_value":{"type":"number","minimum":0,"maximum":100000000,"description":"Proceeds from parts recovery or material recycling."},"disposal_cost":{"type":"number","minimum":0,"maximum":100000000,"description":"Cost of disposing of the item. Scrapping is a cost, not proceeds."},"inspection_cost":{"type":"number","minimum":0,"maximum":100000000,"description":"Cost of inspecting this return. Incurred on every route and therefore does not change the ranking, only the level."},"inbound_freight_cost":{"type":"number","minimum":0,"maximum":100000000,"description":"Freight already spent getting the item back. Incurred on every route."},"restocking_cost":{"type":"number","minimum":0,"maximum":100000000,"description":"Cost of putting the item back into stock. Only charged to the as-is resale route."}}}},"defaults":{"type":"object","additionalProperties":false,"description":"Values that apply to every item that does not carry its own. An item value always wins.","properties":{"resale_probability":{"type":"number","minimum":0,"maximum":1},"repair_cost":{"type":"number","minimum":0,"maximum":100000000},"repair_success_probability":{"type":"number","minimum":0,"maximum":1},"disposal_cost":{"type":"number","minimum":0,"maximum":100000000},"inspection_cost":{"type":"number","minimum":0,"maximum":100000000},"inbound_freight_cost":{"type":"number","minimum":0,"maximum":100000000},"restocking_cost":{"type":"number","minimum":0,"maximum":100000000}}},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"EUR","description":"ISO 4217 code for every amount in this request. Not converted, only carried through."},"decision_margin_pct":{"type":"number","minimum":0,"maximum":100,"default":5,"description":"How far ahead the best route must be before it counts as a decision. Inside this margin the result is reported as ambiguous instead of asserting a winner."}}},"outputSchema":{"type":"object","properties":{"decisions":{"type":"array"},"summary":{"type":"object"},"method":{"type":"object"},"unavailable_fields":{"type":"array"}}},"priceModel":null,"requestExample":{"currency":"EUR","defaults":{"inspection_cost":4.5,"inbound_freight_cost":3.9,"restocking_cost":2,"disposal_cost":1.5},"items":[{"return_id":"R-1001","condition":"like_new","resale_value":189,"resale_probability":0.95,"refurb_resale_value":199,"repair_cost":35,"repair_success_probability":0.9,"salvage_value":12},{"return_id":"R-1002","condition":"defective","resale_value":20,"resale_probability":0.4,"refurb_resale_value":149,"repair_cost":60,"repair_success_probability":0.7,"salvage_value":18},{"return_id":"R-1003","condition":"damaged","resale_value":9,"resale_probability":0.3,"refurb_resale_value":40,"repair_cost":55,"repair_success_probability":0.5,"salvage_value":6}],"decision_margin_pct":5},"price_usdc":"0.004","example_request":{"currency":"EUR","defaults":{"inspection_cost":4.5,"inbound_freight_cost":3.9,"restocking_cost":2,"disposal_cost":1.5},"items":[{"return_id":"R-1001","condition":"like_new","resale_value":189,"resale_probability":0.95,"refurb_resale_value":199,"repair_cost":35,"repair_success_probability":0.9,"salvage_value":12},{"return_id":"R-1002","condition":"defective","resale_value":20,"resale_probability":0.4,"refurb_resale_value":149,"repair_cost":60,"repair_success_probability":0.7,"salvage_value":18},{"return_id":"R-1003","condition":"damaged","resale_value":9,"resale_probability":0.3,"refurb_resale_value":40,"repair_cost":55,"repair_success_probability":0.5,"salvage_value":6}],"decision_margin_pct":5},"serviceName":"return_disposition","tags":["returns","reverse-logistics","decision","commerce"],"outputExample":{"decisions":[{"return_id":"R-1001","condition":"like_new","recommendation":"resell_as_is","best_route":"resell_as_is","net_value":169.15,"runner_up":"repair_and_resell","margin_over_runner_up":32.25,"margin_over_runner_up_pct":19.066,"ambiguous":false,"ambiguous_note":null,"repair_cost_break_even":2.75,"repair_cost_break_even_note":"repairing stays the better choice while repair_cost stays below this amount, everything else unchanged","options":[{"route":"resell_as_is","evaluable":true,"missing_fields":[],"net_value":169.15,"common_cost":8.4,"calculation":"0.95 * 189 - 2 restocking - 8.4 inspection and inbound freight"},{"route":"repair_and_resell","evaluable":true,"missing_fields":[],"net_value":136.9,"common_cost":8.4,"calculation":"0.9 * 199 + 0.1 * 12 - 35 repair - 8.4 inspection and inbound freight"},{"route":"recover_value","evaluable":true,"missing_fields":[],"net_value":3.6,"common_cost":8.4,"calculation":"12 - 8.4 inspection and inbound freight"},{"route":"scrap","evaluable":true,"missing_fields":[],"net_value":-9.9,"common_cost":8.4,"calculation":"-1.5 disposal - 8.4 inspection and inbound freight"}],"assumed_zero_costs":[]},{"return_id":"R-1002","condition":"defective","recommendation":"repair_and_resell","best_route":"repair_and_resell","net_value":41.3,"runner_up":"recover_value","margin_over_runner_up":31.7,"margin_over_runner_up_pct":76.755,"ambiguous":false,"ambiguous_note":null,"repair_cost_break_even":91.7,"repair_cost_break_even_note":"repairing stays the better choice while repair_cost stays below this amount, everything else unchanged","options":[{"route":"resell_as_is","evaluable":true,"missing_fields":[],"net_value":-2.4,"common_cost":8.4,"calculation":"0.4 * 20 - 2 restocking - 8.4 inspection and inbound freight"},{"route":"repair_and_resell","evaluable":true,"missing_fields":[],"net_value":41.3,"common_cost":8.4,"calculation":"0.7 * 149 + 0.3 * 18 - 60 repair - 8.4 inspection and inbound freight"},{"route":"recover_value","evaluable":true,"missing_fields":[],"net_value":9.6,"common_cost":8.4,"calculation":"18 - 8.4 inspection and inbound freight"},{"route":"scrap","evaluable":true,"missing_fields":[],"net_value":-9.9,"common_cost":8.4,"calculation":"-1.5 disposal - 8.4 inspection and inbound freight"}],"assumed_zero_costs":[]},{"return_id":"R-1003","condition":"damaged","recommendation":"recover_value","best_route":"recover_value","net_value":-2.4,"runner_up":"resell_as_is","margin_over_runner_up":5.3,"margin_over_runner_up_pct":220.833,"ambiguous":false,"ambiguous_note":null,"repair_cost_break_even":17,"repair_cost_break_even_note":"repairing stays the better choice while repair_cost stays below this amount, everything else unchanged","options":[{"route":"resell_as_is","evaluable":true,"missing_fields":[],"net_value":-7.7,"common_cost":8.4,"calculation":"0.3 * 9 - 2 restocking - 8.4 inspection and inbound freight"},{"route":"repair_and_resell","evaluable":true,"missing_fields":[],"net_value":-40.4,"common_cost":8.4,"calculation":"0.5 * 40 + 0.5 * 6 - 55 repair - 8.4 inspection and inbound freight"},{"route":"recover_value","evaluable":true,"missing_fields":[],"net_value":-2.4,"common_cost":8.4,"calculation":"6 - 8.4 inspection and inbound freight"},{"route":"scrap","evaluable":true,"missing_fields":[],"net_value":-9.9,"common_cost":8.4,"calculation":"-1.5 disposal - 8.4 inspection and inbound freight"}],"assumed_zero_costs":[]}],"summary":{"currency":"EUR","returns":3,"decided":3,"ambiguous":0,"not_valuable":0,"recommendation_counts":{"resell_as_is":1,"repair_and_resell":1,"recover_value":1,"scrap":0},"net_value_of_decided":208.05,"net_value_if_everything_scrapped":-29.7,"gain_over_scrapping_everything":237.75,"reference_note":"The scrap-everything figure counts only the returns whose scrap route could be valued, so compare it against decided rather than against returns."},"method":{"routes":["resell_as_is","repair_and_resell","recover_value","scrap"],"common_costs":"inspection_cost and inbound_freight_cost are charged to every route: they are incurred whatever you decide, so they change the level and never the ranking","restocking":"restocking_cost is charged to resell_as_is only","repair_failure":"a failed repair falls back to salvage_value; repair_cost is charged either way","arithmetic":"whole cents, the same rule as /v1/invoice-audit","tie_break":"equal net values are decided in the fixed order resell_as_is > repair_and_resell > recover_value > scrap, never by input order","omitted_costs":"an omitted cost is treated as zero and named in assumed_zero_costs; an omitted value makes its route not evaluable and is never treated as zero","deterministic":true,"out_of_scope":["market price lookup","condition grading","warranty and statutory rights","running your returns process"]},"unavailable_fields":[]}}