Fix up shipment line positions

POST/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item/sort

v2Operation ID v2_public_shipment_item_sort

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_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
unique_keystringrequired
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

application/json, required.

currentstring | null
The line you moved (hash id).
nextstring | null
The line now after it (hash id), or null.
previousstring | null
The line now before it (hash id), or null.

More examples (1)

After moving one line

curl

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

200Successful response.

dataobjectrequired
Child fields (2)
- dataarray of objects | null
  Every line, when positions changed; otherwise null.
  Fields of each item (16)
  - _metaobject
    Read-only details of the line.
  - auto_invoice_managedboolean
  - billable_fee_totaldecimal pair
    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 Money and quantities.
  - external_idsarray of objects
    Links to external systems; usually empty.
  - external_typestring | null
  - from_legacyboolean
  - idstring
    The shipment line.
  - is_externalboolean
  - lock_versioninteger
    Returned but not checked on shipment lines.
  - positioninteger
  - pricingobject
    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).
    Child fields (1)
    typestring
    One of: "system", "shipment_cost"
  - productobject
    Child fields (3)
    _metaobject
    Read-only details; for order_item, parent describes the order line.
    propertiesobject
    For order_item, id is the order line; for shipment_cost, name, description, shipment_package_id, shipment_estimate_id.
    typestring
    One of: "order_item", "shipment_cost"
  - quantityobject
    Child fields (2)
    typestring
    Always "unit"
    totaldecimal pair
    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 Money and quantities.
  - shipment_idstring
    The shipment.
  - typestring
    Same as product.type.
  - weightobject
    The order line's weight (_meta.total, _meta.unit).
- is_position_sortedboolean
  Whether any position changed.
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You 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.
404Not 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.
422The 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.
500A 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.

PUTUpdate a shipment line/v2/api/store/{team_slug}/v2/shipment/item/{unique_key}
GETList the lines of a shipment/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item

Example request

curl

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  }'

Example response 200

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

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com