{"openapi":"3.1.0","info":{"title":"Returns & Delivery Intelligence API","version":"1.0.0","description":"Read supplied orders, addresses, carrier events, and return rates, and calculate only the comparisons those records support. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST a JSON body matching the operation's requestBody schema to the operation path. Include an Idempotency-Key header (64 hex characters, 32 random bytes).\n2. If you have not paid, the server responds 402 with payment requirements in the body. Pay the exact amount to the payTo address on Base.\n3. Retry the identical request with the same Idempotency-Key and add a payment-signature header containing the x402 payment payload. On success (200) the operation result is returned.\n4. Reuse the same Idempotency-Key only for retries of the same operation and request body; it will not be charged twice.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/returns-delivery/exception-classify":{"post":{"operationId":"classify_delivery_exceptions","summary":"Classify delivery exceptions","description":"Classify a supplied carrier code or order status only when it matches a documented token. Any other code stays unrecognized, and no tracking scan is added.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"text":"Event: E-1 | O-1 | 2026-11-02T15:00:00Z | refused | customer refused\nEvent: E-2 | O-2 | 2026-11-03T15:00:00Z | erase | note\nThe carrier lost the parcel.\n"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"source":{"type":"string"},"code":{"type":"string"},"category":{"type":"string"},"at":{"type":"string"},"confirmed":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"code":{"type":"string"},"subject":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"classified","items":[{"id":"E-1","orderId":"O-1","source":"event","code":"refused","category":"refused","at":"2026-11-02T15:00:00.000Z","confirmed":false,"interpretation":"stated"},{"id":"E-2","orderId":"O-2","source":"event","code":"erase","category":"unrecognized","at":"2026-11-03T15:00:00.000Z","confirmed":false,"interpretation":"none"}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[{"kind":"ignored","code":"unlabeled_line","subject":"","detail":"Lines without a recognized label were not read and their text was not copied."}],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/failed-pattern-detect":{"post":{"operationId":"detect_failed_delivery_patterns","summary":"Detect failed-delivery patterns","description":"Group supplied failed, undeliverable, refused, or returned orders by postcode, address, or carrier. A pattern needs at least three orders. One failure is not a carrier finding.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"orders":[{"id":"O-1","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"},{"id":"O-2","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"},{"id":"O-3","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"},{"id":"O-4","status":"delayed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"level":{"type":"string"},"signals":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"confirmed":{"type":"boolean"},"orders":{"type":"array","items":{"type":"string"}},"detail":{"type":"string"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"checked","level":"review","signals":[{"code":"shared_postcode","confirmed":false,"orders":["O-1","O-2","O-3"],"detail":"3 failed orders share postcode sw1a 1aa|gb. This is not a carrier finding."},{"code":"shared_carrier","confirmed":false,"orders":["O-1","O-2","O-3"],"detail":"3 failed orders share carrier example carrier. This is not a carrier finding."}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/shipping-address-validate":{"post":{"operationId":"validate_shipping_address_structure","summary":"Validate shipping-address structure","description":"Check that the supplied lines, city, postcode, and country are present, and compare a postcode with a published shape for nine country codes. The check does not confirm that a carrier can deliver.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"addresses":[{"id":"A-2","line1":"10 Example Street","city":"Austin","region":"TX","postcode":"1234","country":"US"},{"id":"A-1","line1":"10 Example Street","city":"London","postcode":"SW1A 1AA","country":"GB"},{"id":"A-3","line1":"","city":"","postcode":"","country":""}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"addresses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"countryKnown":{"type":"boolean"},"format":{"type":"string"},"structure":{"type":"string"},"complete":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"interpretation":{"type":"string"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"checked","addresses":[{"id":"A-2","line1":"10 Example Street","line2":"","city":"Austin","region":"TX","postcode":"1234","country":"US","countryKnown":true,"format":"differs","structure":"format","complete":true,"deliverabilityConfirmed":false,"issues":[{"code":"postcode_format","detail":"The postcode does not match the published shape for this country code. Delivery was not checked."}],"interpretation":"stated"},{"id":"A-1","line1":"10 Example Street","line2":"","city":"London","region":"","postcode":"SW1A 1AA","country":"GB","countryKnown":true,"format":"matches","structure":"present","complete":true,"deliverabilityConfirmed":false,"issues":[],"interpretation":"stated"},{"id":"A-3","line1":"","line2":"","city":"","region":"","postcode":"","country":"","countryKnown":false,"format":"not_checked","structure":"incomplete","complete":false,"deliverabilityConfirmed":false,"issues":[{"code":"line1_missing","detail":"The first address line was not supplied."},{"code":"city_missing","detail":"The city was not supplied."},{"code":"postcode_missing","detail":"The postcode was not supplied."},{"code":"country_missing","detail":"The country was not supplied."}],"interpretation":"stated"}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/return-shipping-cost-calculate":{"post":{"operationId":"calculate_return_shipping_cost","summary":"Calculate return shipping cost","description":"Apply one matching caller-supplied rate to a return. A missing rate is not estimated, currencies are not converted, and the result is not a refund.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"orders":[{"id":"O-1","carrier":"Example Carrier","country":"GB"},{"id":"O-2","carrier":"Example Carrier","country":"FR"}],"rates":[{"carrier":"Example Carrier","country":"GB","amount":4.5,"currency":"USD","basis":"flat"}],"returns":[{"id":"R-1","orderId":"O-1","reason":"size"},{"id":"R-2","orderId":"O-2","reason":"size"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"costs":{"type":"array","items":{"type":"object","properties":{"returnId":{"type":"string"},"orderId":{"type":"string"},"currency":{"type":"string"},"stated":{"type":"number"},"statedSupplied":{"type":"boolean"},"calculated":{"type":"number"},"calculatedSupplied":{"type":"boolean"},"basis":{"type":"string"},"refundGranted":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"calculated","costs":[{"returnId":"R-1","orderId":"O-1","currency":"USD","stated":0,"statedSupplied":false,"calculated":4.5,"calculatedSupplied":true,"basis":"flat","refundGranted":false,"interpretation":"stated"},{"returnId":"R-2","orderId":"O-2","currency":"","stated":0,"statedSupplied":false,"calculated":0,"calculatedSupplied":false,"basis":"","refundGranted":false,"interpretation":"stated"}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/return-reason-analyze":{"post":{"operationId":"analyze_return_reasons","summary":"Analyze return reasons","description":"Count supplied return reasons exactly as written. A reason is a pattern only at three or more returns. The reason text is not rewritten and no refund is granted.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"returns":[{"id":"R-1","reason":"size"},{"id":"R-2","reason":"size"},{"id":"R-3","reason":"size"},{"id":"R-4","reason":"color"},{"id":"R-5","reason":"erase"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"reasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"count":{"type":"number"},"pattern":{"type":"boolean"},"refundGranted":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"analyzed","reasons":[{"reason":"size","count":3,"pattern":true,"refundGranted":false,"interpretation":"stated"},{"reason":"color","count":1,"pattern":false,"refundGranted":false,"interpretation":"stated"},{"reason":"erase","count":1,"pattern":false,"refundGranted":false,"interpretation":"stated"}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/promise-variance":{"post":{"operationId":"calculate_delivery_promise_variance","summary":"Calculate delivery-promise variance","description":"Subtract the supplied promise timestamp from the supplied delivery timestamp. A missing timestamp is not filled in, and the comparison is not a carrier guarantee.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"orders":[{"id":"O-1","promised":"2026-11-01","delivered":"2026-11-03"},{"id":"O-2","promised":"2026-11-05","delivered":"2026-11-04"},{"id":"O-3","promised":"2026-11-01"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"promised":{"type":"string"},"delivered":{"type":"string"},"varianceDays":{"type":"number"},"daysSupplied":{"type":"boolean"},"varianceHours":{"type":"number"},"hoursSupplied":{"type":"boolean"},"withinPromise":{"type":"boolean"},"promiseChecked":{"type":"boolean"},"guaranteeConfirmed":{"type":"boolean"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"calculated","orders":[{"id":"O-1","promised":"2026-11-01","delivered":"2026-11-03","varianceDays":2,"daysSupplied":true,"varianceHours":0,"hoursSupplied":false,"withinPromise":false,"promiseChecked":true,"guaranteeConfirmed":false},{"id":"O-2","promised":"2026-11-05","delivered":"2026-11-04","varianceDays":-1,"daysSupplied":true,"varianceHours":0,"hoursSupplied":false,"withinPromise":true,"promiseChecked":true,"guaranteeConfirmed":false},{"id":"O-3","promised":"2026-11-01","delivered":"","varianceDays":0,"daysSupplied":false,"varianceHours":0,"hoursSupplied":false,"withinPromise":false,"promiseChecked":false,"guaranteeConfirmed":false}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/return-window-calculate":{"post":{"operationId":"calculate_a_return_window","summary":"Calculate a return window","description":"Add the supplied day count to the supplied delivered or ordered date and compare a return request with that end date. No day count is assumed, and an inside date is not a refund entitlement.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"window":{"days":14,"from":"delivered"},"orders":[{"id":"O-1","delivered":"2026-11-01"}],"returns":[{"id":"R-1","orderId":"O-1","requested":"2026-11-20"},{"id":"R-2","orderId":"O-1","requested":"2026-11-15"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"days":{"type":"number"},"daysSupplied":{"type":"boolean"},"from":{"type":"string"},"returns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"requested":{"type":"string"},"state":{"type":"string"},"refundGranted":{"type":"boolean"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"calculated","days":14,"daysSupplied":true,"from":"delivered","returns":[{"id":"R-1","orderId":"O-1","start":"2026-11-01","end":"2026-11-15","requested":"2026-11-20","state":"outside","refundGranted":false},{"id":"R-2","orderId":"O-1","start":"2026-11-01","end":"2026-11-15","requested":"2026-11-15","state":"inside","refundGranted":false}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{}}]}}},"/api/v1/returns-delivery/logistics-report":{"post":{"operationId":"report_returns_and_delivery_logistics","summary":"Report returns and delivery logistics","description":"Combine supplied exceptions, failed-order groups, address structure, return rates, promise variance, and the return window. The report does not contact a carrier or grant a refund.","tags":["returns-delivery"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"text":{"type":"string","maxLength":200000},"json":{"type":"string","maxLength":200000},"csv":{"type":"string","maxLength":200000},"file":{"type":"object","properties":{"filename":{"type":"string","minLength":1,"maxLength":180},"mediaType":{"type":"string","enum":["text/plain","text/csv","application/json"]},"fileBase64":{"type":"string","minLength":1,"maxLength":12000000}},"required":["mediaType","fileBase64"],"additionalProperties":false},"orders":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"promised":{"type":"string","maxLength":40},"delivered":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":80},"carrier":{"type":"string","maxLength":80},"ordered":{"type":"string","maxLength":40},"windowDays":{"type":"number","minimum":0,"maximum":3650},"weight":{"type":"number","minimum":0,"maximum":1000000},"addressId":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"addresses":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"line1":{"type":"string","maxLength":160},"line2":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":80}},"additionalProperties":false}},"events":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"at":{"type":"string","maxLength":40},"code":{"type":"string","maxLength":80},"detail":{"type":"string","maxLength":500}},"additionalProperties":false}},"returns":{"maxItems":80,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":80},"orderId":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":160},"requested":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"cost":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"weight":{"type":"number","minimum":0,"maximum":1000000}},"additionalProperties":false}},"rates":{"maxItems":40,"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"amount":{"type":"number","minimum":0,"maximum":1000000000},"currency":{"type":"string","maxLength":12},"basis":{"type":"string","maxLength":40}},"additionalProperties":false}},"window":{"type":"object","properties":{"days":{"type":"number","minimum":0,"maximum":3650},"from":{"type":"string","maxLength":40}},"additionalProperties":false},"rules":{"maxItems":8,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40},"value":{"type":"string","maxLength":40}},"required":["name","value"],"additionalProperties":false}}},"additionalProperties":false},"example":{"orders":[{"id":"O-1","promised":"2026-11-01","delivered":"2026-11-03","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"},{"id":"O-2","promised":"2026-11-01","delivered":"2026-11-03","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"},{"id":"O-3","promised":"2026-11-01","delivered":"2026-11-03","status":"failed","carrier":"Example Carrier","postcode":"SW1A 1AA","country":"GB"}],"addresses":[{"id":"A-1","line1":"10 Example Street","city":"London","postcode":"SW1A 1AA","country":"GB"},{"id":"A-2","line1":"10 Example Street","city":"Austin","postcode":"1234","country":"US"}],"returns":[{"id":"R-1","orderId":"O-1","reason":"size","requested":"2026-11-20"},{"id":"R-2","orderId":"O-1","reason":"size","requested":"2026-11-10"},{"id":"R-3","orderId":"O-2","reason":"size","requested":"2026-11-10"}],"rates":[{"carrier":"Example Carrier","country":"GB","amount":4.5,"currency":"USD","basis":"flat"}],"window":{"days":14,"from":"delivered"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"checkedAt":{"type":"string"},"status":{"type":"string"},"orderCount":{"type":"number"},"failedCount":{"type":"number"},"patternCount":{"type":"number"},"addressIssueCount":{"type":"number"},"calculatedCount":{"type":"number"},"lateCount":{"type":"number"},"outsideCount":{"type":"number"},"level":{"type":"string"},"totals":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"},"count":{"type":"number"}},"additionalProperties":true}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"source":{"type":"string"},"code":{"type":"string"},"category":{"type":"string"},"at":{"type":"string"},"confirmed":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"signals":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"confirmed":{"type":"boolean"},"orders":{"type":"array","items":{"type":"string"}},"detail":{"type":"string"}},"additionalProperties":true}},"addresses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"countryKnown":{"type":"boolean"},"format":{"type":"string"},"structure":{"type":"string"},"complete":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"issues":{"type":"array","items":{}},"interpretation":{"type":"string"}},"additionalProperties":true}},"costs":{"type":"array","items":{"type":"object","properties":{"returnId":{"type":"string"},"orderId":{"type":"string"},"currency":{"type":"string"},"stated":{"type":"number"},"statedSupplied":{"type":"boolean"},"calculated":{"type":"number"},"calculatedSupplied":{"type":"boolean"},"basis":{"type":"string"},"refundGranted":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"reasons":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string"},"count":{"type":"number"},"pattern":{"type":"boolean"},"refundGranted":{"type":"boolean"},"interpretation":{"type":"string"}},"additionalProperties":true}},"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"promised":{"type":"string"},"delivered":{"type":"string"},"varianceDays":{"type":"number"},"daysSupplied":{"type":"boolean"},"varianceHours":{"type":"number"},"hoursSupplied":{"type":"boolean"},"withinPromise":{"type":"boolean"},"promiseChecked":{"type":"boolean"},"guaranteeConfirmed":{"type":"boolean"}},"additionalProperties":true}},"returns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"requested":{"type":"string"},"state":{"type":"string"},"refundGranted":{"type":"boolean"}},"additionalProperties":true}},"carrierContacted":{"type":"boolean"},"returnInitiated":{"type":"boolean"},"refundGranted":{"type":"boolean"},"deliverabilityConfirmed":{"type":"boolean"},"eventsInvented":{"type":"boolean"},"findings":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"checkedAt":"2026-11-04T12:00:00.000Z","status":"reported","orderCount":3,"failedCount":3,"patternCount":2,"addressIssueCount":1,"calculatedCount":3,"lateCount":3,"outsideCount":1,"level":"review","totals":[{"currency":"USD","amount":13.5,"count":3}],"items":[{"id":"O-1","orderId":"O-1","source":"status","code":"failed","category":"failed","at":"2026-11-03","confirmed":false,"interpretation":"stated"},{"id":"O-2","orderId":"O-2","source":"status","code":"failed","category":"failed","at":"2026-11-03","confirmed":false,"interpretation":"stated"},{"id":"O-3","orderId":"O-3","source":"status","code":"failed","category":"failed","at":"2026-11-03","confirmed":false,"interpretation":"stated"}],"signals":[{"code":"shared_postcode","confirmed":false,"orders":["O-1","O-2","O-3"],"detail":"3 failed orders share postcode sw1a 1aa|gb. This is not a carrier finding."},{"code":"shared_carrier","confirmed":false,"orders":["O-1","O-2","O-3"],"detail":"3 failed orders share carrier example carrier. This is not a carrier finding."}],"addresses":[{"id":"A-1","line1":"10 Example Street","line2":"","city":"London","region":"","postcode":"SW1A 1AA","country":"GB","countryKnown":true,"format":"matches","structure":"present","complete":true,"deliverabilityConfirmed":false,"issues":[],"interpretation":"stated"},{"id":"A-2","line1":"10 Example Street","line2":"","city":"Austin","region":"","postcode":"1234","country":"US","countryKnown":true,"format":"differs","structure":"format","complete":true,"deliverabilityConfirmed":false,"issues":[{"code":"postcode_format","detail":"The postcode does not match the published shape for this country code. Delivery was not checked."}],"interpretation":"stated"}],"costs":[{"returnId":"R-1","orderId":"O-1","currency":"USD","stated":0,"statedSupplied":false,"calculated":4.5,"calculatedSupplied":true,"basis":"flat","refundGranted":false,"interpretation":"stated"},{"returnId":"R-2","orderId":"O-1","currency":"USD","stated":0,"statedSupplied":false,"calculated":4.5,"calculatedSupplied":true,"basis":"flat","refundGranted":false,"interpretation":"stated"},{"returnId":"R-3","orderId":"O-2","currency":"USD","stated":0,"statedSupplied":false,"calculated":4.5,"calculatedSupplied":true,"basis":"flat","refundGranted":false,"interpretation":"stated"}],"reasons":[{"reason":"size","count":3,"pattern":true,"refundGranted":false,"interpretation":"stated"}],"orders":[{"id":"O-1","promised":"2026-11-01","delivered":"2026-11-03","varianceDays":2,"daysSupplied":true,"varianceHours":0,"hoursSupplied":false,"withinPromise":false,"promiseChecked":true,"guaranteeConfirmed":false},{"id":"O-2","promised":"2026-11-01","delivered":"2026-11-03","varianceDays":2,"daysSupplied":true,"varianceHours":0,"hoursSupplied":false,"withinPromise":false,"promiseChecked":true,"guaranteeConfirmed":false},{"id":"O-3","promised":"2026-11-01","delivered":"2026-11-03","varianceDays":2,"daysSupplied":true,"varianceHours":0,"hoursSupplied":false,"withinPromise":false,"promiseChecked":true,"guaranteeConfirmed":false}],"returns":[{"id":"R-1","orderId":"O-1","start":"2026-11-03","end":"2026-11-17","requested":"2026-11-20","state":"outside","refundGranted":false},{"id":"R-2","orderId":"O-1","start":"2026-11-03","end":"2026-11-17","requested":"2026-11-10","state":"inside","refundGranted":false},{"id":"R-3","orderId":"O-2","start":"2026-11-03","end":"2026-11-17","requested":"2026-11-10","state":"inside","refundGranted":false}],"carrierContacted":false,"returnInitiated":false,"refundGranted":false,"deliverabilityConfirmed":false,"eventsInvented":false,"findings":[],"limitations":["Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.","No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.","An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.","A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.","No carrier account is contacted and no return is initiated."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed. With upfront settlement this may occur after payment; reuse the same idempotency key to retrieve the stored result."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.12"},"protocols":[{"x402":{}}]}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}