# Change and delete packages at once ```http POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/shipment/{unique_key}/package/bulk ``` - API version: v2 - Operation ID: `v2_public_shipment_package_bulk` - Section: Shipping › [Shipment packages](https://developer.yoprint.com/reference/shipment-packages.md) - Web page: https://developer.yoprint.com/reference/shipment-packages/v2-shipment-package-bulk/ - Authentication: `Authorization: Bearer YOUR_API_KEY` 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_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. The body is an array of objects. Fields: - `action` (string, required): There is no create: packages come from labels. One of: `"update"`, `"delete"`. - `bid` (string, required): Your label for this action. - `shipment_package_id` (string, required): A package of this shipment. - `payload` (object, optional): Required for `update`. - `status` (string, required): Pending, Ready to Ship, Shipped or Delivered. One of: `"pending"`, `"ready-to-ship"`, `"shipped"`, `"delivered"`. ### Example request ```bash 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" } ]' ``` ## Response `200` Successful response. Fields: - `data` (array of objects, required): The packages you touched. - Each item: - `object_type` (string, optional): Always `"shipment_package"`. - `action_performed` (string, optional): One of: `"UPDATED"`, `"DELETED"`. - `bid` (string, optional): Your label from the request. - `has_changes` (boolean, optional) - `item` (object, optional): A package. - `charges` (integer | number | string | null, optional): 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](/concepts/money-and-quantities/). - `created_at` (string (date-time), optional) - `from_address` (any, optional): The address record behind `from_address_id`, or null when it is not set. - `from_address_id` (string | null, optional): Older packages only: the ship-from address record; null otherwise. - `goshippo` (object, optional): Shippo labels only: the Shippo details (shipment, rate, carrier, addresses, parcels). - `address_from` (any, optional): The ship-from address sent to Shippo. - `address_return` (any, optional): The return address sent to Shippo. - `address_to` (any, optional): The ship-to address sent to Shippo. - `carrier_id` (string | null, optional): The Shippo carrier account. - `parcel_id` (string | null, optional): The Shippo parcel. - `parcels` (any, optional): The parcels of the Shippo shipment. - `provider` (string | null, optional) - `provider_image_200` (string | null, optional) - `provider_image_75` (string | null, optional) - `provider_tracking_number` (string | null, optional) - `rate_id` (string | null, optional): The Shippo rate bought. - `shipment_data` (any, optional): The Shippo shipment the rate came from. - `shipment_id` (string | null, optional): The Shippo shipment. - `height` (number | string | null, optional): Parcel size and weight as stored, in `length_unit` and `weight_unit`. Null for external labels. - `id` (string, optional): The package. - `is_master` (boolean, optional): The first package of a label (the others have `parent_id`). - `length` (number | string | null, optional) - `length_unit` (string | null, optional): Shippo labels only, upper case. - `order_external_ids` (array of objects, optional): The order's links to external systems. - `order_external_type` (string | null, optional): `shopify` when the order came from Shopify. - `order_id` (string, optional): The order. - `order_object_type` (string | null, optional) - `order_quote` (boolean, optional) - `order_scoped_id` (string | null, optional) - `parent_id` (string | null, optional): The master package, for the other parcels of a multi-parcel label. - `pdf` (array of objects, optional): Not on external labels: the label file. `label` and `description` are fixed texts that always say 4 x 6, whatever your label size setting. - Each item: - `description` (string, optional) - `label` (string, optional) - `url` (string, optional): For a Shippo label, Shippo's signed link to the label file: don't publish it. - `provider_name` (string | null, optional): The carrier. - `provider_saturday_delivery` (boolean, optional): Shippo labels only (absent on external labels); always false today. - `provider_service_code` (string | null, optional): For external labels, `ups`, `fedex` or `other`. For Shippo labels it may be null: read the service from `provider_service_name`. - `provider_service_name` (string | null, optional) - `provider_shipment_id` (string | null, optional): The Shippo transaction id (Shippo labels). - `provider_tracking_number` (string | null, optional) - `shipment_external_type` (string | null, optional): `shopify` when the shipment is linked to Shopify. - `shipment_has_third_party_fulfilled_items` (boolean, optional) - `shipment_id` (string, optional): The shipment. - `shipment_scoped_id` (string, optional) - `shipment_shopify_sync` (any, optional): Shopify sync state of the shipment. - `status` (string, optional): One of: `"pending"`, `"ready-to-ship"`, `"shipped"`, `"delivered"`. - `to_address` (any, optional): The address record behind `to_address_id`, or null when it is not set. - `to_address_id` (string | null, optional): Older packages only: the ship-to address record; null otherwise. - `type` (string, optional): `goshippo` a label bought through Shippo; `external_label` a label recorded from elsewhere. One of: `"goshippo"`, `"external_label"`, `"single_label"`. - `weight` (number | string | null, optional) - `weight_unit` (string | null, optional): Shippo labels only, upper case. - `width` (number | string | null, optional) - `lock_version` (object, optional): Lock versions after the change (no `order` key here). - `shipment` (object, optional): The shipment's lock versions: `shipment_item_lock_version`, `shipment_lock_version`. - `status` (integer, required) - `success` (boolean, required) Example response: ```json { "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 } ``` ## 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 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. - `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`; `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. ## Related - [Change a package's status](https://developer.yoprint.com/reference/shipment-packages/v2-shipment-package-update.md): `PUT /v2/api/store/{team_slug}/v2/shipment_package/{hash_id}` - [Delete a package (voids its label)](https://developer.yoprint.com/reference/shipment-packages/v2-shipment-package-destroy.md): `DELETE /v2/api/store/{team_slug}/v2/shipment_package/{hash_id}`