Skip to main content
A Postman collection covering the Loop public API — every endpoint, grouped by resource, with example request bodies drawn from the same OpenAPI specs that power this documentation.

Download the collection

Import into Postman, then set your API key. The collection is self-contained — no separate environment file required.

​
Setup

  1. In Postman, choose Import and select the downloaded file.
  2. Open the collection’s Variables tab.
  3. Set apiKey to a key generated in Developer Tools.
  4. Run Setup & Auth → Who Am I to confirm the key resolves to the expected shop, and to see the scopes it carries.
baseUrl is pre-set to https://api.loopreturns.com/api/v1. Authentication is configured at the collection level as the X-Authorization header, so individual requests inherit it.

​
Build order

Records must exist before anything that references them. Seeding a sandbox from empty, build in this order: Locations are needed twice — once by inventory, once by order fulfilment.
An order is only returnable if it is fulfilled. The API accepts an order with no fulfillments and returns 200, but nothing on it can be returned — draft-return testing then dead-ends with an empty eligible-items list and no error explaining why.

​
Referencing records

Every reference accepts either Loop’s global identifier or your own external ID. Sending both is a validation error, not a preference:
Most resources also expose dedicated /external/{externalId} routes for GET and DELETE.
Loop’s identifiers are 18–19 digit integers that exceed JavaScript’s safe integer range, so JSON.parse silently corrupts them — including Postman’s own response viewer. Every request in this collection sends X-Loop-Global-Identifier-Type: string, so identifiers arrive as strings and stay intact. If you drop that header in your own client, address records by your external_id instead.

​
Draft Returns

Draft Returns is a state machine. Every response’s _templates enumerates which actions are legal next — drive your integration from those rather than hardcoding a sequence, since what is available changes with shop configuration.
_templates only appears in the HAL-FORMS representation, so every request in the Draft Returns folder sends Accept: application/prs.hal-forms+json. GET /draft-returns requires it and returns 422 unsupported-feature without it; the other endpoints fall back to plain REST JSON and silently omit _templates, which is easier to miss.
The folder is ordered as the journey runs: Create & Inspect → Returning Items → Outcome → Shop Now Cart → Shipping & Customer → Payment → Finalize & Submit.

​
Testing webhooks

Webhooks → Get Sample Payloads returns example payloads for each topic, so you can build and test handlers without triggering real events.