# Fix up shipment line positions

```http
POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item/sort
```

- API version: v2
- Operation ID: `v2_public_shipment_item_sort`
- Section: Shipping › [Shipment line items](https://developer.yoprint.com/reference/shipment-line-items.md)
- Web page: https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-sort/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Makes room around a line whose position you just changed, so positions stay unique and spaced. It doesn't move the line to a new place: set `position` with Update a shipment line first, then call this with the line (`current`) and its new neighbours (`previous`, `next`).

- Send all three as null (or a `current` that isn't on the shipment) to re-space every line, keeping their order.
- If `previous` and `next` are both sent and are within 1000 of each other, every line is re-spaced.
- Otherwise, if the line is within 1000 of a neighbour, only it moves: to the middle of `previous` and `next`, or 3000 past the only neighbour you sent.
- Otherwise nothing changes.

Returns `is_position_sorted` and, when positions changed, every line (`data`).

## Permission

Needs permission to edit the shipment's order: the team owner, a role whose Manage Sales Orders permission is "update all", or "update assigned" when you created the order or are assigned to it, or, on a draft order, its creator when their role can create sales orders. Otherwise 403 `user_is_not_authorized`. Reading needs only team membership.

## Business rules

- Hash ids only in `previous`, `current` and `next`: a unique key passes validation but fails with 500.

## Side effects

- Open Admin Portal pages, and Customer Portal pages the order's customer has open, refresh when positions change.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `unique_key` (string, required): The shipment's `id` (a hash id), as its answers show it. Its unique key (`shp_...`) also works, but API answers don't include it. Example `MQyJUnd3oty75h`.

## Request body

Content type `application/json`, required.

Fields:

- `current` (string | null, optional): The line you moved (hash id).
- `next` (string | null, optional): The line now after it (hash id), or null.
- `previous` (string | null, optional): The line now before it (hash id), or null.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item/sort' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "current": null,
    "next": null,
    "previous": null
  }'
```

Another example: After moving one line:

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item/sort' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "current": "u8mEG7LHUtS55s",
    "next": "T62Dl1gvIvguYd",
    "previous": "goJhP2gixO3PhU"
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - `data` (array of objects | null, optional): Every line, when positions changed; otherwise null.
    - Each item:
      - `_meta` (object, optional): Read-only details of the line.
      - `auto_invoice_managed` (boolean, optional)
      - `billable_fee_total` (decimal pair, optional): Shipping cost lines only: what is billed (after override, markup or margin); `pricing.product_cost.total` is the cost. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `external_ids` (array of objects, optional): Links to external systems; usually empty.
      - `external_type` (string | null, optional)
      - `from_legacy` (boolean, optional)
      - `id` (string, optional): The shipment line.
      - `is_external` (boolean, optional)
      - `lock_version` (integer, optional): Returned but not checked on shipment lines.
      - `position` (integer, optional)
      - `pricing` (object, optional): For `system`, `_meta.unit_price` is the order line's unit price and `_meta.subtotal` is that price × this shipment line's quantity (`_meta.total` is always 0); for `shipment_cost`, `product_cost` has `override` (always true for lines saved through the API), `total` (the cost), `pricing_mode` and `pricing_mode_total` (decimal pairs at 6 decimal places).
        - `type` (string, optional): One of: `"system"`, `"shipment_cost"`.
      - `product` (object, optional)
        - `_meta` (object, optional): Read-only details; for `order_item`, `parent` describes the order line.
        - `properties` (object, optional): For `order_item`, `id` is the order line; for `shipment_cost`, `name`, `description`, `shipment_package_id`, `shipment_estimate_id`.
        - `type` (string, optional): One of: `"order_item"`, `"shipment_cost"`.
      - `quantity` (object, optional)
        - `type` (string, optional): Always `"unit"`.
        - `total` (decimal pair, optional): The quantity. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `shipment_id` (string, optional): The shipment.
      - `type` (string, optional): Same as `product.type`.
      - `weight` (object, optional): The order line's weight (`_meta.total`, `_meta.unit`).
  - `is_position_sorted` (boolean, optional): Whether any position changed.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "data": [
      {
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "goJhP2gixO3PhU",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 100000,
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 180
            },
            "total": {
              "dp": 0,
              "value": 0
            },
            "unit_price": {
              "dp": 6,
              "value": 30000000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 18500 Hoodie"
            }
          },
          "properties": {
            "id": "OM2IMHqOYFKlP4"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 6
          },
          "type": "unit"
        },
        "shipment_id": "MQyJUnd3oty75h",
        "type": "order_item",
        "weight": {
          "type": "use_system"
        }
      },
      {
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "u8mEG7LHUtS55s",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 200000,
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 300
            },
            "total": {
              "dp": 0,
              "value": 0
            },
            "unit_price": {
              "dp": 6,
              "value": 12500000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 5000 T-shirt"
            }
          },
          "properties": {
            "id": "ZJTJ2uF5dMiArL"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 24
          },
          "type": "unit"
        },
        "shipment_id": "MQyJUnd3oty75h",
        "type": "order_item",
        "weight": {
          "type": "use_system"
        }
      },
      {
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "T62Dl1gvIvguYd",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 300000,
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 300
            },
            "total": {
              "dp": 0,
              "value": 0
            },
            "unit_price": {
              "dp": 6,
              "value": 12500000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 2000 T-shirt"
            }
          },
          "properties": {
            "id": "XznWFuTIgJF9Do"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 24
          },
          "type": "unit"
        },
        "shipment_id": "MQyJUnd3oty75h",
        "type": "order_item",
        "weight": {
          "type": "use_system"
        }
      }
    ],
    "is_position_sorted": true
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your role can't edit this order. Fix: Ask the team owner to adjust your role or assign you to the order.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: The shipment isn't your team's. Fix: Check the id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: An id that isn't a hash id (`validation_failed`). Fix: Send line hash ids.
- `500` A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as `action_not_allowed`; an unexpected failure answers `{"message": "Server Error"}`. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.
  - When: A line unique key (`shpitm_...`) instead of a hash id. Fix: Send the line's `id`.

## Related

- [Update a shipment line](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-update.md): `PUT /v2/api/store/{team_slug}/v2/shipment/item/{unique_key}`
- [List the lines of a shipment](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-index.md): `GET /v2/api/store/{team_slug}/v2/shipment/{unique_key}/item`