canonical: https://jentic.com/apis/loopreturns.com/loopreturns # Loop Returns API Loop Returns is a Shopify-first returns-management platform whose API exposes the post-purchase return lifecycle - creating returns, processing or closing them, generating return shipping labels, and configuring webhooks. The 13 endpoints cover return CRUD, return-reason and destination lookups, and webhook subscriptions so external systems can react to status changes. Authentication uses an API key in the X-Authorization header issued from the Loop admin. ## For AI agents Create, process, close, and label ecommerce returns on Loop Returns through 13 endpoints; subscribe webhooks for status changes via an API key in the X-Authorization header. ## Scope Does not handle outbound order fulfilment, payment refunds on the gateway, or inventory restocking outside Loop's destination model - use for the Loop Returns lifecycle (returns, labels, webhooks, configuration) only. ## Capabilities - Create a return for an order with line items, return reasons, and resolution type (refund, exchange, store credit) - Process or close an existing return to advance it through the resolution workflow - Generate a return shipping label and retrieve the tracking number for the customer - List configured return reasons and destinations to populate a customer-facing returns portal - Subscribe and unsubscribe webhooks so order systems react to return status changes in real time - Retrieve a return record by ID for support, fraud review, or warehouse handoff ## Use cases ### Self-service returns portal Shopify-based brands embed a returns portal that calls Loop Returns to create a return, fetch the available reasons and destinations, and generate a prepaid label for the customer. The 13 endpoints cover the full flow from intake to label issuance, and webhooks notify the OMS once the warehouse processes the inbound parcel. Most brands ship the integration in under a week. Example prompt: POST /returns with order ID, line items, and reason code; then POST `/returns/{returnId}/labels` to generate the prepaid label and return the tracking number to the customer. ### Returns ops automation Operations teams use the API to bulk-process backlogged returns once the warehouse confirms receipt. List endpoints surface returns awaiting action, `/returns/{returnId}/process` advances them, and webhooks push the resulting status to downstream finance and inventory systems so refunds and stock updates happen without manual intervention. Example prompt: GET /returns filtered by status 'awaiting_processing', loop through each ID and POST `/returns/{returnId}/process`, and confirm the status webhook fires for each. ### Refund and inventory reconciliation Finance and inventory teams subscribe to Loop webhooks to keep their ledger and stock counts aligned with return outcomes. When a return is processed or closed, the webhook payload triggers a refund event in the payments system and an inventory adjustment for the destination warehouse, eliminating the daily reconciliation report most teams used to run by hand. Example prompt: POST /webhooks subscribing to 'return.processed', then on each event POST a refund in the payment system and increment the destination warehouse's inventory for the returned SKUs. ### Agent-driven returns assistant via Jentic An AI assistant in customer service handles 'where is my return?' questions by calling Loop through Jentic. The agent fetches the return record, the associated label tracking, and the destination so it can answer without touching the rep dashboard. Jentic isolates the X-Authorization API key so the agent never sees the raw secret. Example prompt: Use Jentic to search 'get loop return', load GET `/returns/{returnId}`, execute it with the return ID from the chat, and combine the response with GET `/returns/{returnId}/labels` to answer the customer. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/returns` | Create a return for an order | | GET | `/returns/{returnId}` | Get a return by ID | | POST | `/returns/{returnId}/process` | Process a return through the workflow | | POST | `/returns/{returnId}/close` | Close a return | | POST | `/returns/{returnId}/labels` | Generate a return shipping label | | GET | `/return-reasons` | List configured return reasons | | GET | `/destinations` | List configured return destinations | | POST | `/webhooks` | Subscribe a webhook for return events | ## Key resources - **Returns** — Create, retrieve, update, process, and close returns through the resolution lifecycle - **Labels** — Generate and retrieve prepaid return shipping labels - **Configuration** — List configured return reasons and return destinations - **Webhooks** — Subscribe and manage webhooks for return lifecycle events ## Why Jentic - **Setup:** Wiring the Loop Returns API by hand means setting up its X-Authorization key header, attaching it to every call against api.loopreturns.com, and shaping return, label, and webhook request bodies yourself. Through Jentic you install once, import Loop Returns from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Loop Returns puts the return id in the URL path (`/returns/{returnId}/...`), so a rule can pin your agent to one return: it can read that return and generate its label and nothing else. You choose the operations it may call, so state changes like processing or closing a return are not included unless you add them. - **Credential handling:** Your Loop Returns API key is stored once, encrypted, by your own Jentic One instance and injected into the X-Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a return' or 'generate a return label', and Jentic returns the matching Loop operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AfterShip API** — Tracking-first post-purchase platform that also handles returns alongside shipment tracking - **ShipStation API** — Outbound shipping and label-printing platform that pairs with Loop for the return-leg label - **Shopify Admin API** — Underlying ecommerce platform whose orders are the source of Loop return records - **Stripe API** — Payment processor whose refunds are issued in response to Loop return.processed events ## FAQ ### What authentication does the Loop Returns API use? The Loop Returns API uses an API key sent in the X-Authorization header - generate the key from the Loop admin under API integrations. Through Jentic, the key is stored encrypted in the vault and the agent receives a scoped reference, so the raw key never enters agent context. ### Can I generate a return shipping label through the Loop Returns API? Yes. POST `/returns/{returnId}/labels` generates a prepaid label and GET `/returns/{returnId}/labels` retrieves it. The response includes the carrier tracking number you can pass back to the customer or store in your OMS. ### What are the rate limits for the Loop Returns API? Loop applies per-account rate limits and returns HTTP 429 when exceeded; the published guidance is to retry with exponential backoff. Jentic forwards 429 responses unchanged so an agent can pause and retry rather than crash the workflow. ### How do I subscribe to return status changes through Jentic? Search Jentic for 'subscribe loop returns webhook', load POST /webhooks, and execute it with your callback URL and the events you care about (return.created, return.processed, return.closed). Loop will then POST to your URL whenever those events fire. ### Does the Loop Returns API support exchanges as well as refunds? Yes. POST /returns accepts a resolution type that includes refund, exchange, and store credit, and the configured destinations control where exchanged stock is routed. Use GET /destinations to list configured warehouse destinations before creating exchange returns. ### How many endpoints does the Loop Returns API have? 13 endpoints across returns, labels, configuration (return reasons and destinations), and webhooks. The whole returns lifecycle fits into a small operation set that an agent can hold in context at once. ### Can I limit what my agent is allowed to do with the Loop Returns API? Yes. Because you run Jentic One yourself and your own rules decide which operations and credentials the agent may use, you pick exactly which Loop Returns endpoints it can call. Since Loop puts the return id in the URL path (`/returns/{returnId}/...`), you can pin the agent to a single return so it only reads that record via GET `/returns/{returnId}` and generates its label via POST `/returns/{returnId}/labels.` State-changing operations like POST `/returns/{returnId}/process` or /close and webhook subscriptions stay off unless you explicitly grant them.