> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft Returns

> Build a return-creation flow by managing draft returns through a state machine.

## Draft Returns API

<Warning>
  This API version is **unreleased** and subject to change.
  Test it via the `unstable` version path: `/api/unstable/draft-returns/...`
</Warning>

The Draft Returns API lets you build a complete return-creation flow by managing draft returns
through a state machine. Endpoints allow you to initialize a draft, add or remove items, set
customer and address details, finalize selections, and submit the completed return.

### Response structure

Each successful response includes:

* `draft_return` — the draft return and shopper details
* `context` — data needed to fill action payloads
* `_links` — available actions, keyed by relation name, each with an `href`
* `_templates` — action descriptors keyed by name, with `method`, `title`, `contentType`, and `properties`
* `client_application` — how the client should identify itself on later requests
* `errors` — any errors from processing

```json theme={null}
{
  "_links": {
    "self": { "href": "https://api.loopreturns.com/api/unstable/draft-returns/123" },
    "add-returning-item": {
      "href": "https://api.loopreturns.com/api/unstable/draft-returns/123/returning-items"
    }
  },
  "_templates": {
    "add-returning-item": {
      "method": "POST",
      "title": "Add a line item to the return",
      "contentType": "application/json",
      "properties": [
        { "name": "order_line_item_id", "type": "number", "required": true }
      ]
    }
  },
  "draft_return": { "..." },
  "context": { "..." },
  "client_application": { "..." },
  "errors": []
}
```

Responses use `Content-Type: application/prs.hal-forms+json`. Request bodies use
`Content-Type: application/json`. Authenticate with the `X-Authorization` API key header.

### State machine

```
created → finalize-items → items-finalized → submit → submitted
   ↓                              ↓
   ↓← ← unfinalize-items ← ← ← ← ↓
   ↓                              ↓
   └→ cancel → cancelled     expired
```

* **created** — add items and set customer information
* **items-finalized** — choose credit type and return method
* **submitted** / **cancelled** / **expired** — terminal; `_templates` and `_links` are empty