Change and delete packages at once

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

v2Operation ID v2_public_shipment_package_bulk

Changes the status of, or deletes, several packages of one shipment in one transaction: all of them, or none. Deletes run first and void Shippo labels as Delete a package does. Returns only the packages you touched, each with its bid and action_performed (UPDATED or DELETED).

Permission

Needs permission to view the shipment's order: the team owner, a role whose Manage Sales Orders permission is "view all", or "view assigned" when you created the order or are assigned to it. Otherwise 403 user_is_not_authorized. Edit rights are not needed, so a role that can only view orders can do this too. This applies even when every action is an update; Change a package's status alone checks no role.

Business rules

One action per package: a second is 422 cart_item_validation_error with error.context.reason duplicate_item_action and error.bid. A package not on this shipment: the same code with reason item_not_available.
The draft rule and the Shopify lock rules of Delete a package apply to each delete; the third-party-fulfilment check does not.

Side effects

Requests Shippo refunds for deleted Shippo labels, in the background. Open Admin Portal pages refresh, and so do Customer Portal pages the order's customer has open.

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
There is no create: packages come from labels.
- One of: "update", "delete"
bidstringrequired
Your label for this action.
shipment_package_idstringrequired
A package of this shipment.
payloadobject
Required for update.
Child fields (1)
- statusstringrequired
  Pending, Ready to Ship, Shipped or Delivered.
  - One of: "pending", "ready-to-ship", "shipped", "delivered"

Response

200Successful response.

dataarray of objectsrequired
The packages you touched.
Fields of each item (6)
- object_typestring
  - Always "shipment_package"
- action_performedstring
  - One of: "UPDATED", "DELETED"
- bidstring
  Your label from the request.
- has_changesboolean
- itemobject
  A package.
  Child fields (36)
  - chargesinteger | number | string | null
    The label cost. For a multi-parcel label every package repeats the rate's full amount: read the master's value and don't add packages up. Null for external labels. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
  - created_atstring (date-time)
  - from_addressany
    The address record behind from_address_id, or null when it is not set.
  - from_address_idstring | null
    Older packages only: the ship-from address record; null otherwise.
  - goshippoobject
    Shippo labels only: the Shippo details (shipment, rate, carrier, addresses, parcels).
    Child fields (13)
    address_fromany
    The ship-from address sent to Shippo.
    address_returnany
    The return address sent to Shippo.
    address_toany
    The ship-to address sent to Shippo.
    carrier_idstring | null
    The Shippo carrier account.
    parcel_idstring | null
    The Shippo parcel.
    parcelsany
    The parcels of the Shippo shipment.
    providerstring | null
    provider_image_200string | null
    provider_image_75string | null
    provider_tracking_numberstring | null
    rate_idstring | null
    The Shippo rate bought.
    shipment_dataany
    The Shippo shipment the rate came from.
    shipment_idstring | null
    The Shippo shipment.
  - heightnumber | string | null
    Parcel size and weight as stored, in length_unit and weight_unit. Null for external labels.
  - idstring
    The package.
  - is_masterboolean
    The first package of a label (the others have parent_id).
  - lengthnumber | string | null
  - length_unitstring | null
    Shippo labels only, upper case.
  - order_external_idsarray of objects
    The order's links to external systems.
  - order_external_typestring | null
    shopify when the order came from Shopify.
  - order_idstring
    The order.
  - order_object_typestring | null
  - order_quoteboolean
  - order_scoped_idstring | null
  - parent_idstring | null
    The master package, for the other parcels of a multi-parcel label.
  - pdfarray of objects
    Not on external labels: the label file. label and description are fixed texts that always say 4 x 6, whatever your label size setting.
    Fields of each item (3)
    descriptionstring
    labelstring
    urlstring
    For a Shippo label, Shippo's signed link to the label file: don't publish it.
  - provider_namestring | null
    The carrier.
  - provider_saturday_deliveryboolean
    Shippo labels only (absent on external labels); always false today.
  - provider_service_codestring | null
    For external labels, ups, fedex or other. For Shippo labels it may be null: read the service from provider_service_name.
  - provider_service_namestring | null
  - provider_shipment_idstring | null
    The Shippo transaction id (Shippo labels).
  - provider_tracking_numberstring | null
  - shipment_external_typestring | null
    shopify when the shipment is linked to Shopify.
  - shipment_has_third_party_fulfilled_itemsboolean
  - shipment_idstring
    The shipment.
  - shipment_scoped_idstring
  - shipment_shopify_syncany
    Shopify sync state of the shipment.
  - statusstring
    One of: "pending", "ready-to-ship", "shipped", "delivered"
  - to_addressany
    The address record behind to_address_id, or null when it is not set.
  - to_address_idstring | null
    Older packages only: the ship-to address record; null otherwise.
  - typestring
    goshippo a label bought through Shippo; external_label a label recorded from elsewhere.
    One of: "goshippo", "external_label", "single_label"
  - weightnumber | string | null
  - weight_unitstring | null
    Shippo labels only, upper case.
  - widthnumber | string | null
