Sets, kits and production recipes

Product composition and stock handling describe different decisions. A native recipe defines components, variants, factors and the distribution of order fields. A published stock structure determines which physical goods fulfill that composition.

Publication creates no reservation, consumption or output. Use manufacturing commands for actual assembly, disassembly, consumption, output and scrap. Warehouse manufacturing does not automatically provide the production proof required by a particular dispatch section.

An imported shop group can repeat an existing order line as a virtual head. When one unambiguous real part of that same group is already linked and its shop product, variant identity and quantity match exactly, the head stays grouping context without requiring another catalog article. This recognition adds no physical line, quantity or automatic production job. Different or missing identities, conflicting assignments and unresolved real parts still require clarification. This interpretation does not publish a stock structure or rewrite existing warehouse or production work.

#Endpoints and permissions

• GET /v1/articles/{id}/stock-structure: current definition, optionally selecting variant_id or an owned historical definition_id. Requires products:read.
• GET /v1/articles/{id}/stock-structure/options: active native recipe, current definition, variants and authorized operator, warehouse and condition references. Requires products:read, inventory:read, conditions:read, and the key creator's current product and warehouse viewing permissions.
• GET /v1/articles/{id}/stock-structure/availability: complete virtual sets available in one operator_ref and warehouse_ref, optionally for variant_id. Requires the same read scopes as options.
• POST /v1/stock-structures/commands: publish with stock_structures:write, products:write and current product editing permission.
• POST /v1/stock-structures/commands/preview: the same checks with complete rollback; additionally requires products:read.
• GET /v1/stock-structures/commands/{idempotencyKey}: the original receipt belonging to this API connection; requires products:read.

Test keys cannot publish real definitions or calculate against actual stock. Their options reads do not expose real article or warehouse choices. Use isolated simulator articles and inventory for complete write tests.

#Author a recipe directly

An ERP or authorized AI can create the first recipe without a prior UI edit. Native recipe authoring and publication of warehouse semantics are separate, explicit commands.

• GET /v1/articles/{id}/structure: complete active recipe and its current revision, plus the separately published warehouse definition and its stale flag. Requires products:read. structure: null means there is no active recipe for the selected article/variant.
• GET /v1/articles/{id}/structure/options: owned component products, native variants or compiler-variable choices. Requires products:read. Select section=products|variants|variables; use component_product_id for component variants, optional search, offset and limit (1–100). Follow next_offset until null. The response includes accepted providers and collection bounds.
• POST /v1/product-structures/commands: save or archive a native recipe. Requires both products:write and the separate opt-in product_structures:write, plus the key creator's current product editing permission. Existing product-write keys receive no new recipe authority automatically.
• POST /v1/product-structures/commands/preview: the identical checks with rollback; additionally requires products:read. saved: false is no stored version or command receipt.
• GET /v1/product-structures/commands/{requestId}: original receipt from this API connection, with current products:read authority. A null result leaves the outcome unknown.

Use one durable request_id for the exact intended change. Saving immediately activates a changed native definition; there is no separately stored draft. Identical current content can reuse the existing version, reported as reused: true. The preview reports the actual result_revision and reused decision. The recipe definition retains the same field names and meanings as the native editor:

max_route_targets: 500 in the options response means the total target assignments across every rule, not 500 targets per rule or 500 distinct slots. Each rule permits at most 100 unique slot IDs, all referring to the recipe's at most 100 parts. Reusing one slot in two rules consumes two target assignments. Five rules targeting 100 slots each consume 500 assignments; adding another single-target rule exceeds the total even though there are only six rules. An exclude rule submitted with targetSlotIds: [] contributes one rule and zero targets. These limits are separate from shop bundle-rule limits.

Every route target must be a slot in the submitted complete recipe. Slot identifiers remain stable across deliberate edits. These component factors are integer counts; warehouse balances elsewhere use exact decimal strings. Unknown or foreign products/variants are unavailable and cannot be introduced through a field route.

{
  "request_id": "e2000000-0000-4000-8000-000000000001",
  "operation": {
    "kind": "save",
    "definition": {
      "parentProductId": "e2000000-0000-4000-8000-000000000002",
      "parentProductVariantId": null,
      "expectedRevision": 0,
      "fulfillmentMode": "atomic",
      "parts": [{
        "slotId": "e2000000-0000-4000-8000-000000000003",
        "productId": "e2000000-0000-4000-8000-000000000004",
        "productVariantId": null,
        "label": "Cup",
        "quantity": 2,
        "sortOrder": 0
      }],
      "routes": []
    }
  }
}

Replace the synthetic article references with actual choices and create the request/slot UUIDs for your intention. Archive uses operation: {kind: "archive", product_id, structure_id, expected_revision}. Active physical work or a warehouse publication can prevent archiving. A new recipe does not rewrite frozen orders, manufacturing evidence or historical shipments. If stock_publication_stale is true, read and explicitly publish the new warehouse definition before starting work that requires the current recipe.

