> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/product-stock/partially-update-a-product-stock.md).

# Partially update a product stock

Updates one or more fields of a product-stock record. Only the fields included in the request body are changed; everything left out keeps its current value.

The `product` cannot be changed: including a `product` that differs from the record's current one is rejected with `406 Not Acceptable`.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Product Stock","description":"Administrative endpoints for **product stock** — the primary on-hand quantity of a product in the catalog. There is exactly one product-stock record per product (`product` is a one-to-one reference), holding the sellable `stock` count, the unit of measure, and a counter used to reconcile stock reported by an external system (ERP) against quantities already sold locally.\n\nAdditional per-seller stock (one record per stock list / data source) is managed separately through the `extra_product_stock` endpoints.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of product-stock records.\n* Filter by product (including nested product filters) and by modification date.\n* Order results with the `sort` parameter, as described under **Filtering & Ordering**.\n\n**2. Full CRUD**\n* Create a stock record for a product.\n* Retrieve a single record.\n* Fully or partially update a record.\n* Delete a record. `DELETE` is a **soft delete** — the row is kept and its `stock` is set to `0`.\n\n**3. Bulk Upsert**\n* Create or update many records in one request through `POST /product_stock/bulk_upsert/`.\n\n## Product Stock Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `pk` | integer | The unique identifier of the record. Read-only; supplying it in a request body has no effect. |\n| `product` | integer | The identifier of the product this stock belongs to. Required on create. One record per product; the product cannot be changed on update. |\n| `stock` | integer | The sellable quantity. A non-negative integer; defaults to `0`. |\n| `unit_type` | string | The unit of measure — `qty` (quantity) or `kg` (kilogram). Defaults to `qty`. |\n| `extra_field` | object | Free-form JSON for extra data. Optional; defaults to an empty object. |\n| `sold_quantity_unreported` | integer | The quantity sold locally but not yet reflected in the externally reported stock. A non-negative integer; normally managed internally. See **Stock Reconciliation**. |\n| `modified_date` | string | Read-only. ISO 8601 timestamp of the last modification. |\n\n## Stock Reconciliation\n\nWhen stock is written for a product, the incoming quantity is reconciled against what has already been sold locally: the stored `stock` becomes `max(incoming_stock - sold_quantity_unreported, 0)`. This keeps a feed of ERP-reported stock from overselling items that have already left the shelf but have not yet been reported back to the ERP.\n\n## Deleting a Product Stock\n\n> **Important:** `DELETE` never removes the record. Its `stock` is set to `0` and the row is kept, so the product simply becomes out of stock and can be restocked with a later update.\n\n## Filtering & Ordering\n\nThe list endpoint accepts these filters:\n\n| Parameter | Match |\n|-----------|-------|\n| `product` | The related product by identifier. |\n| `product__id`, `product__sku`, `product__base_code`, `product__product_type`, … | Nested product filters — any filter exposed by the product filter set, addressed with the `product__` prefix. |\n| `modified_date__gt`, `modified_date__gte`, `modified_date__lt`, `modified_date__lte` | Modification-date range comparisons (ISO 8601). |\n\nThere is no plain `modified_date` equality filter. Results can be ordered with the `sort` parameter on the record's fields (e.g. `-modified_date`); prefix a field with a hyphen for descending order.\n\n## Dynamic Settings & Environment Variables\n\nThe write endpoints are affected by one dynamic setting.\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `LIST_SIMPLE_INSTEAD_OF_META` | boolean | `false` | When `true`, writing stock for a **simple**-type product (via create, update, or bulk upsert) triggers a recomputation of that product's listable status after the stock is saved, so a product that just went in or out of stock is re-evaluated for storefront listing. It does not change any request or response field, and it has no effect on read operations or on non-simple products. |\n\n**Environment variables:** No environment variables are read directly by these endpoints. The default of `LIST_SIMPLE_INSTEAD_OF_META` is taken from the Django setting of the same name (falling back to `false`)."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"ProductStockPatchRequest":{"type":"object","description":"The body of a product-stock partial update request. Only the fields included in the body are changed; every field is optional.","properties":{"product":{"type":"integer","description":"Including a `product` that differs from the record's current one is rejected. Omitting it keeps the current product."},"stock":{"type":"integer","minimum":0,"description":"The sellable quantity. Reconciled against `sold_quantity_unreported` on write."},"unit_type":{"allOf":[{"$ref":"#/components/schemas/ProductStockUnitType"}],"description":"The unit of measure."},"extra_field":{"type":"object","description":"Free-form JSON for extra data."},"sold_quantity_unreported":{"type":"integer","minimum":0,"description":"The quantity sold locally but not yet reported."}}},"ProductStockUnitType":{"type":"string","description":"The unit of measure of a stock quantity.","enum":["qty","kg"]},"ProductStock":{"type":"object","description":"A product-stock record — the primary on-hand quantity of a single product.","properties":{"pk":{"type":"integer","readOnly":true,"description":"The unique identifier of the record."},"product":{"type":"integer","description":"The identifier of the product this stock belongs to. One record per product."},"stock":{"type":"integer","minimum":0,"description":"The sellable quantity. A non-negative integer."},"unit_type":{"$ref":"#/components/schemas/ProductStockUnitType"},"extra_field":{"type":"object","description":"Free-form JSON for extra data."},"sold_quantity_unreported":{"type":"integer","minimum":0,"description":"The quantity sold locally but not yet reflected in the externally reported stock."},"modified_date":{"type":"string","format":"date-time","readOnly":true,"description":"ISO 8601 timestamp of the last modification."}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"ProductStockBusinessError":{"type":"object","description":"Returned when a product-stock request is valid in form but violates a business rule of the stock service.\n\nCodes raised by these endpoints:\n* `product_stock_400_1` — the product of an existing record was changed, or a bulk upsert element was missing `product` or malformed.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}},"responses":{"ProductStockValidationError":{"description":"The request contains invalid or missing data — for example a missing `product`, a `product` that does not exist or already has a stock record, a negative `stock`, or an unrecognised `unit_type`. The response names the field the complaint belongs to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ProductStockNotFound":{"description":"No product-stock record exists with the given identifier. Zeroed-out records are still retrievable, so this answer means the record does not exist at all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ProductStockBusinessError":{"description":"The request is well-formed but violates a business rule of the stock service — the `product` of an existing record was changed, or an element of a bulk upsert was missing `product` or was otherwise malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductStockBusinessError"}}}}}},"paths":{"/product_stock/{id}/":{"patch":{"tags":["Product Stock"],"operationId":"partialUpdateProductStock","summary":"Partially update a product stock","description":"Updates one or more fields of a product-stock record. Only the fields included in the request body are changed; everything left out keeps its current value.\n\nThe `product` cannot be changed: including a `product` that differs from the record's current one is rejected with `406 Not Acceptable`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductStockPatchRequest"}}}},"responses":{"200":{"description":"The updated product-stock record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductStock"}}}},"400":{"$ref":"#/components/responses/ProductStockValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/ProductStockNotFound"},"406":{"$ref":"#/components/responses/ProductStockBusinessError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/product-stock/partially-update-a-product-stock.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
