Loop Returns API
Official vendor OpenAPI document · agent-readyE CommerceOrder ManagementapiKey13 EndpointsREST
For 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.
Use for: I need to create a return for a Shopify order, Process a Loop return so it moves to the next workflow stage, Generate a prepaid shipping label for a return, List all returns created in the last 7 days
Not supported: 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.
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.
Install Jentic One Beta
Connect the Loop Returns API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Loop Returns API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Floopreturns.com%2Floopreturns" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Floopreturns.com%2Floopreturns" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Loop Returns API.
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
Patterns agents use Loop Returns API for, with concrete tasks.
★ 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.
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.
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.
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.
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
13 endpoints — 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.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Complementary
Stripe API
Payment processor whose refunds are issued in response to Loop return.processed events
Use Stripe alongside Loop when a processed return needs to trigger a refund on the original payment intent rather than store credit.
FAQs
Specific to using Loop Returns API through Jentic.
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.
GET STARTED