After an uncertain response, read the receipt with the original request_id or repeat the identical command. A new request ID is a new intention, even when identical current content happens to reuse a version. Historical profile versions may recover only a proven identical original command, never admit a new edit.

#Publish a definition

1. Create and activate the native recipe with /v1/product-structures/commands, product management or the shared product structure tools.
2. Read options for the article and optional variant. Retain the active structure_version_id, every slot_id and the current published revision (0 if unpublished).
3. Choose a mode and a condition policy for every component. Preview the command, then submit the exact reviewed request.

{
  "idempotency_key": "e1000000-0000-4000-8000-000000000001",
  "product_id": "e1000000-0000-4000-8000-000000000002",
  "variant_id": null,
  "structure_version_id": "e1000000-0000-4000-8000-000000000003",
  "expected_revision": 0,
  "mode": "virtual_set",
  "component_conditions": [
    {
      "slot_id": "e1000000-0000-4000-8000-000000000004",
      "policy": { "kind": "certified_released" }
    }
  ],
  "output_condition_policy": { "kind": "certified_released" },
  "reason": "Ship individual components from inspected stock"
}

Include every slot of the active flat recipe exactly once. Factors are positive whole-piece counts taken from that native recipe; the command cannot overwrite them with different values. Stock quantities are exact decimal strings with at most six decimal places. available_sets is a whole count represented as a string. The documented unit is piece. Independently stocked variants require an unambiguous physical SKU.

The response includes definition_id, revision, each component's actual stock article, and frozen factors and policies. A virtual_set header has stock_product_id: null. For a physical kit or production recipe, that field identifies the actual finished stock article.

#Choose condition policies deliberately

certified_released accepts explicitly released conditions and excludes unclassified legacy stock. This policy is deliberately broad: subsequent released versions can also qualify. Use selected when eligibility must remain limited to particular condition versions and operators:

{
  "kind": "selected",
  "condition_refs": ["e1000000-0000-4000-8000-000000000005"]
}

Obtain references from the authorized options response. Each represents an immutable condition version of a warehouse operator. New versions are not automatically added to a concrete selection. Quarantined or blocked goods do not become eligible through an arbitrary supplied reference. An explicit selection can include the clearly identified legacy condition; doing so does not retrospectively certify inspection.

Component policies govern eligible input goods. output_condition_policy governs the eligibility of finished physical goods for orders. Real output may initially enter quarantine; physical receiving and release are separate decisions.

#Availability without counting shared stock twice

A set needs two pieces of one SKU in slot A and three pieces of that same SKU in slot B. With 20 free eligible pieces, four complete sets are available. Both slots share the same 20 pieces. Do not add their individual eligible_free values.

The calculation considers reservations, exclusive holds, storage location, current partner releases and condition policies. Overlapping condition selections also share physical supply. Calculation stays within one operator warehouse; goods from separate warehouses are not silently combined.

This response is a current observation, not a reservation. The same components may support different offered sets. Their individually reported availability is not a simultaneous promise; an actual allocation is required to bind goods.

#Dispatch, production and returns

Orders retain their frozen composition. Physical components have their own component_id; reservations, production evidence and package contents remain bound to those actual quantities. The commercial header quantity is not the sum of components.

A shipment may contain only some required components. Its proven complete header quantity can therefore be 0 despite real component movement. Read /v1/orders/{id}/dispatches, including components and package contents, for these cases. A later shipment can supply missing components and prove a positive complete header quantity. Earlier shipment receipts are not rewritten. The older shipment-only reader may reject such a case with shipment_components_require_dispatches.

A virtual-set return refers to an actually shipped physical component from the return-source choices. It never receives a virtual header as stock. A physical kit remains a real finished article; disassembly requires its proven original manufacturing composition, not a guess based on today's active recipe.

#Conflicts, receipts and limits

The active native recipe and expected publication revision are checked at write time. On conflict, read again and review a new deliberate decision. Existing physical goods, physical history, unfinished manufacturing or bound orders can prevent a mode change. Changing modes cannot reinterpret historical goods.

Persist the complete request and idempotency_key before sending. After an uncertain response, read the original receipt or retry the exact original request. The receipt remains bound to that API connection and its unchanged arguments. A later current definition does not replace the historical reply. A null lookup does not prove failure.

Options are bounded to 100 components, 250 variants, 100 operators, 1,000 visible condition versions and 250 warehouses. Exceeding a bound is rejected explicitly rather than silently truncated. Nested virtual sets and unresolved variants are not supported physical component sources. External shop bundles must preserve their actually imported commercial lines; a missing external header line is never invented from component totals.

When a shop supplies real commercial child lines and only a logical header without an order line, each child keeps its original order-line identifier and already-total quantity. Its stock factor is 1; the logical header creates no extra demand. A group with both a commercial header and commercial children remains ambiguous and is rejected for allocation until its source structure is clarified. A physical-kit definition cannot silently become shipping of its recipe inputs.