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.

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):

{
  "items": [
    {
      "line_item_id": 123,
      "description": "Grade A: No refurbishment needed",
      "condition_category": "grade_a"
    }
  ]
}

Request, after (2026-10):

{
  "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):

{
  "line_item_id": 123,
  "description": "Grade A: No refurbishment needed",
  "condition_category": "grade_a"
}

Response, after (2026-10):

{
  "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:

{
  "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:

{
  "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:

{
  "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 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 for the full lifecycle.

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.

Introduction

Guides

Use Cases

Return Create

Migration

Summary of changes

1. `condition_category` is now an object

2. ASN endpoint enforces 120-day date range limit

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

4. Draft Returns use HAL Forms only

Webhooks

Staying on 2026-07

Questions?

​Summary of changes

​1. condition_category is now an object

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

​3. created_at is required in ATOM format on orders

​4. Draft Returns use HAL Forms only

​Webhooks

​Staying on 2026-07

​Questions?

Summary of changes

1. `condition_category` is now an object

2. ASN endpoint enforces 120-day date range limit

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

4. Draft Returns use HAL Forms only

Webhooks

Staying on 2026-07

Questions?