> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # Capture serials for a package > Captures serial numbers for a package line progressively as units are scanned, marking each as allocated; the response's `partial` flag stays true until every unit is captured. Rejects a serial already used elsewhere in the package with 409, already sold on another order with 422 `serial_already_sold`, or belonging to a different product with 422 `serial_product_mismatch`; requires `serials:write` scope. ## OpenAPI ````yaml /openapi.yaml post /serials/capture-partial openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. **Changelog.** Entries are dated and name every published contract whose MEANING moved, not only the ones whose field names changed. The narrative version of the same entries, written for integrators, is published at https://arcuserp.mintlify.app/changelog. **2026-09-22 (planned 2026-09-21), REORDER-BUYER-TRUTH: demand changed what it MEANS on three published contracts, with no field renamed.** An integrator that pins field names sees no breakage and different numbers, which is why this entry exists. - **Demand now counts build consumption.** `demand_avg_per_day` on the public product, kit and inventory-balance objects, and `daily_demand` / `demand_basis` / `net_suggested_qty` on `GET /v1/purchasing/reorder-report`, are composed from fulfilled sales lines PLUS posted `build_consume` inventory draws: each physical decrement of a product counts exactly once. The previous rule adopted an internal-consumption basis only when the sales blend was exactly zero, so a product both sold AND consumed into work orders planned as if the build draws did not exist. Products drawn into work orders move; on one production-shaped dataset five did, the largest from 0.05/day to 14.95/day. - **`demand_basis` now carries four values, not two:** `sales`, `sales_and_builds`, `builds` and `consumption`. A consumer with a two-branch reader (anything that is not `consumption` is `sales`) silently hides the two new ones. - **`current_demand_units` on `GET /v1/inventory/balances/:id` moved, by a second rule.** It counts committed-but-unshipped CUSTOMER demand, and it now counts a kit component's own line rather than its parent kit line, and excludes non-sales documents. On one production dataset 269 of 1,043 balance rows changed, 227 of them downward; the largest single move was 1,941 to 25, on a product whose open PURCHASE order line had been reported as customer demand. Re-baseline anything that alerts or reorders off this field. - `run_rate_30/90/180/365` and `blended_daily` on the same balance object move for the first reason above. - **Added, not changed:** `GET /v1/purchasing/reorder-report` accepts `demand_window` and returns the unit, cover-through and reorder-point-provenance fields documented on that operation; `order_multiple` is accepted and returned on the product-vendor doors. - **Volume note.** The `inventory.low_stock`, `inventory.out_of_stock` and `inventory.back_in_stock` webhook events are population-gated on `on_hand <= reorder_point`, and reorder points move with the demand above, so subscribers should expect a one-time step change in event volume around the release. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /serials/capture-partial: post: tags: - Serials summary: Capture serials for a package description: >- Captures serial numbers for a package line progressively as units are scanned, marking each as allocated; the response's `partial` flag stays true until every unit is captured. Rejects a serial already used elsewhere in the package with 409, already sold on another order with 422 `serial_already_sold`, or belonging to a different product with 422 `serial_product_mismatch`; requires `serials:write` scope. operationId: capturePartialSerialsV1 parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Client-supplied idempotency key (UUID recommended). Same key within 24h returns the cached response. requestBody: required: true content: application/json: schema: type: object required: - package_item_id - product_id properties: package_item_id: type: string format: uuid description: UUID of fulfillment.package_items row to capture against. product_id: type: string format: uuid description: >- UUID of the product. Used for per-product serial_config lookup. order_id: type: string format: uuid nullable: true description: Optional. Parent order UUID for order-state gate validation. package_id: type: string format: uuid nullable: true description: Optional. Parent package UUID. raw_barcodes: type: array items: type: string description: >- Raw scanned strings. The canonical parseScan runs barcode normalization (prefix strip, format parse, lot extraction). Prefer this over serial_numbers[]. serial_numbers: type: array items: type: string description: >- Pre-parsed serial numbers. Use raw_barcodes when possible; serial_numbers bypasses barcode parsing. lot_number: type: string nullable: true description: >- Override lot number. If omitted, parsed from raw_barcodes via parseScan. expiry_date: type: string format: date nullable: true description: >- Override expiry date. If omitted, parsed from raw_barcodes via parseScan. notes: type: string nullable: true description: Optional operator notes stored on the serial row. source: type: string nullable: true description: >- Optional capture source tag (e.g. 'scanner', 'manual', 'api'). responses: '201': description: Partial or complete capture result content: application/json: schema: type: object properties: data: type: object properties: captured_count: type: integer description: Number of serials captured in this call. total_required: type: integer description: Total serial slots required for the package item. remaining: type: integer description: Slots still outstanding after this call. partial: type: boolean description: true when remaining > 0. serials: type: array items: $ref: '#/components/schemas/Serial' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '404': description: package_item_not_found or product_not_found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: duplicate_serial_number content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- serial_already_sold or serial_product_mismatch or serial_release_blocked_order_locked content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: - serials:write components: schemas: Serial: type: object description: > A serial-tracked unit of a product. Created in bulk by generateSerials at purchase-order receipt (status `available`) and walks the lifecycle `available -> allocated -> sold -> returned -> dispositioned`. The `disposition` action records a terminal outcome (restock, write_off, return_to_vendor) and the `link-lot` action attaches the serial to a lot for traceability. Scope: serials:read / serials:write / serials:delete. Rule 23 SSOT: `status` is written only by canonical generateSerials / allocateSerial / consumeSerial / receiveSerialReturn / dispositionSerial. properties: id: type: string format: uuid readOnly: true object: type: string example: serial entity_id: type: string format: uuid readOnly: true product_id: type: string format: uuid serial_number: type: string description: Unique-per-product serial value. 1..255 chars. status: type: string enum: - available - allocated - sold - returned - dispositioned description: Lifecycle state. See enum serial_status. example: available location_id: type: string format: uuid nullable: true description: Layer 4 location scope; serials are warehouse-bound. order_id: type: string format: uuid nullable: true description: Current allocation/sale order, if any. order_item_id: type: string format: uuid nullable: true package_id: type: string format: uuid nullable: true description: Current outbound package, if any. package_item_id: type: string format: uuid nullable: true lot_id: type: string format: uuid nullable: true description: Linked lot for traceability; null if not lot-tracked. lot_number: type: string nullable: true description: Convenience copy of lots.lot_code at link time; lot_id is the FK. expiry_date: type: string format: date nullable: true warranty_start_date: type: string format: date-time nullable: true warranty_end_date: type: string format: date-time nullable: true extended_warranty_end_date: type: string format: date-time nullable: true warranty_status: type: string nullable: true description: active, expired, voided. received_at: type: string format: date-time nullable: true readOnly: true sold_at: type: string format: date-time nullable: true readOnly: true returned_at: type: string format: date-time nullable: true readOnly: true last_scanned_at: type: string format: date-time nullable: true readOnly: true last_order_id: type: string format: uuid nullable: true readOnly: true description: Previous allocation; preserved through return cycles. last_order_item_id: type: string format: uuid nullable: true readOnly: true last_package_id: type: string format: uuid nullable: true readOnly: true last_package_item_id: type: string format: uuid nullable: true readOnly: true notes: type: string nullable: true created_at: type: string format: date-time readOnly: true Error: description: | Alias for ErrorEnvelope. Canonical error response shape used by all API endpoints. Refer to ErrorEnvelope for the full field definition. allOf: - $ref: '#/components/schemas/ErrorEnvelope' ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent__ Test keys use ark_test_ent__. Both are issued per entity via Settings > Developers > API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.