- lock_versionobject
  Lock versions after the change (no order key here).
  Child fields (1)
  - 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 view the shipment's order (user_is_not_authorized). Nothing is saved.
Fix
Ask the team owner for permission to view this order, or to be assigned to it.
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 bad status (bulk_validation_payload_failed), a duplicate or foreign package, or a refused delete; nothing is saved.
Fix
Fix the named action and resend the whole array.

PUTChange a package's status/v2/api/store/{team_slug}/v2/shipment_package/{hash_id}
DELETEDelete a package (voids its label)/v2/api/store/{team_slug}/v2/shipment_package/{hash_id}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/package/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": "update",      "bid": "p1",      "payload": {        "status": "shipped"      },      "shipment_package_id": "o6foWpSAayc79D"    },    {      "action": "delete",      "bid": "p2",      "shipment_package_id": "UDsG6yjZAVrRNv"    }  ]'

Example response 200

{
  "data": [
    {
      "action_performed": "UPDATED",
      "bid": "p1",
      "has_changes": true,
      "item": {
        "charges": 12400,
        "created_at": "2026-11-03T15:00:00+00:00",
        "goshippo": {
          "parcels": [
            {
              "distance_unit": "in",
              "height": "4",
              "length": "12",
              "mass_unit": "lb",
              "weight": "2",
              "width": "10"
            }
          ],
          "provider": "USPS",
          "rate_id": "rate_0001"
        },
        "height": "4",
        "id": "o6foWpSAayc79D",
        "is_master": true,
        "length": "12",
        "length_unit": "IN",
        "order_id": "sFbALVSYD55eXe",
        "order_object_type": "sales_order",
        "order_quote": false,
        "order_scoped_id": "SO1001",
        "parent_id": null,
        "pdf": [
          {
            "description": "Postage label individually to be printed 4\" x 6\" label",
            "label": "Postage Label (4 in x 6 in label)",
            "url": "https://example.com/labels/o6foWpSAayc79D.pdf"
          }
        ],
        "provider_name": "USPS",
        "provider_saturday_delivery": false,
        "provider_service_code": null,
        "provider_service_name": "Ground Advantage",
        "provider_shipment_id": "transaction_0001",
        "provider_tracking_number": "9400100000000000000000",
        "shipment_has_third_party_fulfilled_items": false,
        "shipment_id": "MQyJUnd3oty75h",
        "shipment_scoped_id": "SHIP-12",
        "status": "shipped",
        "type": "goshippo",
        "weight": "2",
        "weight_unit": "LB",
        "width": "10"
      },
      "lock_version": {
        "shipment": {
          "shipment_item_lock_version": 1730000000000000,
          "shipment_lock_version": 1730000000000000
        }
      },
      "object_type": "shipment_package"
    },
    {
      "action_performed": "DELETED",
      "bid": "p2",
      "has_changes": true,
      "item": {
        "charges": 12400,
        "created_at": "2026-11-03T15:00:00+00:00",
        "goshippo": {
          "parcels": [
            {
              "distance_unit": "in",
              "height": "4",
              "length": "12",
              "mass_unit": "lb",
              "weight": "2",
              "width": "10"
            }
          ],
          "provider": "USPS",
          "rate_id": "rate_0001"
        },
        "height": "4",
        "id": "UDsG6yjZAVrRNv",
        "is_master": true,
        "length": "12",
        "length_unit": "IN",
        "order_id": "sFbALVSYD55eXe",
        "order_object_type": "sales_order",
        "order_quote": false,
        "order_scoped_id": "SO1001",
        "parent_id": null,
        "pdf": [
          {
            "description": "Postage label individually to be printed 4\" x 6\" label",
            "label": "Postage Label (4 in x 6 in label)",
            "url": "https://example.com/labels/o6foWpSAayc79D.pdf"
          }
        ],
        "provider_name": "USPS",
        "provider_saturday_delivery": false,
        "provider_service_code": null,
        "provider_service_name": "Ground Advantage",
        "provider_shipment_id": "transaction_0003",
        "provider_tracking_number": "9400100000000000000001",
        "shipment_has_third_party_fulfilled_items": false,
        "shipment_id": "MQyJUnd3oty75h",
        "shipment_scoped_id": "SHIP-12",
        "status": "pending",
        "type": "goshippo",
        "weight": "2",
        "weight_unit": "LB",
        "width": "10"
      },
      "lock_version": {
        "shipment": {
          "shipment_item_lock_version": 1730000000000000,
          "shipment_lock_version": 1730000000000000
        }
      },
      "object_type": "shipment_package"
    }
  ],
  "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