> ## 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. # Create stock (positive adjustment) > Add stock the system does not know about, such as stock found during a count or opening stock for a new warehouse. Each line is created as loose stock, on one storage unit, or across several new storage units. Every stock line created is recorded as a positive adjustment transaction. To increase the quantity of an existing stock record instead, use `POST /api/positive_adjustments/extra_stock_on_storage_unit_found`. ## Request Structure ```json expandable { "account_id": 1, "description": "Stock found during cycle count", "stock_date": "2026-10-17T09:30:00Z", "stocks": [ { "location_id": 100, "product_id": 123, "quantity": 6 }, { "location_id": 101, "product_id": 123, "quantity": 24, "storage_unit_quantity": 1, "storage_unit_type_id": 2 } ], "warehouse_id": 1, "reason_code_id": 4 } ``` ## Key Fields | Field | Required | Description | | - | - | - | | `account_id` | Yes | Stock account (owner of the stock) for every line | | `warehouse_id` | Yes | Warehouse for every line | | `stock_date` | Yes | ISO 8601 date-time used as the FIFO date of every line | | `description` | Yes | Free-text reason for the adjustment (audit trail) | | `stocks` | Yes | Lines to create: `product_id`, `location_id` and `quantity` are required on each | | `reason_code_id` | No | `positive_adjustment` reason code; required if the account enforces one | ## Storage Units Each line's storage unit fields decide how it is created: | `storage_unit_quantity` | Other fields | Result | | - | - | - | | Omitted or `0` | - | Loose stock at the location, no storage unit | | `1` | `storage_unit_reference` matches an existing non-dispatched storage unit | Stock is added to that storage unit | | `1` | `storage_unit_reference` is new | A storage unit is created with that reference | | `1` | `storage_unit_type_id` only | A storage unit is created with a reference generated from the type's sequence | | Greater than `1` | `storage_unit_type_id` | That many storage units are created, each holding `quantity` | Send the same `storage_unit_reference` on several lines to build a mixed storage unit. ## Behavior * All lines are created in a single transaction: if any line fails, nothing is created. * New stock is always created with status `AVAILABLE`. * Products with full serial number tracking need one serial number per unit, and cannot use `storage_unit_quantity` greater than 1. * The response has no body (204). To read the created stock, query `/graphql#ListStocks` (for example filtered by location and product). ## Error Codes | Code | Symbol | Description | | - | - | - | | 228 | incorrect\_reason\_code\_type | Reason code is not a `positive_adjustment` reason code | | 230 | reason\_code\_missing | No reason code was sent but the account enforces positive adjustment reason codes | | 335 | receipt\_line\_storage\_unit\_quantity\_must\_eq\_one\_with\_full\_tracking\_of\_serial\_numbers | `storage_unit_quantity` greater than 1 sent for a serial-tracked product | | 339 | serial\_numbers\_quantity\_is\_not\_equal\_to\_stock\_quantity | Serial-tracked product sent with a number of serial numbers that does not match the quantity | | 341 | serial\_numbers\_already\_in\_stock | A serial number is already in stock for the product | | 342 | serial\_numbers\_not\_unique | The same serial number was sent more than once | ## OpenAPI ````yaml /api-reference/clarus-api.json post /api/positive_adjustments/create_stocks 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/positive_adjustments/create_stocks: post: tags: - Stocks summary: Create stock (positive adjustment) description: >- Add stock the system does not know about, such as stock found during a count or opening stock for a new warehouse. Each line is created as loose stock, on one storage unit, or across several new storage units. Every stock line created is recorded as a positive adjustment transaction. To increase the quantity of an existing stock record instead, use `POST /api/positive_adjustments/extra_stock_on_storage_unit_found`. operationId: positiveAdjustmentCreateStocks requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StockPositiveAdjustmentCreateStocksRequest' example: account_id: 1 description: Stock found during cycle count stock_date: '2026-10-17T09:30:00Z' stocks: - location_id: 100 product_id: 123 quantity: 6 - location_id: 101 product_id: 123 quantity: 24 storage_unit_quantity: 1 storage_unit_type_id: 2 warehouse_id: 1 reason_code_id: 4 responses: '204': description: Stock created successfully '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: StockPositiveAdjustmentCreateStocksRequest: type: object description: >- Request body for creating new stock through a positive adjustment. The body is sent as plain JSON, not wrapped in a JSON:API `data` envelope. required: - account_id - description - stock_date - stocks - warehouse_id properties: account_id: type: integer allOf: - $ref: '#/components/schemas/AccountId' description: Stock account that owns all the stock created by this request description: type: string description: Free-text reason for the adjustment, recorded on each transaction reason_code_id: type: integer nullable: true description: >- ID of a reason code with `reason_type` `positive_adjustment`, recorded on the transaction for the audit trail. Required when the stock's account has `enforce_positive_adjustment_reason_code` enabled. stock_date: type: string format: date-time description: >- ISO 8601 date-time used as the FIFO date of every stock line created (e.g. `2026-10-17T09:30:00Z`) stocks: type: array minItems: 1 description: >- The stock lines to create. Each line is created as loose stock, on one storage unit, or on several storage units depending on its storage unit fields. items: $ref: '#/components/schemas/StockPositiveAdjustmentLine' warehouse_id: type: integer allOf: - $ref: '#/components/schemas/WarehouseId' description: Warehouse all the stock is created in example: account_id: 1 description: Stock found during cycle count stock_date: '2026-10-17T09:30:00Z' stocks: - location_id: 100 product_id: 123 quantity: 6 - location_id: 101 product_id: 123 quantity: 24 storage_unit_quantity: 1 storage_unit_type_id: 2 warehouse_id: 1 reason_code_id: 4 AccountId: type: integer description: >- Stock account ID - the owner of the stock. Accounts represent 3PL clients or stock owners, not end customers. example: 1 StockPositiveAdjustmentLine: type: object description: >- One line of stock to create in a `create_stocks` positive adjustment. The account, warehouse and FIFO date come from the top level of the request, not from the line. required: - location_id - product_id - quantity 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 nullable: true 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 nullable: true height: type: number minimum: 0 description: Height of the stock line, in the given unit_of_measure nullable: true 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 location_id: type: integer allOf: - $ref: '#/components/schemas/LocationId' description: Location the stock is created at number_of_layers: type: integer nullable: true minimum: 0 description: Number of layers on the stock line product_id: type: integer allOf: - $ref: '#/components/schemas/ProductId' description: Product the stock is for quantity: type: number minimum: 0 exclusiveMinimum: true description: >- Quantity of the product to add. When `storage_unit_quantity` is greater than 1 this is the quantity on EACH storage unit, not the total. serial_numbers: type: array items: type: string description: >- Serial numbers to assign to the new stock. Required when the product has full serial number tracking, in which case exactly one serial number per unit must be sent (quantity rounded up). Serial numbers must be unique and must not already be in stock for the product. stock_configuration: type: string enum: - unit - case - inner - outer description: Packaging configuration of the stock line nullable: true storage_unit_quantity: type: integer nullable: true minimum: 0 description: >- Number of storage units to create for this line. Omit (or send 0) for loose stock with no storage unit; send 1 to place the stock on a single storage unit; send more than 1 to create that many storage units, each holding `quantity`. Values above 1 require `storage_unit_type_id` and are not allowed for products with full serial number tracking. storage_unit_reference: type: string nullable: true description: >- Reference of the storage unit to place the stock on (only used when `storage_unit_quantity` is 1). If a non-dispatched storage unit with this reference already exists the stock is added to it; otherwise a new storage unit is created with this reference. Send the same reference on several lines to build a mixed storage unit. storage_unit_type_id: type: integer nullable: true description: >- Storage unit type for new storage units. When `storage_unit_reference` is omitted, references are generated from this type's sequence (e.g. `PAL000123`). 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_of_measure: type: string enum: - centimetre - metre - inch - foot - millimetre description: Unit for the height, width and depth measurements nullable: true units_per_layer: type: number minimum: 0 description: Number of units per layer nullable: true width: type: number minimum: 0 description: Width of the stock line, in the given unit_of_measure nullable: true example: location_id: 100 product_id: 123 quantity: 24 storage_unit_quantity: 1 storage_unit_type_id: 2 WarehouseId: type: integer description: Warehouse ID - the physical warehouse location for operations example: 1 ErrorResponse: type: object description: Standard error response wrapper properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Array of error objects required: - errors LocationId: type: integer description: Location ID - reference to a storage location within a warehouse example: 100 ProductId: type: integer description: Product ID - reference to a product in the warehouse catalog example: 123 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. ````