> ## 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.

# Migrate from 2026-07 to 2026-10

This guide covers the breaking changes between API versions `2026-07` and `2026-10`, and what you
need to update in your integration.

> [!WARNING]
>
> **The `/api/latest/` alias moves from `2026-07` to `2026-10` on 29 October 2026.**
>
> If you call `/api/latest/`, your integration will pick up all four breaking changes on that date.
> The `/api/v1/` alias and explicit `/api/2026-07/` paths are unaffected. If you want stability,
> pin your requests to `/api/2026-07/` before the cutover.

## Summary of changes

| Change | Type | Endpoint |
| - | - | - |
| `condition_category` is now an object | Breaking | `POST /dispositioning/grade` |
| ASN endpoint enforces 120-day date range limit | Breaking | `GET /warehouse/reporting/asn` |
| `created_at` is required in ATOM format on orders | Breaking | `POST /orders`, `PUT /orders`, `PUT /orders/{id}` |
| Draft Returns use HAL Forms only, ignore `Accept` header | Breaking | All Draft Returns endpoints |

## 1. `condition_category` is now an object

**Endpoint:** `POST /dispositioning/grade`

**What changed:**
In `2026-07`, `condition_category` is a string, for example `"grade_a"`, in both the request and the
response. In `2026-10`, it is an object in both directions. A plain string is no longer accepted on
`2026-10` and the request fails with a `422` validation error on `items.N.condition_category`.

**Request, before (2026-07):**

```json theme={null}
{
  "items": [
    {
      "line_item_id": 123,
      "description": "Grade A: No refurbishment needed",
      "condition_category": "grade_a"
    }
  ]
}
```

**Request, after (2026-10):**

```json theme={null}
{
  "items": [
    {
      "line_item_id": 123,
      "description": "Grade A: No refurbishment needed",
      "condition_category": {
        "subject": "Item condition grade",
        "title": "Grade A",
        "grade": "grade_a",
        "category_name": "grade_a",
        "category_parent": "Grade"
      }
    }
  ]
}
```

`subject` and `title` are required when you send the object. `grade`, `category_name`, and
`category_parent` are optional, and each value can be up to 100 characters. Loop matches the
category by `subject` and `title`. If no category with that pair exists yet, a new one is created
with the values you send.

**Response, before (2026-07):**

```json theme={null}
{
  "line_item_id": 123,
  "description": "Grade A: No refurbishment needed",
  "condition_category": "grade_a"
}
```

**Response, after (2026-10):**

```json theme={null}
{
  "line_item_id": 123,
  "description": "Grade A: No refurbishment needed",
  "condition_category": {
    "grade": "grade_a",
    "title": "Grade A",
    "subject": "Item condition grade",
    "category_name": "grade_a",
    "category_parent": "Grade"
  }
}
```

**What to do:**

* Send `condition_category` as an object with at least `subject` and `title`. To keep using the
  built-in categories, send the matching pair, for example `"Item condition grade"` and `"Grade A"`.
* Update code that reads `condition_category` from grade responses to handle an object instead of
  a string. The value you previously received is available as `condition_category.grade`.

## 2. ASN endpoint enforces 120-day date range limit

**Endpoint:** `GET /warehouse/reporting/asn`

**What changed:**
In `2026-10`, the endpoint validates `from` and `to`. It returns a `422` when either value is not a
parseable date, or when the range between them is longer than 120 days. A range of exactly 120 days
is allowed.

**Before (2026-07):**
There is no limit on the range, so wide ranges are accepted. An unparseable `from` or `to` value
silently falls back to the Unix epoch.

**After (2026-10), range longer than 120 days:**

```json theme={null}
{
  "message": "The from and to range exceeds the allowable max of 120 days (and 1 more error)",
  "errors": {
    "from": ["The from and to range exceeds the allowable max of 120 days"],
    "to": ["The from and to range exceeds the allowable max of 120 days"]
  }
}
```

**After (2026-10), unparseable date:**

