--- title: "Batch update Container" method: PATCH path: "/api/v3/container:batch-update" tags: ["Container"] --- # Batch update Container `PATCH /api/v3/container:batch-update` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/container:batch-update` - Auth: HTTP bearer Batch update Container synchronously in one transaction. Maximum 25 items per request. ## Request body - object - `items` UpdateContainerInputWithPathParams[], required - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving. - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`. - `checkoutRecord` CheckoutRecordInput - `assigneeId` string, nullable - `comment` string, nullable - `status` 'AVAILABLE' | 'RESERVED' | 'CHECKED_OUT', required - `id` string, required - `name` string - `parentStorageId` string, nullable - `projectId` string, nullable - `quantity` MeasurementInput - `unitId` string, nullable, required - `value` number, double, nullable, required - `restrictedSamplePartyIds` string[]: API IDs of the restricted sample parties (a party is a Benchling user, Organization, or Team). Limited to 100 items. - `restrictionStatus` 'RESTRICTED' | 'UNRESTRICTED' | 'NOT_APPLICABLE' - `role` ExperimentalRoleInput - `group` integer, required - `primaryRole` 'CONTROL' | 'SAMPLE' | 'BLANK' | 'STANDARD', required - `subrole` string, nullable, required - `sampleOwnerIds` string[]: API IDs of the sample owners (an owner is a Benchling user, Organization, or Team). Limited to 100 items. - `schemaFields` object - `shouldRemoveBarcodes` boolean: Whether to remove the barcode of the container. Only allowed when archiving the container. ## Response `200` OK - ContainerBatchupdateResponse200 - `items` Container[], required - `__typename` string - `archiveReason` string, nullable - `archived` boolean - `barcode` string, nullable - `checkoutRecord` CheckoutRecord: Tracks the checkout status of an inventory item such as a Container. When laboratory samples need to be temporarily removed from storage (e.g., for an experiment), users can check them out, optionally adding a comment and assigning responsibility to a user or team (see Assignee). The record captures when the status was last modified. This enables sample tracking workflows and prevents conflicts when multiple users need access to the same samples. - `__typename` string - `assignee` union: Represents who can be assigned to work on a Legacy Request. An assignee can be either an individual `User` or a `Team`. When a team is assigned, any member of that team can fulfill the request. - object: Team variant - `__typename` 'Team', required: Discriminator value: Team - `id` string, api_id - object: User variant - `__typename` 'User', required: Discriminator value: User - `id` string, api_id - `comment` string, nullable - `modifiedAt` string, datetime, nullable - `status` 'AVAILABLE' | 'RESERVED' | 'CHECKED_OUT' - `contents` ContainerContent[] - `__typename` string - `concentration` Measurement: Represents a quantity with an associated unit of measurement within Benchling's inventory system. Measurements are used throughout inventory to track container volumes, sample masses, concentrations, and other quantitative values. Each Measurement pairs a numeric value with a Unit (see Unit) to provide context-aware quantity handling. For example, a container might have a Measurement of 500 uL for its volume. Unlike ContainerQuantity which provides a simpler representation, Measurement supports the full Unit system with dimensional conversions. - `__typename` string - `unit` UnitRef - `__typename` string - `id` string, api_id - `value` number, double, nullable - `createdAt` string, datetime: When the container was first filled with this entity. - `entity` EntityRef - `__typename` string - `id` string, api_id - `modifiedAt` string, datetime: When the entity was last added to this container or the concentration was last changed. - `coordinates` GridCoordinates: Read model representing a fillable position in a box or plate. - `__typename` string - `column` integer: The 0-indexed column index of the position - `index` integer: The 1-indexed position determined by counting across rows. For example, for a six-well plate: +---+---+---+ | 1 | 2 | 3 | +---+---+---+ | 4 | 5 | 6 | +---+---+---+ - `position` string: The alphanumeric position, where rows are indexed alphabetically and columns are indexed numerically, starting from "A1" - `row` integer: The 0-indexed row index of the position - `createdAt` string, datetime - `expirationInfo` ExpirationInfo: Provides expiration tracking for inventory items such as containers and their contents. The expirationDate may be explicitly set on the container or inherited from the stored entity's properties. The isExpired flag is a computed convenience field that returns true if the current date is past the expiration date. Items without an expiration date are considered non-expiring (isExpired returns false). - `__typename` string - `expirationDate` string, datetime, nullable: Expiration date of the item, potentially inherited from the contents or overridden. - `isExpired` boolean: Whether the item is past its expiration date. Items without an expiration date return False. - `gridNumber` number, double, nullable: Please use coordinates.index - `gridPosition` string, nullable: Please use coordinates.position - `id` string - `modifiedAt` string, datetime - `name` string - `parentStorage` union: A union of inventory item types that can serve as parent storage for containers. A Box stores containers in a grid layout. A MatrixPlate places containers into grid positions much like a Box, while a WellPlate's wells are themselves modeled as containers that are permanently part of the plate structure. A Location represents hierarchical storage such as freezers, shelves, or rooms. This union enables the parentStorage field on Container to reference any valid storage parent. - object: Box variant - `__typename` 'Box', required: Discriminator value: Box - `id` string, api_id - object: Location variant - `__typename` 'Location', required: Discriminator value: Location - `id` string, api_id - object: MatrixPlate variant - `__typename` 'MatrixPlate', required: Discriminator value: MatrixPlate - `id` string, api_id - object: WellPlate variant - `__typename` 'WellPlate', required: Discriminator value: WellPlate - `id` string, api_id - `parentStorageSchema` union: A union of schema types corresponding to storage items. Each storage type (Box, WellPlate, MatrixPlate, Location) has an associated schema that defines its structure and metadata. This union is used to reference the schema of a container's parent storage. - object: BoxSchema variant - `__typename` 'BoxSchema', required: Discriminator value: BoxSchema - `id` string, api_id - object: LocationSchema variant - `__typename` 'LocationSchema', required: Discriminator value: LocationSchema - `id` string, api_id - object: MatrixPlateSchema variant - `__typename` 'MatrixPlateSchema', required: Discriminator value: MatrixPlateSchema - `id` string, api_id - object: WellPlateSchema variant - `__typename` 'WellPlateSchema', required: Discriminator value: WellPlateSchema - `id` string, api_id - `project` ProjectRef - `__typename` string - `id` string, api_id - `quantity` Measurement: Represents a quantity with an associated unit of measurement within Benchling's inventory system. Measurements are used throughout inventory to track container volumes, sample masses, concentrations, and other quantitative values. Each Measurement pairs a numeric value with a Unit (see Unit) to provide context-aware quantity handling. For example, a container might have a Measurement of 500 uL for its volume. Unlike ContainerQuantity which provides a simpler representation, Measurement supports the full Unit system with dimensional conversions. - `__typename` string - `unit` UnitRef - `__typename` string - `id` string, api_id - `value` number, double, nullable - `role` ExperimentalRole: Represents the complete experimental designation of a well or container within an assay, combining a primary role (see PrimaryExperimentalRole), replicate group number, and optional subrole. The group field identifies replicate sets: wells with the same primary role and group number are treated as technical replicates for statistical analysis. The subrole field provides additional categorization for controls (e.g., POSITIVE, NEGATIVE, MAXIMUM, MINIMUM); only CONTROL primary roles may have subroles. ExperimentalRole is used in plate-based workflows to define experimental layouts (see PlateMapPosition) and annotate wells in FixedPlate and Container objects. - `__typename` string - `group` integer: Role group (aka replicate id) - `primaryRole` 'CONTROL' | 'SAMPLE' | 'BLANK' | 'STANDARD': Primary role - `subrole` string, nullable: Subrole, used to differentiate different sub types of a role (e.g. positive control) - `schema` ContainerSchemaRef - `__typename` string - `id` string, api_id - `creator` PrincipalRef - `__typename` string - `id` string, api_id - `schemaFields` SchemaFieldValue[], nullable - `__typename` string - `fieldDefinition` SchemaFieldDefinitionRef - `__typename` string - `id` string, api_id - `id` string - `linkedEntityId` string, nullable - `value` union: Types of values that Benchling can interpret. - object: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). - `__typename` 'ArrayValue', required: Discriminator value: ArrayValue - `value` SingularBenchlingValue[] - union: A union of value types that can appear as elements within an ArrayValue. Identical to BenchlingValue but excludes ArrayValue to prevent nesting. Keep in sync with BenchlingValue. - … - object: A type that represents boolean values. - `__typename` 'BooleanValue', required: Discriminator value: BooleanValue - `value` boolean: The boolean value. - object: A type that represents datetime values. - `__typename` 'DateTimeValue', required: Discriminator value: DateTimeValue - `value` string, datetime: The datetime value with UTC as the timezone. - object: A type that represents date values. - `__typename` 'DateValue', required: Discriminator value: DateValue - `value` string, date: The date value. - object: A type that represents decimal value as strings. - `__typename` 'DecimalValue', required: Discriminator value: DecimalValue - `numericValue` number, double, nullable: Deprecated. The float representation of the decimal value. - `value` string, nullable: The decimal value in a string representation - object: A type that represents integer values. - `__typename` 'IntegerValue', required: Discriminator value: IntegerValue - `value` integer: The integer value. - object: A type that represents JSON values. - `__typename` 'JsonValue', required: Discriminator value: JsonValue - `value` union: The JSON value. - object - string[] - string - number, double - boolean - object: A type that represents a list of links to other objects. - `__typename` 'ObjectLinkListValue', required: Discriminator value: ObjectLinkListValue - `value` LinkableDomainObject[]: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. - union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - … - object: A type that represents links to other objects. - `__typename` 'ObjectLinkValue', required: Discriminator value: ObjectLinkValue - `value` union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - object: AaSequence variant - … - object: Attachment variant - … - object: Box variant - … - object: Container variant - … - object: CustomEntity variant - … - object: DnaOligo variant - … - object: DnaSequence variant - … - object: DropdownOption variant - … - object: Entry variant - … - object: Inaccessible variant - … - object: Location variant - … - object: MatrixPlate variant - … - object: Mixture variant - … - object: Molecule variant - … - object: OligoConjugate variant - … - object: OligoDuplex variant - … - object: Protein variant - … - object: Result variant - … - object: RnaOligo variant - … - object: RnaSequence variant - … - object: WellPlate variant - … - object: A type that represents text (string) values with an associated URL. - `__typename` string, required - `url` string: The URL associated with the value. Please use `TextValue` if you don't want a URL. - `value` string: The text value. It may or may not be an empty string. - object: A type that represents text (string) values. - `__typename` string, required - `value` string: The text value. It may or may not be an empty string. - `testOrders` string, uri, nullable: All test orders associated with the container. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-11-05** `3873a10bf7b8`: 1 breaking, 1 info - added `subschema #1, subschema #8, subschema #9` to the `items/items/schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` - removed `subschema #1, subschema #8, subschema #9` from the `items/items/schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` - **2026-11-05** `c9f087b98b8b`: 1 info - added the new optional request property `items/items/shouldRemoveBarcodes` [Operation history](https://skmtc.dev/benchling/apis/benchling-api/changes/api/v3/container:batch-update/patch.md) --- [API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/3873a10bf7b8?raw)