Add, change and remove shipment lines at once

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

v2Operation ID v2_public_shipment_item_bulk

Applies several line changes to one shipment in one transaction: all of them are saved, or none.

The body is a JSON array of actions, each with your own label bid, an action, a payload for create and update (the same body as the single calls) and cart_item_id for update and delete. YoPrint runs the deletes first, then the creates, then the updates, and recalculates once. Returns every line of the shipment afterwards, with a top-level has_changes. 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

One action per line: a second is 422 cart_item_validation_error with error.context.reason duplicate_item_action and the row's error.bid.
An update or delete of a line that isn't on the shipment is the same code with reason item_not_available (and error.bid). Deleting an already deleted line is skipped.
The validation and Shopify lock rules of the single calls apply to each action (the Shopify lock to every action, synced line or not). Two don't: a shipping cost line for a package that already has one is created again (the single call answers NONE), and the draft-order "Publish this order before ..." rule for externally synced shipments isn't checked.

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

The body is an array of objects.

actionstringrequired
- One of: "create", "update", "delete"
bidstringrequired
Your label for this action, echoed in errors.
cart_item_idstring
The shipment line. Required for update and delete.
payloadobject
Required for create and update.

Response

200Successful response.

dataarray of objectsrequired
Every line of the shipment after the save, one envelope each (deleted lines are absent). has_changes is at the top level, next to data.
Fields of each item (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 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; bulk_validation_payload_failed names the failing item's bid and its fields.
When
A payload fails validation (bulk_validation_payload_failed, with bid and fields), or a rule refuses an action; nothing is saved.
Fix
Fix the named action and resend the whole array.

Notes

Lines you updated say UPDATED; lines you created and lines you didn't touch both say CREATED, and deleted lines are absent. Use the top-level has_changes (next to data) to know whether anything changed.

POSTAdd a line to a shipment/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item
PUTUpdate a shipment line/v2/api/store/{team_slug}/v2/shipment/item/{unique_key}
DELETERemove a line from a shipment/v2/api/store/{team_slug}/v2/shipment/item/{unique_key}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item/bulk' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '[    {      "action": "create",      "bid": "row-1",      "payload": {        "position": 100,        "product": {          "properties": {            "id": "ZJTJ2uF5dMiArL"          },          "type": "order_item"        },        "quantity": {          "total": {            "dp": 0,            "value": 24          },          "type": "unit"        }      }    },    {      "action": "delete",      "bid": "row-2",      "cart_item_id": "goJhP2gixO3PhU"    }  ]'

Example response 200

{
  "data": [
    {
      "action_performed": "CREATED",
      "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": 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"
        }
      },
      "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"
    }
  ],
  "has_changes": 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