> ## Documentation Index > Fetch the complete documentation index at: https://documentation.claruswms.com/llms.txt > Use this file to discover all available pages before exploring further. # Update stock details > Update the details of an existing stock record. Covers descriptive fields, packaging configuration, physical dimensions (including weight, via the nested `unit_dimensions` object), and the tenant-configurable custom fields. This endpoint does not move stock or change quantity — use the dedicated move, transfer, hold and negative adjustment actions for those. Creates an attributes-updated (ATTRUP) transaction for audit purposes. ## Request Structure ```json expandable { "data": { "type": "stocks", "attributes": { "description": "Repackaged pallet", "string1": "REF-00821", "unit_dimensions": { "weight": 15.5, "weight_unit_of_measure": "kilogram" } } } } ``` All attributes are optional — send only the fields you want to change. ## Key Fields | Field | Type | Description | | ------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------- | | `description` | string | Free-text description of the stock line | | `stock_configuration` | string | Packaging configuration: `unit`, `case`, `inner`, `outer` | | `unit_of_measure` | string | Dimension unit: `centimetre`, `metre`, `inch`, `foot`, `millimetre` | | `height`, `width`, `depth` | number | Physical dimensions of the stock line (>= 0) | | `units_per_layer`, `configurations_per_layer`, `units_per_configuration` | number | Layout/packing quantities (>= 0) | | `unit_dimensions` | object | Nested dimensions record where **weight** and other physical measurements are held — see below | | `string1`–`string5` | string | Tenant-configurable custom text fields | | `integer1`–`integer5` | integer | Tenant-configurable custom number fields | | `datetime1`–`datetime5` | string (date-time) | Tenant-configurable custom date/time fields | | `boolean1`–`boolean5` | boolean | Tenant-configurable custom flag fields | ## Setting Weight Weight is stored on the stock's associated dimensions record, not directly on the stock. Set it via the nested `unit_dimensions` object: | Field | Type | Description | | -------------------------------- | ------ | ----------------------------------------------------- | | `weight` | number | Weight of a single unit (>= 0) | | `weight_unit_of_measure` | string | `gram` or `kilogram` | | `packing_weight` | number | Packaging weight of a single unit (>= 0) | | `packing_weight_unit_of_measure` | string | `gram` or `kilogram` | | `volume` | number | Volume of a single unit (>= 0) | | `volume_unit_of_measure` | string | `millilitre`, `litre`, `hectolitre`, `gallon`, `pint` | | `cube` | number | Cubic measurement (>= 0) | | `height`, `length`, `width` | number | Physical dimensions (>= 0) | | `value` | number | Monetary/assessed value (>= 0) | | `unit_of_measure` | string | Dimension unit for the measurements above | | `stock_configuration` | string | Configuration the dimensions apply to | | `packing_description` | string | Free-text packing description | ## OpenAPI ````yaml /api-reference/clarus-api.json patch /api/stocks/{id} openapi: 3.0.3 info: title: ClarusWMS API description: >- REST and GraphQL API for ClarusWMS - a multi-tenanted SaaS warehouse management system. This API provides REST mutation endpoints (POST, PATCH, DELETE) for managing warehouse operations and GraphQL list endpoints for data retrieval. **REST mutations** are available at `/api/*` paths. **GraphQL queries** are available at `/graphql` — each resource has a documented list query. ## Authentication All endpoints require OAuth 2.0 Bearer token authentication. Use the client credentials or authorization code flow to obtain an access token from `https://clarus-api.com/oauth/token`. ## Multi-Tenancy This is a multi-tenant system. Each tenant (subdomain) has isolated data. **You must include the `X-Clarus-Subdomain` header with every request** to specify which tenant you are operating on. ### Required Header | Header | Required | Description | |--------|----------|-------------| | `X-Clarus-Subdomain` | Yes | The subdomain/tenant name identifying which tenant's data to access | **Example:** ``` X-Clarus-Subdomain: acme-warehouse ``` ## Request Format (JSON:API) All REST mutation requests use JSON:API format. Data must be sent within a `data` object containing `type` and `attributes`: ```json { "data": { "type": "resource_name", "attributes": { "field1": "value1" } } } ``` ## GraphQL Queries All data retrieval uses GraphQL at `POST /graphql`. Send a JSON body with `query` and optional `variables`: ```json { "query": "query($code: String) { accounts { all(code: $code) { edges { node { id code name } } } } }", "variables": { "code": "ACME" } } ``` version: 1.0.0 contact: name: Clarus Software url: https://claruswms.com servers: - url: https://clarus-api.com description: Production API security: - BearerAuth: [] ClarusSubdomain: [] tags: - name: Account Warehouses description: >- Account-warehouse association endpoints for managing which accounts can operate in which warehouses - name: Accounts description: Account/customer management endpoints for 3PL client management - name: Addresses description: >- Generic address management endpoints. Town/city is held in `address_3` (passed to couriers as the city). - name: Alternative Code Types description: Alternative code type reference endpoints categorising alternative codes. - name: Alternative Codes description: >- Alternative code management endpoints — additional identifiers (e.g. customer SKUs) attached to products, suppliers, carriers, or warehouses. - name: Automations description: >- Event-driven automation rules that trigger destination actions (API, FTP, email, webhook, file import, AI) when warehouse resource events fire, gated by configurable conditions. - name: Barcode Formats description: Barcode format reference endpoints. - name: Bookings description: >- Booking diary management endpoints for scheduling inbound and outbound dock appointments - name: Carriers description: >- Shipping carrier management endpoints (e.g. DHL, DPD, Royal Mail) used on shipments and goods out orders. - name: 'Carriers: Services' description: >- Carrier service-level endpoints (e.g. Next Day, Express) belonging to a carrier. - name: 'Charging: Baskets' description: >- Charge basket endpoints for collecting and invoicing billable charges against accounts. Each account has one open basket at a time that accumulates charge lines from warehouse operations. Use these endpoints to manage basket lifecycle and generate invoices. - name: 'Charging: Configuration' description: >- Charge configuration endpoints for managing charge cards, charge prices, and charge windows. Charge cards define billing profiles assigned to accounts. Charge prices define pricing rules within a card. Charge windows define recurring billing schedules. - name: 'Charging: Lines' description: >- Charge line management endpoints for individual billable line items within charge baskets. Charge lines are typically created automatically by warehouse operations but can also be created and managed manually. - name: Collection Addresses description: >- Collection address management endpoints. Collection addresses belong to a supplier and are used for inbound collections. - name: Crossdocks description: >- External crossdock management endpoints for direct inbound-to-outbound transfer. - name: Currencies description: Currency management endpoints. Codes are ISO 4217 in lowercase. - name: Custom Carrier Types description: >- Custom carrier type management endpoints, including print layout parameters for label/document templates. - name: Customers description: >- Customer management endpoints. Customers are the end-recipients of goods (distinct from stock accounts). - name: Dashboard Widgets description: >- Dashboard widget management endpoints for creating, updating, and deleting widgets. Each widget is bound to a report query and rendered on dashboards as a configurable chart (bar, line, pie, gauge, etc.). Widgets are placed onto dashboards via the dashboard's widget placement endpoint. - name: Dashboards description: >- Dashboard management endpoints for creating, updating, and deleting dashboards together with the widgets placed on them. Dashboards are role-scoped collections of widgets that render report query data as charts. Use the placement endpoint to atomically replace the widgets shown on a dashboard. - name: Delivery Addresses description: >- Delivery address management endpoints. Delivery addresses belong to an end customer and are used for outbound deliveries. - name: Documents description: >- Document management endpoints for downloading, uploading, and transferring generated files - name: External Entities description: >- External entity endpoints — references to items in external systems (e.g. Shopify products, carriers, shipping rates, warehouses) that are linked to internal ClarusWMS entities via mappings. - name: 'Goods In: Receipts' description: >- Inbound receipt management endpoints for receiving inventory into the warehouse, including the receive task actions used to confirm stock has been received against a receipt - name: 'Goods Out: Orders' description: >- Outbound order management endpoints for creating, updating, and cancelling sales orders - name: 'Goods Out: Pick Lists' description: Pick list management endpoints for updating and removing pick lists - name: 'Goods Out: Processing' description: >- Pick processing endpoints for generating pick lists and order fulfillment workflows - name: Groups description: Group management endpoints for organizing products and locations - name: HHD Flows description: >- Handheld device (HHD) flow definitions — configurable RF/HHD workflows belonging to an HHD implementation. Known internally as RF flows. - name: HHD Users description: >- RF (handheld device) user query endpoints. RF users are dedicated warehouse device operators. - name: Import Configurations description: >- Import configuration endpoints for ingesting external files (CSV, XML, EDI, TXT) and transforming them into warehouse resources via configurable processing flows. - name: Import Templates description: >- Import template management endpoints. Templates map inbound files (matched by filename regexp) onto warehouse resources for an SFTP user. - name: Integrations description: >- Third-party integration management endpoints for ecommerce, carrier, and ERP connections - name: Load Drops description: >- Load drop management endpoints — the individual delivery/collection stops on a load, including stop re-sequencing. - name: Loads description: Load management endpoints for grouping shipments onto vehicles - name: Location Types description: Location type management endpoints for classifying warehouse locations. - name: Locations description: Location management endpoints for warehouse storage locations - name: Mapping Groups description: >- Mapping group endpoints — containers that link external entities to internal entities for a given operation type, plus their field definitions. - name: Mappings description: >- Mapping endpoints — link external entities to internal records within a mapping group. Includes the generic mappings endpoint (for non-integration operation types) and the dedicated endpoints for integration carrier, shipping rate, warehouse, product, and FTP mappings. - name: Order Types description: Order type reference endpoints. - name: Packages description: >- Package endpoints — parcels within a shipment, with dimensions and tracking. - name: Printers description: Cloud Print printer management endpoints for document and label printing. - name: Products description: >- Product management endpoints for creating, updating, and deleting products in the warehouse catalog. ## GraphQL Filtering Guide Products support individual code/barcode filters: `code`, `barcode`, `case_barcode`, `inner_barcode`, `outer_barcode`. Each supports operators: `eq`, `ilike`, `in`, `like`, `between`. When multiple individual filters are used together, they are AND'd (all conditions must match). ### The `all_codes` filter `all_codes` is a **specialized cross-field search** that ORs across all 5 code fields (`code`, `barcode`, `case_barcode`, `inner_barcode`, `outer_barcode`) in a single query. It performs exact matching (IN operator), not partial/ILIKE matching. **When to use `all_codes`:** Only when you have a code or barcode value and don't know which field it belongs to — e.g., a user scans a barcode that could be a unit barcode, case barcode, inner barcode, or outer barcode. **When NOT to use `all_codes`:** When you know which specific code field to search. Use the individual filter instead for better performance and precision. - name: 'Products: Accounts' description: Assignments linking products to stock accounts. - name: 'Products: Materials' description: Bill-of-materials component lines for a parent product. - name: 'Products: Storage Units' description: >- Product storage unit configuration — how a product is packed into storage unit types (per-layer, layers, totals). - name: Putaway Rules description: Per-account putaway ordering rules, with re-sequencing. - name: Reason Codes description: >- Reason code endpoints for stock adjustments, holds, transfers, and stock checks. - name: Replenishment description: Replenishment endpoints for restocking pick faces from bulk storage - name: Report Queries description: Report query management endpoints for custom reporting and data extraction - name: Reports description: >- Report management endpoints for creating report definitions, updating configurations, and generating report output as downloadable documents - name: Roles description: Role and permission management endpoints for access control - name: Scheduled Reports description: >- Scheduled report management endpoints for recurring report delivery via email and FTP - name: SFTP Users description: >- FTP/SFTP user management endpoints for inbound (upload) and outbound (download) file transfer. - name: Shipments description: Shipment management endpoints for carrier integration and parcel tracking - name: Sites description: >- Site management endpoints. Sites group warehouses for multi-site operations. - name: Stock Balances description: >- Aggregated stock balance query endpoints summarising available, allocated, ordered, received, and picked quantities per product/account/warehouse. - name: Stock Checks description: >- Stock check endpoints for counting the products held at a location and reconciling them against the system. A stock check moves through `pending` to either `passed` or `failed`, and failed checks can subsequently be `resolved` with a reason code. - name: Stock Unit Types description: >- Stock unit type reference endpoints (the unit a product's stock is measured in). - name: Stocks description: >- Stock management endpoints for inventory operations including holds, moves, transfers, and adjustments - name: Storage Unit Types description: >- Storage unit type endpoints (pallets, cages, totes) with dimensions and barcode settings. - name: Storage Units description: >- Storage unit management endpoints for containers like pallets, cages, and boxes - name: Subdomains description: >- Tenant (subdomain) management endpoints. Creating a subdomain provisions a new tenant with its own isolated data; the subdomain slug cannot be changed once created. - name: Suppliers description: Supplier management endpoints. Suppliers are the source of inbound goods. - name: Tasks description: >- Task management endpoints for warehouse operations including picking, putaway, receiving, dispatch, and replenishment tasks. Tasks are created automatically by warehouse operations (e.g., goods in receipts, goods out orders, replenishment) and cannot be created or deleted via the API. Use these endpoints to update task attributes, manage task allocation to users, and complete tasks. - name: Tax Rates description: Tax rate management endpoints with percentage component rates. - name: Tax Types description: Tax type management endpoints. - name: Templates description: >- Template management endpoints for creating, updating, and testing Liquid HTML print templates - name: Trailer Types description: Trailer type reference endpoints. - name: Trailers description: Trailer management endpoints for loading and dispatch. - name: Transactions description: >- Read-only stock transaction history query endpoints. Transactions record every stock movement and cannot be created or modified via the API. - name: Users description: User management endpoints for system access and permissions - name: Warehouse Routes description: Per-product warehouse routing priorities, with re-sequencing. - name: Warehouses description: Warehouse management endpoints for multi-site operations paths: /api/stocks/{id}: patch: tags: - Stocks summary: Update stock details description: >- Update the details of an existing stock record. Covers descriptive fields, packaging configuration, physical dimensions (including weight, via the nested `unit_dimensions` object), and the tenant-configurable custom fields. This endpoint does not move stock or change quantity — use the dedicated move, transfer, hold and negative adjustment actions for those. Creates an attributes-updated (ATTRUP) transaction for audit purposes. operationId: updateStock parameters: - name: id in: path required: true description: The unique identifier of the stock record to update schema: type: integer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StockUpdateRequest' example: data: type: stocks attributes: description: Repackaged pallet string1: REF-00821 integer1: 12 unit_dimensions: weight: 15.5 weight_unit_of_measure: kilogram height: 20 width: 30 length: 40 unit_of_measure: centimetre responses: '200': description: Stock updated successfully content: application/json: schema: $ref: '#/components/schemas/DataResponse' example: data: type: stocks id: 123 attributes: status: available quantity: 100 description: Repackaged pallet string1: REF-00821 integer1: 12 height: 20 width: 30 depth: 40 '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: StockUpdateRequest: type: object description: >- Request body for updating the details of a stock record. All attributes are optional — send only the fields to change. required: - data properties: data: type: object required: - type - attributes properties: type: type: string enum: - stocks description: Resource type identifier attributes: type: object description: The stock detail fields to update properties: boolean1: type: boolean nullable: true description: Tenant-configurable custom flag field boolean2: type: boolean nullable: true description: Tenant-configurable custom flag field boolean3: type: boolean nullable: true description: Tenant-configurable custom flag field boolean4: type: boolean nullable: true description: Tenant-configurable custom flag field boolean5: type: boolean nullable: true description: Tenant-configurable custom flag field configurations_per_layer: type: number minimum: 0 description: Number of configurations per layer datetime1: type: string format: date-time nullable: true description: Tenant-configurable custom date/time field datetime2: type: string format: date-time nullable: true description: Tenant-configurable custom date/time field datetime3: type: string format: date-time nullable: true description: Tenant-configurable custom date/time field datetime4: type: string format: date-time nullable: true description: Tenant-configurable custom date/time field datetime5: type: string format: date-time nullable: true description: Tenant-configurable custom date/time field depth: type: number minimum: 0 description: Depth of the stock line, in the given unit_of_measure description: type: string nullable: true description: Free-text description of the stock line height: type: number minimum: 0 description: Height of the stock line, in the given unit_of_measure integer1: type: integer nullable: true description: Tenant-configurable custom number field integer2: type: integer nullable: true description: Tenant-configurable custom number field integer3: type: integer nullable: true description: Tenant-configurable custom number field integer4: type: integer nullable: true description: Tenant-configurable custom number field integer5: type: integer nullable: true description: Tenant-configurable custom number field stock_configuration: type: string enum: - unit - case - inner - outer description: Packaging configuration of the stock line string1: type: string nullable: true description: Tenant-configurable custom text field string2: type: string nullable: true description: Tenant-configurable custom text field string3: type: string nullable: true description: Tenant-configurable custom text field string4: type: string nullable: true description: Tenant-configurable custom text field string5: type: string nullable: true description: Tenant-configurable custom text field unit_dimensions: allOf: - $ref: '#/components/schemas/StockDimensions' description: >- Nested physical dimensions record where weight and other measurements are set unit_of_measure: type: string enum: - centimetre - metre - inch - foot - millimetre description: Unit for the height, width and depth measurements units_per_configuration: type: number minimum: 0 description: Number of units per configuration units_per_layer: type: number minimum: 0 description: Number of units per layer width: type: number minimum: 0 description: Width of the stock line, in the given unit_of_measure example: data: type: stocks attributes: description: Repackaged pallet string1: REF-00821 integer1: 12 unit_dimensions: weight: 15.5 weight_unit_of_measure: kilogram height: 20 width: 30 length: 40 unit_of_measure: centimetre DataResponse: type: object description: Standard successful response wrapper following JSON:API format properties: data: type: object description: The response payload properties: id: type: integer description: Unique identifier of the resource type: type: string description: Resource type name attributes: type: object additionalProperties: true description: Resource attributes StockDimensions: type: object description: >- Physical dimensions of a stock line, including weight. Sent as the nested `unit_dimensions` object when updating stock. All properties are optional. properties: cube: type: number minimum: 0 description: Cubic measurement height: type: number minimum: 0 description: Height, in the given unit_of_measure length: type: number minimum: 0 description: Length, in the given unit_of_measure packing_description: type: string nullable: true description: Free-text description of the packing packing_weight: type: number minimum: 0 description: Weight of the packaging for a single unit packing_weight_unit_of_measure: type: string enum: - gram - kilogram description: Unit for packing_weight stock_configuration: type: string enum: - unit - case - inner - outer description: Packaging configuration the dimensions apply to unit_of_measure: type: string enum: - centimetre - metre - inch - foot - millimetre description: Unit for the height, length and width measurements value: type: number minimum: 0 description: Monetary/assessed value volume: type: number minimum: 0 description: Volume of a single unit volume_unit_of_measure: type: string enum: - millilitre - litre - hectolitre - gallon - pint description: Unit for volume weight: type: number minimum: 0 description: Weight of a single unit weight_unit_of_measure: type: string enum: - gram - kilogram description: Unit for weight width: type: number minimum: 0 description: Width, in the given unit_of_measure example: weight: 15.5 weight_unit_of_measure: kilogram height: 20 width: 30 length: 40 unit_of_measure: centimetre ErrorResponse: type: object description: Standard error response wrapper properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Array of error objects required: - errors Error: type: object description: Detailed error information properties: code: type: integer description: Numeric error code for programmatic handling symbol: type: string description: Symbolic error identifier (e.g., 'product_code_exists') details: type: string description: Human-readable error message source: type: string nullable: true description: Source of the error (service and method name) context: type: object nullable: true additionalProperties: true description: Additional context about the error required: - code - symbol - details responses: Unauthorized: description: Authentication required - provide a valid Bearer token content: application/json: schema: type: object properties: error: type: string description: Error message explaining authentication failure UnprocessableEntity: description: Validation error or business logic error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: oauth2 description: >- OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token. flows: clientCredentials: tokenUrl: https://clarus-api.com/oauth/token scopes: {} authorizationCode: authorizationUrl: https://clarus-api.com/oauth/authorize tokenUrl: https://clarus-api.com/oauth/token scopes: {} ClarusSubdomain: type: apiKey in: header name: X-Clarus-Subdomain description: >- The subdomain/tenant name identifying which tenant's data to access. Required for all API requests. ````