> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/returns-api/resources/first-successful-requests.md). # First Successful Requests ### Retailer OMS / outbound-order ingestion engineer This persona owns the first write into the platform: `POST /{identifier}/outbound-orders`. The request body is `CreateOutboundOrderWebRequest`, with fields such as `orderReference`, `contactInformation`, `orderItems`, `customFields`, and `canOverwrite`. A successful response is `201 Created`, and a duplicate create can return `409 Conflict`. **Best first successful request** {% code title="BASE URL" expandable="true" %} ```bash https://returns-oms-api.sandbox.eshopworld.com/ ``` {% endcode %} {% tabs %} {% tab title="Try it" %} {% @code-walkthrough/try-it specLoaded="" specEps="" method="POST" path="/{identifier}/outbound-orders" baseUrl="" title="Creates an Outbound Order" defaults="{"path":{"identifier":""},"query":{},"headers":{"Content-Type":"application/json"}}" mode="closed" %} {% endtab %} {% endtabs %} {% code expandable="true" %} ```json curl -X POST "https:///TENANT01/outbound-orders" \ -H "Content-Type: application/json" \ -d '{ "orderReference": "1636646500", "contactInformation": { "firstName": "John", "lastName": "Smith", "address1": "2107 Massachusetts Avenue", "city": "Washington", "postalCode": "20008", "countryIso": "US", "email": "shipper@domain.com", "telephone": "187456998745", "cultureLanguageIso": "en-GB" }, "orderItems": [ { "productCode": "0607337", "lineItemId": "1", "quantity": 1, "productDescription": "Ultra Slim Watch" } ], "canOverwrite": true }' ``` {% endcode %} Why this is the right first request: it proves tenant scoping, payload shape, contact ingestion, and item ingestion in one call without forcing customs, shipping-status, or returns-only fields too early. *** ### Returns portal / eligibility engineer The safer first request is `GET /{identifier}/orders/{orderReference}`, because the order response already tells you whether the order is returnable, how many articles are available or unavailable for return, whether the return period has expired, and whether the order qualifies for cancel. The endpoint also supports an `orderItems` filter of `all | not-returned`. **Best first successful request** {% code title="BASE URL" expandable="true" %} ```bash https://returns-oms-api.sandbox.eshopworld.com/ ``` {% endcode %} {% tabs %} {% tab title="Try it" %} {% @code-walkthrough/try-it specLoaded="" specEps="" method="GET" path="/{identifier}/orders/{orderReference}" baseUrl="" title="Retrieve an outbound order" defaults="{"path":{"identifier":"","orderReference":""},"query":{"orderItems":""},"headers":{"Content-Type":"application/json"}}" mode="closed" %} {% endtab %} {% endtabs %} Why this is the right first request: for a returns UX, this is the cleanest proof that the portal can look up an order and derive return eligibility before trying to create a return order. *** ### Customer support This persona needs to inspect a specific return after it exists. The cleanest first request is `GET /{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}`. The response includes status, return admin centre code, return type, return method, paid-by, carrier, drop-off location, created and updated timestamps, return items, and weight. **Best first successful request** {% code title="BASE URL" expandable="true" %} ```bash https://returns-oms-api.sandbox.eshopworld.com/ ``` {% endcode %} {% tabs %} {% tab title="Try it" %} {% @code-walkthrough/try-it specLoaded="" specEps="" method="GET" path="/{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}" baseUrl="" title="Gets a Return Order" defaults="{"path":{"identifier":"","orderReference":"","returnOrderNumber":""},"query":{},"headers":{"Content-Type":"application/json"}}" mode="closed" %} {% endtab %} {% endtabs %} Why this is the right first request: it gives support teams a focused, case-level read without requiring filters or body payloads. *** ### Label and document operations This persona has two relevant surfaces: **requesting a preprinted label** and **retrieving a generated return document**. The stronger *first successful write* is `POST /{identifier}/label-requests`, because the request shape is visible and the endpoint is dedicated to label operations. It returns `200 OK`, and duplicates can return `409 Conflict` when the same order/shipping reference combination was already requested. **Best first successful request** {% code title="BASE URL" expandable="true" %} ```bash https://returns-oms-api.sandbox.eshopworld.com/ ``` {% endcode %} {% tabs %} {% tab title="Try it" %} {% @code-walkthrough/try-it specLoaded="" specEps="" method="POST" path="/{identifier}/label-requests" baseUrl="" title="Requests a preprinted label" defaults="{"path":{"identifier":""},"query":{},"headers":{"Content-Type":"application/json"}}" mode="closed" %} {% endtab %} {% endtabs %} {% code expandable="true" %} ```json curl -X POST "https:///TENANT01/label-requests" \ -H "Content-Type: application/json" \ -d '{ "outboundOrderReference": "123456", "shippingReference": "123456", "shopperAddress": { "firstName": "John", "lastName": "Smith", "address1": "123 Road", "city": "Belfast", "postalCode": "BT1 111", "countryIso": "UK", "email": "email@email.com", "telephone": "123456789", "cultureLanguageIso": "en-GB" }, "orderItems": [ { "id": "123456", "productCode": "P1", "lineItemId": "5555555", "quantity": 1, "productDescription": "Digital Watch" } ] }' ``` {% endcode %} Why this is the right first request: it tests label-specific order linkage plus shopper-address handling without depending on an already-created return order number. *** ### Tracking / post-return visibility analyst This persona needs shipment visibility after the return is in flight. The first request is `POST /{identifier}/tracking-events`, whose request model exposes `trackingReference` and `emailAddress`, and whose response includes milestones, detailed events, and carrier. **Best first successful request** {% code title="BASE URL" expandable="true" %} ```bash https://returns-oms-api.sandbox.eshopworld.com/ ``` {% endcode %} {% tabs %} {% tab title="Try it" %} {% @code-walkthrough/try-it specLoaded="" specEps="" method="POST" path="/{identifier}/tracking-events" baseUrl="" title="Retrieves tracking events" defaults="{"path":{"identifier":""},"query":{},"headers":{"Content-Type":"application/json"}}" mode="closed" %} {% endtab %} {% endtabs %} ```json curl -X POST "https:///TENANT01/tracking-events" \ -H "Content-Type: application/json" \ -d '{ "trackingReference": 20077466295, "emailAddress": "shopper@eshopworld.com" }' ``` Why this is the right first request: it is the lightest way to prove the tracking surface is wired correctly and gives both milestone-level and event-level data. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/returns-api/resources/first-successful-requests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.