{"openapi":"3.1.0","info":{"title":"Loop Returns (BYOK) API","version":"0.1.0","description":"Loop Returns (BYOK) lets an AI assistant read your own Loop Returns data through the Loop Returns API with a key you supply (Loop API key (with the scopes you need)). Read-only: 9 tools (list_returns, get_return, get_return_notes, list_shipping_notices, list_destinations, get_destination, list_happy_returns_shipments, get_happy_returns_shipment, list_happy_returns_shipment_items). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-loop-returns.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-loop-returns/docs"},"termsOfService":"https://connectorbay.com/byok-loop-returns/terms"},"servers":[{"url":"https://byok-loop-returns.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-loop-returns/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_returns":{"post":{"operationId":"list_returns","summary":"List returns created or updated in a time window (at most 120 days) with state, outcome, order, totals, carrier and trac","description":"List returns created or updated in a time window (at most 120 days) with state, outcome, order, totals, carrier and tracking. Defaults to the last 24 hours. Needs the Returns scope. Use for \"Which returns did customers open on Loop in the last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, 'yyyy-mm-dd hh:mm:ss'. Without it (and without to_date) only the last 24 hours are returned.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, 'yyyy-mm-dd hh:mm:ss'. Ignored when from_date is missing. The window may not exceed 120 days.","title":"To Date"},"filter":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Which date the window applies to: created_at or updated_at.","title":"Filter"},"state":{"anyOf":[{"enum":["open","closed","cancelled","expired","review"],"type":"string"},{"type":"null"}],"default":null,"description":"Only returns in this state; default is open, closed and expired.","title":"State"},"paginate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Keep true so the answer comes back as a page with nextPageUrl.","title":"Paginate"},"page_size":{"anyOf":[{"maximum":750,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many returns per page (1 to 750).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor taken from the nextPageUrl of the previous page.","title":"Cursor"}},"title":"list_returnsArguments","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":{"post":{"operationId":"get_return","summary":"Get one return by Loop return id, order id or order name: state, outcome, totals, carrier, tracking and status page. Giv","description":"Get one return by Loop return id, order id or order name: state, outcome, totals, carrier, tracking and status page. Give exactly one of the three. Use for \"Show the Loop return for order 2222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"return_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Loop return id (a number).","title":"Return Id"},"order_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Order id from the commerce platform (a number).","title":"Order Id"},"order_name":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Order name from the commerce platform, for example 2222.","title":"Order Name"}},"title":"get_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/get_return_notes":{"post":{"operationId":"get_return_notes","summary":"List the notes attached to a return: note id, text and creation time. Use for \"What notes are on Loop return 37603922\".","description":"List the notes attached to a return: note id, text and creation time. Use for \"What notes are on Loop return 37603922\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Loop return id (a number).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_return_notesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_shipping_notices":{"post":{"operationId":"list_shipping_notices","summary":"List return packages (advance shipping notice rows) in a date range with item, carrier, tracking, state and destination ","description":"List return packages (advance shipping notice rows) in a date range with item, carrier, tracking, state and destination warehouse. Customer email is left out. Defaults to the last week. Use for \"Which return packages are on their way to my warehouse\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the range, ISO 8601 such as 2026-10-01T00:00:00.000Z.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the range, ISO 8601.","title":"To Date"}},"title":"list_shipping_noticesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_destinations":{"post":{"operationId":"list_destinations","summary":"List return destinations (warehouses and donation partners) with name, type, enabled flag and address. Needs the Destina","description":"List return destinations (warehouses and donation partners) with name, type, enabled flag and address. Needs the Destinations (Read) scope. Use for \"Where can returns be sent for my Loop account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_destinationsArguments","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_destination":{"post":{"operationId":"get_destination","summary":"Get one return destination by id with its type, enabled flag and address. Use for \"Show Loop destination 12345\".","description":"Get one return destination by id with its type, enabled flag and address. Use for \"Show Loop destination 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Destination id (a number).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_destinationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_happy_returns_shipments":{"post":{"operationId":"list_happy_returns_shipments","summary":"List Happy Returns shipments created in a time window (200 per page) with shipment ids, item and return counts. Needs th","description":"List Happy Returns shipments created in a time window (200 per page) with shipment ids, item and return counts. Needs the Happy Returns Shipments (Read) scope. Use for \"Which Happy Returns shipments went out in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"from_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start, ISO 8601 such as 2026-09-01T00:00:00.000Z.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End, ISO 8601.","title":"To Date"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_happy_returns_shipmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_happy_returns_shipment":{"post":{"operationId":"get_happy_returns_shipment","summary":"Get one Happy Returns shipment by its Happy Returns shipment id. Use for \"Show Happy Returns shipment 210123\".","description":"Get one Happy Returns shipment by its Happy Returns shipment id. Use for \"Show Happy Returns shipment 210123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"happy_returns_shipment_id":{"description":"Happy Returns shipment id.","maxLength":200,"title":"Happy Returns Shipment Id","type":"string"}},"required":["happy_returns_shipment_id"],"title":"get_happy_returns_shipmentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_happy_returns_shipment_items":{"post":{"operationId":"list_happy_returns_shipment_items","summary":"List the items in a Happy Returns shipment (by the Loop shipment id) with order, SKU, carrier and tracking. Use for \"Wha","description":"List the items in a Happy Returns shipment (by the Loop shipment id) with order, SKU, carrier and tracking. Use for \"What items are in Loop shipment 47382\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Loop shipment id (a number, loop_shipment_id).","maxLength":200,"title":"Id","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["id"],"title":"list_happy_returns_shipment_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}}}}