```json theme={null}
{
  "message": "The from and to field must be a valid ATOM date. (and 1 more error)",
  "errors": {
    "from": ["The from and to field must be a valid ATOM date."],
    "to": ["The from and to field must be a valid ATOM date."]
  }
}
```

**What to do:**
Make sure your `from` and `to` query parameters are valid dates, for example in `YYYY-MM-DD`
format, and that the range between them is 120 days or less. Split longer reports into several
requests, and handle `422` responses by reading the `errors.from` and `errors.to` arrays.

## 3. `created_at` is required in ATOM format on orders

**Endpoints:**

* `POST /orders` (Create Order)
* `PUT /orders` (Upsert Order)
* `PUT /orders/{id}` (Update Order)

**What changed:**
In `2026-07`, the `created_at` field was optional, and omitting it would generate a
`missing_created_at` warning. In `2026-10`, the field is required and must be in ATOM format
(RFC 3339 with UTC offset).

**Before (2026-07):**
Requests without `created_at` succeeded but returned a warning.

**After (2026-10):**
Requests without `created_at` fail with a validation error.

**Example of valid format:**

```json theme={null}
{
  "external_id": "order-10042",
  "name": "#10042",
  "created_at": "2026-08-07T14:32:00-07:00"
}
```

**What to do:**
Include the `created_at` field in all order create, upsert, and update requests. Use ATOM format:
`YYYY-MM-DDTHH:MM:SS+HH:MM` or `YYYY-MM-DDTHH:MM:SSZ` for UTC.

## 4. Draft Returns use HAL Forms only

**Endpoints:** All Draft Returns endpoints under `/draft-returns/...`

**What changed:**
In `2026-07`, the response format depended on the `Accept` header:

* `Accept: application/prs.hal-forms+json` returned HAL Forms
* `Accept: application/json` (or no header) returned plain JSON

In `2026-10`, all responses use HAL Forms format regardless of the `Accept` header. This includes
`GET /draft-returns` (List), which on `2026-07` still requires `Accept: application/prs.hal-forms+json`
and returns a `422` with error code `unsupported-feature` without it. On `2026-10`, List works with
or without that header.

**Before (2026-07):**
Without the HAL Forms `Accept` header, responses used plain JSON with merchant questions and
messages as plain text.

**After (2026-10):**
All responses use HAL Forms format with `_links`, `_templates`, `_embedded`, and HTML-formatted
messages.

**What to do:**
Update your Draft Returns integration to handle HAL Forms responses:

* Parse `_links` for available actions
* Parse `_templates` for action descriptors with `method`, `title`, `contentType`, and `properties`
* Handle HTML in user input messages via `systemMessage`

See the [Draft Returns (HAL Forms) documentation](https://docs.loopreturns.com/api-reference/2026-10/draft-returns/overview.md)
for the full response structure.

## Webhooks

If you have not selected a webhook version on the **outgoing webhook configuration** page in the
Loop admin portal, your shop follows the latest stable version, so from 29 October 2026 it will
show `2026-10`. To stay on `2026-07`, select it explicitly on that page.

## Staying on 2026-07

If you are not ready to migrate, you can continue using `2026-07` by pinning your requests
explicitly:

```
GET https://api.loopreturns.com/api/2026-07/returns
```

`2026-07` remains a supported stable version. It is deprecated on 15 July 2027 (12 months after its
release) and sunset on 15 July 2028 (24 months after its release). Check the
[versioning page](https://docs.loopreturns.com/api-reference/versioning.md) for the full lifecycle.

> [!WARNING]
>
> Do not use `/api/latest/` if you want to stay on `2026-07`. The `latest` alias moves to
> `2026-10` on 29 October 2026, and clients calling `/api/latest/` will pick up all four
> breaking changes on that date. The `/api/v1/` alias and explicit `/api/2026-07/` paths
> are unaffected.

## Questions?

If you have questions about migrating or need help, contact [support@loopreturns.com](mailto:support@loopreturns.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.