Update a shipment line

PUT/v2/api/store/{team_slug}/v2/shipment/item/{unique_key}

v2Operation ID v2_public_shipment_item_update

Changes one shipment line and recalculates the shipment. Send only what you change; returns the action envelope (UPDATED, or NONE when nothing changed).

• An order_item line can change its quantity and position, not the order line it points at.
• A shipment_cost line can change name, description, shipment_package_id, shipment_estimate_id (null unlinks) and its pricing.

Numbers are { value, dp } pairs: value is the number without its decimal point and dp the count of decimal places, so 12.50 is { "value": 1250, "dp": 2 } (or { "value": 125, "dp": 1 }). value is a JSON integer or a digit string, never a float: 12.5 is refused. Quantities take up to 8 decimal places; shipping costs and a pricing mode's rate take 6. More significant decimals than that are a 422, not rounded. Send very large numbers as strings. Answers send prices at the stored scale (6 decimal places), quantities without trailing zeros, and _meta.subtotal (price × quantity) at the combined scale, compacted when it would exceed a safe integer: always read dp.

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

• A line's kind can't change: 422 "Cannot update the product type...".
• A locked Shopify shipment (or one with a broken Shopify link): 422 validation_error "Cannot update Shopify-synced shipment item from API."
• An externally synced line on a draft order: 422 validation_error "Publish this order before updating an externally synced shipment item.", with error.context.reason parent_order_publish_required.
• quantity.type is required whenever you send quantity, and pricing.type whenever you send pricing (422 validation_failed).

Side effects

• Recalculates the shipment's cost and billable fee totals and the order's shipping totals.
• Updates each order line's shipped status (not allocated, partly, fully or over-allocated).
• On an Auto Invoice order, shipping cost lines are mirrored as shipping fees on the managed invoice.
• Open Admin Portal pages refresh, and so do Customer Portal pages the order's customer has open. No webhook or email is sent.

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 line's id (a hash id), as its answers show it. Its unique key (shpitm_...) also works, but API answers don't include it.

  • Example u8mEG7LHUtS55s

Request body

application/json, required.

• positioninteger
• pricingobject

  Shipping cost lines: { type: shipment_cost, product_cost: { total, pricing_mode } }. type is required whenever you send pricing.

• productobject
  Child fields (2)

  • typestringrequired

    Must be the line's current kind.

    • One of: "order_item", "shipment_cost"
  • propertiesobject
• quantityobject
  Child fields (2)

  • typestringrequired

    Required whenever you send quantity.

    • Always "unit"
  • totaldecimal pair

    The new quantity.

    • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.

More examples (1)

Ship 12 instead

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/item/u8mEG7LHUtS55s' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "quantity": {      "total": {        "dp": 0,        "value": 12      },      "type": "unit"    }  }'

Response

200Successful response.

• dataobjectrequired

  What happened, and the line.

  Child fields (5)

  • object_typestring
    • Always "shipment_item"
  • action_performedstring

    NONE when nothing changed.

    • One of: "CREATED", "UPDATED", "DELETED", "NONE"
  • has_changesboolean
  • itemobject

    A shipment line.

    Child fields (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).

  • lock_versionobject

    Lock versions after the change.

    Child fields (2)

    • orderobject

      The order's lock versions: job_lock_version, invoice_lock_version, order_item_lock_version, shipment_lock_version, payment_lock_version, order_lock_version.

    • shipmentobject

      The shipment's lock versions: shipment_item_lock_version, shipment_lock_version.

• 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 line 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

  Validation or a business rule fails.

  Fix

  Read error.message and error.fields.

Notes

• lock_version is returned but not checked on shipment lines: the last write wins.

Related

• GETGet a shipment line/v2/api/store/{team_slug}/v2/shipment/item/{unique_key}
• POSTAdd, change and remove shipment lines at once/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item/bulk

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/item/u8mEG7LHUtS55s' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "pricing": {      "product_cost": {        "pricing_mode": "none",        "total": {          "dp": 2,          "value": 1500        }      },      "type": "shipment_cost"    }  }'

Example response 200

Response

{
  "data": {
    "action_performed": "UPDATED",
    "has_changes": true,
    "item": {
      "auto_invoice_managed": false,
      "external_ids": [],
      "external_type": null,
      "from_legacy": false,
      "id": "u8mEG7LHUtS55s",
      "is_external": false,
      "lock_version": 1730000000000000,
      "position": 100,
      "pricing": {
        "_meta": {
          "subtotal": {
            "dp": 0,
            "value": 150
          },
          "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": 12
        },
        "type": "unit"
      },
      "shipment_id": "MQyJUnd3oty75h",
      "type": "order_item",
      "weight": {
        "type": "use_system"
      }
    },
    "lock_version": {
      "order": {
        "invoice_lock_version": 1730000000000000,
        "job_lock_version": 1730000000000000,
        "order_item_lock_version": 1730000000000000,
        "order_lock_version": 1730000000000000,
        "payment_lock_version": 1730000000000000,
        "shipment_lock_version": 1730000000000000
      },
      "shipment": {
        "shipment_item_lock_version": 1730000000000000,
        "shipment_lock_version": 1730000000000000
      }
    },
    "object_type": "shipment_item"
  },
  "status": 200,
  "success": true
}