--- updatedAt: 2026-07-03T13:03:56.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # 🔒 Create production V3 This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues. This endpoint requires the following scopes: `production:create`. Create a new production. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Xentral Business Documents API v3", "description": "The Xentral Business Documents API v3 for working with sales orders, offers, invoices, credit notes, delivery notes, return orders, purchase orders, proforma invoices and productions.\n\nIndividual endpoints marked as *Beta* may still change without prior notice — see the respective endpoint descriptions.\n\nRequest payloads may contain properties that an endpoint does not define; these are ignored rather than rejected. Nothing is stored for them and no error is returned, so check the response body to confirm which values were actually applied.", "contact": { "name": "API Support", "url": "https://xentral.com", "email": "api@xentral.com" }, "version": "0.2.0" }, "servers": [ { "url": "https://{xentralId}.xentral.biz", "description": "Your xentral instance", "variables": { "xentralId": { "default": "my-company", "description": "Your Xentral instance ID" } } }, { "url": "https://{domain}", "description": "Xentral with a custom domain", "variables": { "domain": { "default": "demo.xentral.com", "description": "Your Xentral custom domain" } } } ], "components": { "schemas": { "ActivityLogEntry": { "required": [ "message", "causer", "causedAt" ], "properties": { "message": { "type": "string", "example": "Invoice released" }, "causer": { "type": [ "string", "null" ], "example": "John Doe" }, "causedAt": { "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } }, "type": "object", "additionalProperties": false }, "Address": { "required": [ "id", "createdAt", "updatedAt" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "type": "string", "example": "42" }, "isDeleted": { "description": "Flagged if the entry was deleted.", "type": "boolean", "example": false } }, "type": "object" } ] }, "AddressReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the address", "type": "string", "example": "13" } }, "type": "object" }, "CreateProductionData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/HasPreferredWarehouse" }, { "properties": { "address": { "$ref": "#/components/schemas/AddressReferenceData" }, "project": { "$ref": "#/components/schemas/ProjectReferenceData" }, "salesOrder": { "$ref": "#/components/schemas/SalesOrderReferenceData" }, "productionStartDate": { "description": "Production start date", "type": "string", "format": "date", "example": "2024-01-15" }, "productionEndDate": { "description": "Production end date", "type": "string", "format": "date", "example": "2024-01-20" }, "produceProduct": { "$ref": "#/components/schemas/ProductReferenceData" }, "produceQuantity": { "description": "Quantity of the product to produce", "type": "number", "format": "float", "example": 100 }, "batch": { "description": "Batch number for the goods this production produces. Used when the production is completed, unless the completion gives a different one, and only booked into batch stock if the produced product is managed in batches.", "type": "string", "maxLength": 255, "example": "CH-2026-07" }, "bestBeforeDate": { "description": "Best-before date for the goods this production produces. Used when the production is completed, unless the completion gives a different one, and only booked if the produced product carries a best-before date.", "type": "string", "format": "date", "example": "2027-01-31" }, "functionTest": { "description": "Whether function testing is required", "type": "boolean", "example": true }, "createSerialNumbers": { "description": "Whether to create serial numbers", "type": "boolean", "example": false }, "recordSubSerialNumbers": { "description": "Whether to record sub-serial numbers", "type": "boolean", "example": false }, "materialReservation": { "description": "Material reservation method", "type": "string", "enum": [ "instant", "onRelease", "onStart" ], "example": "onRelease" }, "materialRetrieval": { "description": "Material retrieval method", "type": "string", "enum": [ "single", "collective" ], "example": "collective" }, "documentDate": { "description": "Document creation date", "type": "string", "format": "date", "example": "2024-01-10" }, "stockRetrievalDate": { "description": "Stock retrieval date", "type": "string", "format": "date", "example": "2024-01-25" }, "stockProvisioningDate": { "description": "Stock provisioning date", "type": "string", "format": "date", "example": "2024-01-20" }, "bodyText": { "description": "Body text for production notes", "type": "string", "example": "Additional production notes" }, "internalDesignation": { "description": "Internal designation for production", "type": "string", "example": "Internal production reference" }, "internalComment": { "description": "Internal comment for production", "type": "string", "example": "Internal production comment" }, "printSettings": { "description": "Print settings for the production", "properties": { "showTaskDescription": { "description": "Whether to show task descriptions when printing", "type": "boolean", "example": true } }, "type": "object" }, "resolveMultiLevelBOM": { "description": "Whether to resolve multi-level bill of materials", "type": "boolean", "example": false }, "tags": { "description": "Tags assigned to the production. The passed list replaces the currently assigned tags; omit the property to leave them unchanged. Each entry references an existing tag by `id` or names a tag by `title`, which is created if it does not exist; exactly one of the two.", "type": "array", "items": { "$ref": "#/components/schemas/TagReferenceData" } } }, "type": "object" } ] }, "HasPreferredWarehouse": { "properties": { "preferredWarehouse": { "description": "The preferred warehouse. When omitted, it is derived from the project of the document: on create from the resolved project, on an address change from the project of the new business partner. Productions take the production warehouse of the project, all other documents its default warehouse.", "properties": { "id": { "description": "Preferred warehouse ID", "type": "string", "example": "42" } }, "type": "object" } }, "type": "object" }, "Money": { "description": "Money", "properties": { "amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "currency": { "description": "Currency", "type": "string", "example": "EUR" } }, "type": "object", "example": { "amount": "13.37", "currency": "EUR" }, "additionalProperties": false }, "Product": { "description": "A product. Sub-resources are embedded on demand via ?include=.", "required": [ "id" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProjectReferenceResource" }, { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "Product ID.", "type": "string", "pattern": "[0-9]+", "example": "50123" }, "uuid": { "description": "Stable UUID of the product.", "type": [ "string", "null" ], "example": "c7b3f0e2-1a2b-4c3d-8e9f-0a1b2c3d4e5f" }, "number": { "description": "SKU / product number.", "type": [ "string", "null" ], "example": "SKU-1001" }, "name": { "description": "Product name (primary language).", "type": [ "string", "null" ], "example": "Widget Pro" }, "description": { "description": "Product description (primary language).", "type": [ "string", "null" ], "example": "A high-quality widget." }, "ean": { "description": "European Article Number.", "type": [ "string", "null" ], "example": "4001234567890" }, "unit": { "description": "Unit of measure.", "type": [ "string", "null" ], "example": "piece" }, "customsTariffNumber": { "description": "Customs tariff number.", "type": [ "string", "null" ], "example": "85340011" }, "countryOfOrigin": { "description": "Country of origin (ISO 3166-1 alpha-2).", "type": [ "string", "null" ], "example": "DE" }, "merchandiseGroup": { "description": "Merchandise group of the product, used for account mapping and number ranges. By default only the ID is returned; use include=merchandiseGroup for the full merchandise group.", "example": { "id": "7" }, "anyOf": [ { "$ref": "#/components/schemas/ProductMerchandiseGroup" }, { "properties": { "id": { "type": "string", "pattern": "[0-9]+" } }, "type": "object" }, { "type": "null" } ] }, "defaultSupplier": { "description": "Default supplier address. By default only the ID is returned; use include=defaultSupplier for the full address.", "example": { "id": "880" }, "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "properties": { "id": { "type": "string", "pattern": "[0-9]+" } }, "type": "object" }, { "type": "null" } ] }, "isStockItem": { "description": "Whether the product is stock-managed.", "type": "boolean", "example": true }, "variantOf": { "description": "Parent product if this is a variant.", "properties": { "id": { "description": "Parent product ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "50000" } }, "isMatrixProduct": { "description": "Whether the product is a matrix (variant parent) product.", "type": "boolean", "example": false }, "manufacturer": { "description": "Manufacturer name.", "type": [ "string", "null" ], "example": "Dell" }, "manufacturerProductNumber": { "description": "Product number assigned by the manufacturer.", "type": [ "string", "null" ], "example": "MFR-77" }, "manufacturerUrl": { "description": "Manufacturer URL.", "type": [ "string", "null" ], "example": "https://dell.com" }, "regionOfOrigin": { "description": "German federal state of origin (two-digit code; 99 = foreign origin).", "type": [ "string", "null" ], "enum": [ "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "99" ], "example": "08" }, "internalComment": { "description": "Internal comment (not shown to customers).", "type": [ "string", "null" ], "example": "Handle with care" }, "measurements": { "description": "Physical measurements.", "properties": { "weight": { "description": "Weight in kg.", "type": "number", "example": 1.2 }, "netWeight": { "description": "Net weight in kg.", "type": "number", "example": 1 }, "length": { "description": "Length in cm.", "type": "number", "example": 30 }, "width": { "description": "Width in cm.", "type": "number", "example": 20 }, "height": { "description": "Height in cm.", "type": "number", "example": 2 } }, "type": "object", "example": { "weight": 1.2, "netWeight": 1, "length": 30, "width": 20, "height": 2 }, "additionalProperties": false }, "minimumStockLevel": { "description": "Minimum stock level.", "type": "integer", "example": 0 }, "minimumOrderQuantity": { "description": "Minimum order quantity.", "type": "integer", "example": 0 }, "taxRate": { "description": "VAT rate tier applied to the product.", "type": "string", "enum": [ "standard", "reduced", "exempt" ], "example": "standard" }, "serialNumberTracking": { "description": "Serial-number tracking mode.", "type": "string", "enum": [ "none", "stockGenerated", "stockOriginal", "trackOriginal" ], "example": "none" }, "hasBatches": { "description": "Whether batch/charge management is active.", "type": "boolean", "example": false }, "hasBestBeforeDate": { "description": "Whether best-before-date tracking is active.", "type": "boolean", "example": false }, "hasBillOfMaterials": { "description": "Whether the product has a bill of materials.", "type": "boolean", "example": false }, "isAssembledJustInTime": { "description": "Whether the BOM is assembled just-in-time.", "type": "boolean", "example": false }, "isProductionProduct": { "description": "Whether the product is produced in-house.", "type": "boolean", "example": false }, "isExternallyProduced": { "description": "Whether the product is produced externally.", "type": "boolean", "example": false }, "isCustomProduct": { "description": "Whether the product is a custom/individual product.", "type": "boolean", "example": false }, "isShippingCostsProduct": { "description": "Whether the product represents shipping costs.", "type": "boolean", "example": false }, "allowPurchaseFromAllSuppliers": { "description": "Whether purchasing from all suppliers is allowed.", "type": "boolean", "example": false }, "isStockTakingDisabled": { "description": "Whether stock-taking is disabled for the product.", "type": "boolean", "example": false }, "isInCatalog": { "description": "Whether the product is included in the catalog. The catalog name and text are per language and part of the texts include.", "type": "boolean", "example": false }, "printSettings": { "description": "Document print settings applied when the product appears on a document.", "properties": { "withoutPrices": { "description": "Hide the price on documents (PDF).", "type": "boolean", "example": false }, "withoutJustInTimeItems": { "description": "Hide just-in-time component items on documents.", "type": "boolean", "example": false } }, "type": "object", "example": { "withoutPrices": false, "withoutJustInTimeItems": false }, "additionalProperties": false }, "isDeleted": { "description": "Whether the product is soft-deleted. Deleted products are excluded by default; request them explicitly via the isDeleted filter.", "type": "boolean", "example": false }, "isDisabled": { "description": "Whether the product is internally blocked (disabled). Disabled products are excluded by default; request them explicitly via the isDisabled filter.", "type": "boolean", "example": false }, "disabledReason": { "description": "Reason/message for the block.", "type": [ "string", "null" ], "example": null }, "ageRating": { "description": "Age rating (DHL identity check).", "type": [ "string", "null" ], "example": null }, "isDiscountProduct": { "description": "Whether the product is a discount product.", "type": "boolean", "example": false }, "discountPercentage": { "description": "Discount percentage.", "type": "number", "example": 0 }, "stockTaking": { "description": "Stock-taking valuation.", "properties": { "hasStockTakingValue": { "description": "Whether a stock-taking value is set.", "type": "boolean", "example": false }, "stockTakingValue": { "description": "Stock-taking value.", "type": "number", "example": 0 } }, "type": "object", "example": { "hasStockTakingValue": false, "stockTakingValue": 0 }, "additionalProperties": false }, "calculatedPurchasePrice": { "description": "Calculated purchase price.", "properties": { "hasCalculatedPurchasePrice": { "description": "Whether a calculated purchase price is used.", "type": "boolean", "example": false }, "price": { "$ref": "#/components/schemas/Money" } }, "type": "object", "example": { "hasCalculatedPurchasePrice": false, "price": { "amount": "0.0000", "currency": "EUR" } }, "additionalProperties": false }, "calculatoryPurchasePriceSettings": { "description": "Calculatory purchase-price recalculation configuration.", "properties": { "addPurchasePriceToCalculationTrigger": { "description": "Trigger that adds the purchase price to the calculation.", "type": "string", "enum": [ "manual", "onPurchaseOrderCompletion", "onGoodsReceipt" ], "example": "manual" }, "calculatoryPurchasePriceRecalculationMethod": { "description": "Method used to recalculate the calculatory purchase price.", "type": "string", "enum": [ "allRecordedPurchasesWeightedAverage", "latestPurchaseOrdersWeightedAverage", "movingAverage" ], "example": "allRecordedPurchasesWeightedAverage" } }, "type": "object", "example": { "addPurchasePriceToCalculationTrigger": "manual", "calculatoryPurchasePriceRecalculationMethod": "allRecordedPurchasesWeightedAverage" }, "additionalProperties": false }, "salesChannelDefaults": { "description": "Default sales-channel settings of the product. They apply in every sales channel that does not use individual settings (see the salesChannels include).", "properties": { "isVisible": { "description": "Whether the product is visible in the sales channels. While false, the product is hidden from every sales channel. This flag has no per-channel override: it also applies to channels that use individual settings.", "type": "boolean", "example": true }, "isSoldOut": { "description": "Whether the product is marked as sold out in the sales channels. This flag has no per-channel override: it applies to every sales channel, including ones that use individual settings.", "type": "boolean", "example": false }, "isStockNumberSyncActive": { "description": "Whether the stock quantity is automatically transferred to the sales channels.", "type": "boolean", "example": false }, "isRemainingQuantity": { "description": "Whether the product is switched to unavailable in the sales channels once the remaining stock is sold off.", "type": "boolean", "example": false }, "suggestedRetailPrice": { "description": "Suggested retail price (gross RRP) shown in the sales channels. Only used by some online shops.", "type": [ "string", "null" ], "example": "19.99" }, "stockQuantityFormula": { "description": "The rule that decides which stock quantity the sales channels are told instead of the actual stock, such as \"L:Main - RES\". A plain number is a valid rule.", "type": [ "string", "null" ], "example": "L:Main - RES" }, "deliveryTime": { "description": "Delivery time text shown in the sales channels.", "type": [ "string", "null" ], "example": "2-3 days" }, "createNewProductNumberDuringImport": { "description": "Whether a new product number is generated when the sales channel imports the product as an option product, e.g. for customised products.", "type": "boolean", "example": false }, "stockCorrectionValue": { "description": "Correction value added to the stock quantity reported to the sales channels; negative values reduce the reported stock. 0 means no correction.", "type": "integer", "example": -5 } }, "type": "object", "example": { "isVisible": true, "isSoldOut": false, "isStockNumberSyncActive": false, "isRemainingQuantity": false, "suggestedRetailPrice": "19.99", "stockQuantityFormula": "L:Main - RES", "deliveryTime": null, "createNewProductNumberDuringImport": false, "stockCorrectionValue": 0 }, "additionalProperties": false }, "noDiscountAllowed": { "description": "No automatic discounts allowed for this product.", "type": "boolean", "example": false }, "isCommissionBlocked": { "description": "Whether commission is blocked for this product.", "type": "boolean", "example": false }, "noCashDiscountAllowed": { "description": "No cash discount allowed when selling.", "type": "boolean", "example": false }, "suppressSalesPriceWarning": { "description": "Suppress the warning when the product is added to a document without a sales price.", "type": "boolean", "example": false }, "requiresIdentityCheck": { "description": "Requires an identity check (DHL).", "type": "boolean", "example": false }, "isDevice": { "description": "Marked as a device in the customer address.", "type": "boolean", "example": false }, "isServiceItem": { "description": "Whether the product is marked as a service item.", "type": "boolean", "example": false }, "isFee": { "description": "Whether the product represents a fee.", "type": "boolean", "example": false }, "isService": { "description": "Whether the product is a service rather than a physical good.", "type": "boolean", "example": false }, "hasRawMaterialList": { "description": "Whether the product has a raw-material list.", "type": "boolean", "example": false }, "hasDailyPrices": { "description": "Whether daily prices are enabled for the product.", "type": "boolean", "example": false }, "documentQuantityFormula": { "description": "Formula used to compute the quantity on documents.", "type": [ "string", "null" ], "example": null }, "documentPriceFormula": { "description": "Formula used to compute the price on documents.", "type": [ "string", "null" ], "example": null }, "noticeText": { "description": "Product-specific notice text.", "type": [ "string", "null" ], "example": "Not sold individually" }, "defaultStorageLocation": { "description": "Default storage bin (shelf short name).", "type": [ "string", "null" ], "example": "A-01-02" }, "individualTaxRate": { "description": "Individual tax rate in percent; null when the standard rate applies.", "type": [ "number", "null" ], "example": null }, "salesPrices": { "description": "Sales prices (include=salesPrices).", "type": "array", "items": { "$ref": "#/components/schemas/ProductSalesPrice" } }, "purchasePrices": { "description": "Purchase prices (include=purchasePrices).", "type": "array", "items": { "$ref": "#/components/schemas/ProductPurchasePrice" } }, "texts": { "description": "Language/shop texts (include=texts). Contains both the stored overrides and the base texts of the product itself.", "type": "array", "items": { "$ref": "#/components/schemas/ProductText" } }, "categories": { "description": "Product categories (category-tree nodes) the product is assigned to (include=categories).", "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "externalReferences": { "description": "External product numbers (include=externalReferences).", "type": "array", "items": { "$ref": "#/components/schemas/ProductExternalReference" } }, "deliveryThresholds": { "description": "Per-country delivery-threshold tax rules (include=deliveryThresholds).", "type": "array", "items": { "$ref": "#/components/schemas/ProductDeliveryThreshold" } }, "calculationItems": { "description": "Cost-calculation line items (include=calculationItems).", "type": "array", "items": { "$ref": "#/components/schemas/ProductCalculationLineItemResource" } }, "parts": { "description": "Bill-of-materials components (include=parts).", "type": "array", "items": { "$ref": "#/components/schemas/ProductBomItem" } }, "usedIn": { "description": "Products whose bill of materials contains this product (include=usedIn).", "type": "array", "items": { "$ref": "#/components/schemas/ProductBomItem" } }, "packagingUnits": { "description": "Packaging units of the product (include=packagingUnits).", "type": "array", "items": { "$ref": "#/components/schemas/ProductPackagingUnit" } }, "crossSelling": { "description": "Cross-selling linked products (include=crossSelling).", "type": "array", "items": { "$ref": "#/components/schemas/ProductCrossSelling" } }, "customFields": { "description": "Custom fields with their values, labels and per-language translations (include=customFields).", "type": "array", "items": { "required": [ "key" ], "properties": { "key": { "type": "string", "example": "customField1" }, "label": { "type": "string", "example": "Material" }, "type": { "description": "The data type of the custom field. Legacy custom fields always report `string`.", "type": "string", "enum": [ "string", "integer", "float", "date", "datetime", "boolean", "translatable_string", "object" ], "example": "string" }, "value": { "description": "The custom field value. Its JSON type depends on the sibling `type` field: `string`/`translatable_string` and `date`/`datetime` (as ISO 8601 strings) are strings, `integer`/`float` are numbers, `boolean` is a boolean, and `object` is a JSON object.", "example": "Aluminium", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "null" } ] }, "translations": { "description": "Per-language label and value overrides for languages other than DE.", "type": "array", "items": { "required": [ "language" ], "properties": { "language": { "description": "ISO 639-1 language code.", "type": "string", "example": "en" }, "label": { "type": [ "string", "null" ], "example": "Material" }, "value": { "type": [ "string", "null" ], "example": "Aluminum" } }, "type": "object", "additionalProperties": false } } }, "type": "object", "additionalProperties": false } }, "workInstructions": { "description": "Work instructions (include=workInstructions).", "type": "array", "items": { "$ref": "#/components/schemas/ProductWorkInstruction" } }, "variants": { "description": "Variant child products (include=variants).", "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" } }, "options": { "description": "Matrix options of this product with the values they can take (include=options). Only a matrix product holds options; for a variant the list is empty.", "type": "array", "items": { "$ref": "#/components/schemas/ProductOption" } }, "optionValues": { "description": "The option values this product carries as a variant, one per option of its matrix product (include=optionValues). Empty for a product that is not a variant.", "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionValue" } }, "tags": { "description": "Assigned tags (include=tags).", "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "properties": { "description": "Assigned property values (include=properties).", "type": "array", "items": { "$ref": "#/components/schemas/ProductProperty" } }, "salesChannels": { "description": "Per-sales-channel settings (include=salesChannels).", "type": "array", "items": { "$ref": "#/components/schemas/ProductSalesChannelSetting" } }, "media": { "description": "Images & documents (include=media).", "type": "array", "items": { "$ref": "#/components/schemas/ProductMedia" } }, "storageLocations": { "description": "Where the product physically lies: one entry per storage location, batch and best-before date, with serial numbers aggregated, plus the aggregates over them. Only present when requested, and only on single-record endpoints: via include=storageLocations on the single-product endpoint, or via include=materials.product.storageLocations on a single production, where the production document prints the same breakdown for each material. On a production the physical fields are served and the `available` and `sellable` aggregates are omitted, because each material would pay for them separately. Reading it always requires the product:read scope, and it costs several warehouse round trips per product - which is why no list endpoint offers it. A parts-list product assembled just in time lies in no storage location and its `quantity` is always \"0\"; for the units its components allow to be assembled, per warehouse and pooled, ask GET /api/v3/products/{id}/stock.", "properties": { "quantity": { "description": "Total physical stock on hand across all warehouses. Always \"0\" for a product assembled just in time.", "type": "string", "example": "120.0000" }, "available": { "description": "Physically available stock (on hand minus pending quality-control deferrals), summed across all storage locations. For a product assembled just in time: the whole units its components still allow to be assembled across all warehouses once what they have committed elsewhere is deducted - the same figure GET /api/v3/products/{id}/stock reports as producibleAfterCommitments.", "type": "string", "example": "118.0000" }, "sellable": { "description": "Sellable stock after subtracting open sales-order and reservation commitments, summed across all storage locations. For a product assembled just in time: the whole units its components still allow to be assembled across all warehouses once what they have committed elsewhere is deducted, which makes it the same figure as available here.", "type": "string", "example": "100.0000" }, "storageLocations": { "description": "Stock per storage location. Each entry is a unique combination of storage location, batch and best-before date, with serial numbers aggregated.", "type": "array", "items": { "required": [ "storageLocation", "quantity" ], "properties": { "storageLocation": { "properties": { "id": { "type": "string", "pattern": "[0-9]+", "example": "42" }, "name": { "type": [ "string", "null" ], "example": "A-01-02" }, "warehouse": { "properties": { "id": { "type": "string", "pattern": "[0-9]+", "example": "1" }, "name": { "type": "string", "example": "Main warehouse" } }, "type": [ "object", "null" ], "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "quantity": { "description": "Stock quantity at this location for the batch/best-before combination.", "type": "string", "example": "30.0000" }, "batch": { "description": "Batch/charge number, or null when the product is not batch-tracked.", "type": [ "string", "null" ], "example": "LOT-42" }, "bestBeforeDate": { "description": "Best-before date, or null when not tracked.", "type": [ "string", "null" ], "format": "date", "example": "2026-12-31" }, "serialNumbers": { "description": "Serial numbers present at this location; empty when the product is not serial-tracked.", "type": "array", "items": { "type": "string" }, "example": [ "SN-1", "SN-2" ] } }, "type": "object", "additionalProperties": false } } }, "type": "object", "additionalProperties": false } }, "type": "object" } ] }, "ProductBomItem": { "description": "A bill-of-materials line. The linked product is the component for include=parts and the parent (assembly) for include=usedIn.", "required": [ "id", "quantity", "type", "order", "product" ], "properties": { "id": { "description": "Bill-of-materials line ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "quantity": { "description": "Quantity of the component per parent.", "type": "number", "format": "float", "example": 4 }, "type": { "description": "Type of the bill-of-materials line.", "type": "string", "enum": [ "purchasePart", "informationPart", "providedPart" ], "example": "purchasePart" }, "reference": { "description": "Free-text reference of the line.", "type": [ "string", "null" ], "example": "R7" }, "order": { "description": "The ordering sequence of the line within the bill of materials.", "type": "integer", "example": 10 }, "product": { "description": "The linked product: the component for include=parts, the parent (assembly) for include=usedIn.", "properties": { "id": { "description": "Product ID.", "type": "string", "pattern": "[0-9]+" }, "name": { "description": "Product name.", "type": [ "string", "null" ] }, "number": { "description": "Product SKU.", "type": [ "string", "null" ] } }, "type": "object", "example": { "id": "50123", "name": "Screw M4", "number": "SKU-9" } } }, "type": "object", "additionalProperties": false }, "ProductCalculationLineItemResource": { "description": "A product calculation line item", "required": [ "id", "designation", "costType", "includeInCalculation", "totalCost", "archived" ], "properties": { "id": { "description": "ID of the line item.", "type": "string", "example": "33" }, "designation": { "description": "Designation of the line item. Free text, but commonly one of the known standard designations.", "example": "purchaseCosts", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "additionalCosts", "productionCosts", "purchaseCosts", "additionalParts", "freightCosts", "additionalFreightCosts" ] } ] }, "date": { "description": "Date of the cost.", "type": [ "string", "null" ], "format": "date", "example": "2026-01-01" }, "costType": { "description": "Type of the cost.", "type": "string", "enum": [ "oneTime", "perPiece", "perLot", "purchase", "oldMovingAverage" ], "example": "purchase" }, "includeInCalculation": { "description": "Whether the line item is included in the purchase price calculation.", "type": "boolean", "example": true }, "totalCost": { "$ref": "#/components/schemas/Money", "description": "Total cost of the line item." }, "forQuantity": { "description": "Quantity for the total cost.", "type": [ "integer", "null" ], "example": 10 }, "costPerUnit": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Cost per unit." }, { "type": "null" } ], "description": "Cost per unit." }, "purchaseOrder": { "description": "The purchase order connected to this line item.", "properties": { "id": { "description": "Purchase order ID.", "type": "string", "example": "1234" } }, "type": [ "object", "null" ], "example": { "id": "1234" } }, "archived": { "description": "Whether the line item is archived.", "type": "boolean", "example": false }, "editor": { "description": "The editor who created/modified the line item. Null when the line item was created without a user (e.g. by a system process).", "properties": { "id": { "description": "User ID of the editor.", "type": "string", "example": "17" }, "name": { "description": "Username of the editor.", "type": "string", "example": "JohnDoe" } }, "type": [ "object", "null" ], "example": { "id": "17", "name": "JohnDoe" } }, "internalComment": { "description": "Internal comment. Intended to be used for company-internal notes.", "type": [ "string", "null" ], "example": "this is an internal comment" } }, "type": "object", "additionalProperties": false }, "ProductCategory": { "description": "A product category (a node of the category tree) the product is assigned to.", "required": [ "id" ], "properties": { "id": { "description": "Category ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "name": { "description": "Category name.", "type": [ "string", "null" ], "example": "Gadgets" }, "parent": { "description": "Parent category in the tree.", "properties": { "id": { "description": "Parent category ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "2" } } }, "type": "object", "additionalProperties": false }, "ProductCrossSelling": { "description": "A cross-selling relation of a product (linking it to a similar or accessory product).", "required": [ "id", "type", "isActive", "isBidirectional", "order" ], "properties": { "id": { "description": "Cross-selling entry ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "product": { "description": "Cross-sold product linked to the source product.", "properties": { "id": { "description": "Cross-sold product ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "5" } }, "salesChannel": { "description": "Sales channel this cross-selling entry applies to. Null when it applies to all channels.", "properties": { "id": { "description": "Sales channel ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "2" } }, "type": { "description": "Type of the cross-selling relation.", "type": "string", "enum": [ "similar", "accessory" ], "example": "similar" }, "isActive": { "description": "Whether the cross-selling relation is active.", "type": "boolean", "example": true }, "isBidirectional": { "description": "Whether the relation applies in both directions, i.e. the linked product also lists this product.", "type": "boolean", "example": false }, "order": { "description": "The ordering sequence of the entry within the product.", "type": "integer", "example": 10 }, "internalComment": { "description": "Internal comment, does not show up on documents. Intended to be used for company-internal notes.", "type": [ "string", "null" ], "example": "Recommended add-on" } }, "type": "object", "additionalProperties": false }, "ProductDeliveryThreshold": { "description": "Product delivery threshold rule", "required": [ "id", "recipientCountry", "taxRate", "active" ], "properties": { "id": { "description": "The unique identifier of the product delivery threshold rule", "type": "string", "example": "1" }, "recipientCountry": { "description": "Recipient country code in ISO 3166-1 alpha-2 format", "type": "string", "example": "AT" }, "taxRate": { "description": "Tax rate for this product and country combination", "type": "number", "format": "float", "example": 7.02 }, "comment": { "description": "Optional comment about the threshold rule", "type": [ "string", "null" ], "example": "Special tax rate for Austria" }, "revenueAccount": { "description": "Optional revenue account code", "type": [ "string", "null" ], "example": "ABC123" }, "active": { "description": "Whether the threshold rule is active", "type": "boolean", "example": true } }, "type": "object", "additionalProperties": false }, "ProductExternalReference": { "description": "An external / foreign product number (e.g. per sales channel).", "required": [ "id", "isActive", "isScannable" ], "properties": { "id": { "description": "External reference ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "name": { "description": "Label of the external reference.", "type": [ "string", "null" ], "example": "Amazon SKU" }, "number": { "description": "The external product number.", "type": [ "string", "null" ], "example": "B0ABCDE123" }, "isActive": { "description": "Whether the reference is active.", "type": "boolean", "example": true }, "isScannable": { "description": "Whether the number is scannable.", "type": "boolean", "example": false }, "salesChannel": { "description": "Sales channel / shop the reference belongs to.", "properties": { "id": { "description": "Shop ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "3" } } }, "type": "object", "additionalProperties": false }, "ProductMedia": { "description": "A media file (image or document) linked to a product.", "required": [ "id", "isPrimary" ], "properties": { "id": { "description": "ID of the file — the id the productMedia endpoints take, and the one the upload endpoint returns.", "type": "string", "pattern": "[0-9]+", "example": "4711" }, "category": { "description": "What the file is used for on the product. Null when it is filed under a keyword outside the standard set, for example one this Xentral instance defined itself.", "type": [ "string", "null" ], "enum": [ "defaultImage", "defaultGroupImage", "labelImage", "otherImage", "printImage", "dataSheet", "certificateAttachment" ], "example": "defaultImage" }, "isPrimary": { "description": "Whether this file is the standard image of the product — the one shown for the product and printed on its documents. At most one file per product is marked, and a product whose only images are label or group images has none.", "type": "boolean", "example": true }, "name": { "description": "Name of the underlying file.", "type": [ "string", "null" ], "example": "Vitra Eames Plastic Chair" }, "description": { "description": "Description of the underlying file.", "type": [ "string", "null" ], "example": "Front picture of the Vitra Eames Plastic Chair" }, "url": { "description": "Temporary, signed URL to download the file. Null when the file has not been migrated to cloud storage yet.", "type": [ "string", "null" ], "format": "uri", "example": "https://files.example.com/artikel/4711.jpg?signature=abc123" } }, "type": "object", "additionalProperties": false }, "ProductMerchandiseGroup": { "description": "The merchandise group of a product, used for account mapping and number ranges.", "required": [ "id" ], "properties": { "id": { "description": "Merchandise group ID.", "type": "string", "pattern": "[0-9]+", "example": "7" }, "name": { "description": "Merchandise group name.", "type": [ "string", "null" ], "example": "Electronics" } }, "type": "object", "additionalProperties": false }, "ProductOption": { "description": "An option of a matrix product, such as size or colour, together with the values it can take. Options are held by the matrix product itself; each of its variants carries one value per option.", "required": [ "id", "name", "order", "isActive", "values" ], "properties": { "id": { "description": "Product option ID.", "type": "string", "pattern": "[0-9]+", "example": "1401" }, "name": { "description": "Name of the option.", "type": "string", "example": "Size" }, "order": { "description": "Position of the option in the variant matrix. Lower values are shown first.", "type": "integer", "example": 1 }, "isActive": { "description": "Whether this option is still offered when new variants are created. Variants that already carry one of its values keep it either way.", "type": "boolean", "example": true }, "values": { "description": "The values this option can take, in the order they are shown.", "type": "array", "items": { "required": [ "id", "name", "order", "numberSuffix", "isActive" ], "properties": { "id": { "description": "Option value ID.", "type": "string", "pattern": "[0-9]+", "example": "1501" }, "name": { "description": "Name of the value.", "type": "string", "example": "L" }, "order": { "description": "Position of the value within its option. Lower values are shown first.", "type": "integer", "example": 1 }, "numberSuffix": { "description": "Text appended to the product number of a variant carrying this value. Null when no suffix is configured.", "type": [ "string", "null" ], "example": "-L" }, "isActive": { "description": "Whether this value is still offered when new variants are created. Variants that already carry it keep it either way.", "type": "boolean", "example": true } }, "type": "object", "additionalProperties": false }, "example": [ { "id": "1501", "name": "L", "order": 1, "numberSuffix": "-L", "isActive": true } ] } }, "type": "object", "additionalProperties": false }, "ProductOptionValue": { "description": "One option value a variant product carries, together with the option it belongs to. A variant carries one entry per option of its matrix product. The option is normally one of that matrix product's own options, but older data can carry one that is not, and such an entry is still reported. Entries whose option cannot be determined at all are reported with a null option and sorted last, so the values a variant carries are never silently left out.", "required": [ "option", "value" ], "properties": { "option": { "description": "The option this value belongs to. Null when it cannot be determined, which happens in older data; the value itself is still reported.", "required": [ "id", "name", "isActive" ], "properties": { "id": { "description": "Product option ID.", "type": "string", "pattern": "[0-9]+", "example": "1401" }, "name": { "description": "Name of the option.", "type": "string", "example": "Size" }, "isActive": { "description": "Whether this option is still offered when new variants are created. This variant keeps the value either way.", "type": "boolean", "example": true } }, "type": [ "object", "null" ], "additionalProperties": false }, "value": { "description": "The value the variant carries for that option.", "required": [ "id", "name", "numberSuffix", "isActive" ], "properties": { "id": { "description": "Option value ID.", "type": "string", "pattern": "[0-9]+", "example": "1501" }, "name": { "description": "Name of the value.", "type": "string", "example": "L" }, "numberSuffix": { "description": "Text appended to the product number of a variant carrying this value, so the variant's number can be traced back to the values it is built from. Null when no suffix is configured.", "type": [ "string", "null" ], "example": "-L" }, "isActive": { "description": "Whether this value is still offered when new variants are created. This variant keeps it either way.", "type": "boolean", "example": true } }, "type": "object", "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "ProductPackagingUnit": { "description": "A packaging unit of a product (a box/carton holding a fixed number of items) together with its pallet layout and derived weights and volumes.", "required": [ "id", "quantity", "length", "width", "height", "tareWeight", "boxVolume", "netWeight", "grossWeight", "pallet" ], "properties": { "id": { "description": "Packaging unit ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "quantity": { "description": "Number of items contained in one box.", "type": "number", "format": "float", "example": 12 }, "barcode": { "description": "Barcode of the packaging unit, scanned to identify the box during stock-in. Distinct from the product EAN.", "type": [ "string", "null" ], "example": "4260123456789" }, "description": { "description": "Free-text description of the packaging unit.", "type": [ "string", "null" ], "example": "Retail carton" }, "length": { "description": "Length of the box in centimeters.", "type": "number", "format": "float", "example": 40 }, "width": { "description": "Width of the box in centimeters.", "type": "number", "format": "float", "example": 30 }, "height": { "description": "Height of the box in centimeters.", "type": "number", "format": "float", "example": 20 }, "tareWeight": { "description": "Weight of the empty packaging (tare) in grams.", "type": "number", "format": "float", "example": 250 }, "boxVolume": { "description": "Computed volume of one box in cubic meters.", "type": "number", "format": "float", "example": 0.024 }, "netWeight": { "description": "Computed net weight of one full box in kilograms.", "type": "number", "format": "float", "example": 24 }, "grossWeight": { "description": "Computed gross weight of one full box in kilograms.", "type": "number", "format": "float", "example": 24.25 }, "pallet": { "description": "Pallet layout of the packaging unit together with its derived totals.", "properties": { "boxesPerLayer": { "description": "Number of boxes per layer.", "type": "integer", "example": 8 }, "layers": { "description": "Number of layers stacked on the pallet.", "type": "integer", "example": 5 }, "additionalBoxes": { "description": "Additional boxes placed on top of the full layers.", "type": "integer", "example": 2 }, "height": { "description": "Height of the loaded pallet in centimeters.", "type": "number", "format": "float", "example": 120 }, "boxes": { "description": "Computed total number of boxes on the pallet.", "type": "integer", "example": 42 }, "units": { "description": "Computed total number of items on the pallet.", "type": "number", "format": "float", "example": 504 }, "netWeight": { "description": "Computed net weight of a full pallet in kilograms.", "type": "number", "format": "float", "example": 1008 } }, "type": "object", "example": { "boxesPerLayer": 8, "layers": 5, "additionalBoxes": 2, "height": 120, "boxes": 42, "units": 504, "netWeight": 1008 }, "additionalProperties": false } }, "type": "object", "additionalProperties": false }, "ProductProperty": { "description": "A property assigned to a product together with the value entries this product has for it.", "required": [ "id", "name", "type", "values" ], "properties": { "id": { "description": "Global property definition ID, shared by every product carrying this property.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "name": { "description": "Name of the property.", "type": "string", "example": "Material" }, "type": { "description": "Property input type.", "type": "string", "enum": [ "singleLine", "select" ] }, "values": { "description": "The value entries assigned to this property.", "type": "array", "items": { "properties": { "id": { "description": "Property value entry ID.", "type": "string", "pattern": "[0-9]+", "example": "4711" }, "value": { "description": "The stored value of the entry.", "type": [ "string", "null" ], "example": "Red" }, "unit": { "description": "Unit of the value, if any.", "type": [ "string", "null" ], "example": "cm" } }, "type": "object", "additionalProperties": false }, "example": [ { "id": "4711", "value": "Red", "unit": "cm" } ] } }, "type": "object", "additionalProperties": false }, "ProductPurchasePrice": { "description": "A purchase price of a product (per supplier, scale quantity and currency).", "required": [ "id", "quantity", "isDefaultSupplier" ], "properties": { "id": { "description": "Purchase price ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "supplier": { "description": "Supplier address the price applies to.", "properties": { "id": { "description": "Supplier address ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "880" } }, "supplierProductName": { "description": "Product designation the supplier uses for this product.", "type": [ "string", "null" ], "example": "Widget Pro (supplier label)" }, "supplierProductNumber": { "description": "Product number the supplier uses for this product.", "type": [ "string", "null" ], "example": "SUP-4711" }, "quantity": { "description": "Scale price applies from this quantity.", "type": "number", "format": "float", "example": 100 }, "price": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Net purchase price as amount and currency. Null for legacy price rows stored without a currency." }, { "type": "null" } ], "description": "Net purchase price as amount and currency. Null for legacy price rows stored without a currency." }, "isDefaultSupplier": { "description": "Whether this is the default supplier price.", "type": "boolean", "example": true }, "internalComment": { "description": "Internal comment for this purchase price.", "type": [ "string", "null" ], "example": "Framework agreement 2026" }, "expiresAt": { "description": "Date until which the price is valid.", "type": [ "string", "null" ], "format": "date", "example": "2026-12-31" } }, "type": "object", "additionalProperties": false }, "ProductReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the product", "type": "string", "example": "13" } }, "type": "object" }, "ProductSalesChannelSetting": { "description": "Per sales-channel settings of a product (one entry per online shop / sales channel).", "required": [ "id", "isActive", "useIndividualSalesChannelSettings", "isStockNumberSyncActive", "isRemainingQuantity", "suggestedRetailPrice", "createNewProductNumberDuringImport", "stockCorrectionValue" ], "properties": { "id": { "description": "Sales channel setting ID.", "type": "string", "pattern": "[0-9]+", "example": "4711" }, "salesChannel": { "description": "Sales channel (online shop) the settings apply to.", "properties": { "id": { "description": "Sales channel ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "5" } }, "isActive": { "description": "Whether this sales-channel entry is active. While false, the entry is skipped entirely: its individual settings are ignored and no stock or article data is synced through it.", "type": "boolean", "example": true }, "useIndividualSalesChannelSettings": { "description": "Whether individual settings are used for this sales channel instead of the product-wide defaults. While false, the values of the product's salesChannelDefaults block apply to this channel. Individual values take effect only while the entry is active.", "type": "boolean", "example": true }, "isStockNumberSyncActive": { "description": "Whether stock quantity synchronisation is active for this sales channel.", "type": "boolean", "example": false }, "isRemainingQuantity": { "description": "Whether the product is switched to unavailable in this sales channel once the remaining stock is sold off.", "type": "boolean", "example": false }, "suggestedRetailPrice": { "description": "Suggested retail price (RRP) shown in this sales channel.", "type": "string", "example": "19.99" }, "stockQuantityFormula": { "description": "The rule that decides which stock quantity this sales channel is told instead of the actual stock, such as \"L:Main - RES\". A plain number is a valid rule.", "type": [ "string", "null" ], "example": "L:Main - RES" }, "deliveryTime": { "description": "Manually set delivery time for this sales channel.", "type": [ "string", "null" ], "example": "2-3 days" }, "createNewProductNumberDuringImport": { "description": "Whether a new product number is generated during import for this sales channel.", "type": "boolean", "example": false }, "stockCorrectionValue": { "description": "Correction value added to the stock quantity reported to this sales channel; negative values reduce the reported stock. 0 means no correction.", "type": "integer", "example": -5 } }, "type": "object", "additionalProperties": false }, "ProductSalesPrice": { "description": "A sales price of a product (per customer, customer group, scale quantity and currency).", "required": [ "id", "quantity", "isNotCalculatedFromExchangeTable", "hideInBulkPriceListing" ], "properties": { "id": { "description": "Unique identifier of the sales price.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "customer": { "description": "Customer this sales price applies to. Null when the price applies to a customer group or to all customers.", "properties": { "id": { "description": "Customer ID", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "1337" } }, "customerGroup": { "description": "Customer group this sales price applies to. Null when the price applies to a specific customer or to all customers.", "properties": { "id": { "description": "Customer group ID", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "1337" } }, "price": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Net sales price as amount and currency. Prices in Xentral are net B2B prices. Null for legacy price rows stored without a currency." }, { "type": "null" } ], "description": "Net sales price as amount and currency. Prices in Xentral are net B2B prices. Null for legacy price rows stored without a currency." }, "quantity": { "description": "Minimum quantity of the product from which this sales price applies.", "type": "number", "format": "float", "example": 13.37 }, "packageAmount": { "description": "Quantity contained in one packaging unit for this sales price (the \"Quantity in PU\" value on the sales-price screen). Entries with a non-numeric suffix resolve to their leading number; entries without a leading number, or a zero value, resolve to null.", "type": [ "number", "null" ], "format": "float", "example": 13.37 }, "customerProductNumber": { "description": "The product number as used by the customer.", "type": [ "string", "null" ], "example": "Number1" }, "isNotCalculatedFromExchangeTable": { "description": "If true, this price is not converted via the currency exchange table.", "type": "boolean", "example": true }, "hideInBulkPriceListing": { "description": "If true, this price is hidden in scale-price listings on documents.", "type": "boolean", "example": false }, "internalComment": { "description": "Internal comment for this sales price.", "type": [ "string", "null" ], "example": "Special pricing note" }, "validFrom": { "description": "Date from which this sales price is valid. Null if not limited.", "type": [ "string", "null" ], "format": "date", "example": "2025-01-01" }, "expiresAt": { "description": "Date until which this sales price is valid. Null if not limited.", "type": [ "string", "null" ], "format": "date", "example": "2025-01-01" } }, "type": "object", "additionalProperties": false }, "ProductText": { "description": "Language- and shop-specific texts of a product. Entries with an `id` are the stored per-language, per-sales-channel overrides; entries with `id: null` and `salesChannel: null` are the base texts kept on the product itself. Values are returned as stored — overrides are not collapsed over the base texts and variants do not inherit from their parent product.", "required": [ "language", "isInCatalog", "isActive" ], "properties": { "id": { "description": "Product text ID. Null for the base texts stored on the product itself, which have no row of their own.", "type": [ "string", "null" ], "pattern": "[0-9]+", "example": "1337" }, "language": { "description": "Language code, e.g. \"de\".", "type": "string", "example": "de" }, "salesChannel": { "description": "Sales channel the text applies to.", "properties": { "id": { "description": "Shop ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "3" } }, "name": { "description": "Product name in this language.", "type": [ "string", "null" ], "example": "Widget Pro" }, "shortDescription": { "description": "Short description.", "type": [ "string", "null" ], "example": "A compact widget." }, "description": { "description": "Long description.", "type": [ "string", "null" ], "example": "A high-quality widget for everyday use." }, "shopDescription": { "description": "Online-shop description.", "type": [ "string", "null" ], "example": "Buy the Widget Pro now." }, "metaTitle": { "description": "SEO meta title.", "type": [ "string", "null" ], "example": "Widget Pro | Shop" }, "metaDescription": { "description": "SEO meta description.", "type": [ "string", "null" ], "example": "The best widget." }, "metaKeywords": { "description": "SEO meta keywords.", "type": [ "string", "null" ], "example": "widget, tool" }, "isInCatalog": { "description": "Whether the product is included in the catalog.", "type": "boolean", "example": false }, "catalogName": { "description": "Catalog name.", "type": [ "string", "null" ], "example": "Main catalog" }, "catalogText": { "description": "Catalog text.", "type": [ "string", "null" ], "example": "Widget Pro catalog entry." }, "isActive": { "description": "Whether this text is active.", "type": "boolean", "example": true } }, "type": "object", "additionalProperties": false }, "ProductVariant": { "description": "A variant child product of a matrix product.", "required": [ "id" ], "properties": { "id": { "description": "Variant product ID.", "type": "string", "pattern": "[0-9]+", "example": "50124" }, "name": { "description": "Variant product name.", "type": [ "string", "null" ], "example": "Widget Pro – Red" }, "number": { "description": "Variant SKU.", "type": [ "string", "null" ], "example": "SKU-1001-RED" }, "ean": { "description": "Variant EAN.", "type": [ "string", "null" ], "example": "4001234567891" }, "optionValues": { "description": "The option values this variant carries, one per option of its matrix product (include=variants.optionValues).", "type": "array", "items": { "$ref": "#/components/schemas/ProductOptionValue" } } }, "type": "object", "additionalProperties": false }, "ProductWorkInstruction": { "description": "A work instruction of a product (assembly or production step).", "required": [ "id", "name", "timePerUnit", "order" ], "properties": { "id": { "description": "Work instruction ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "name": { "description": "Short name of the work instruction.", "type": "string", "example": "Assemble housing" }, "description": { "description": "Detailed description of the work instruction.", "type": [ "string", "null" ], "example": "Attach the front panel using four M3 screws." }, "timePerUnit": { "description": "Time required per unit, in seconds.", "type": "integer", "example": 120 }, "workstationGroup": { "description": "Workstation group the instruction is performed at.", "properties": { "id": { "description": "Workstation group ID.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "5" } }, "order": { "description": "Sort order of the work instruction.", "type": "integer", "example": 10 } }, "type": "object", "additionalProperties": false }, "Production": { "description": "Production document", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "ID of the production", "type": "string", "example": "1" }, "documentNumber": { "description": "Production document number. For drafts, this will be null.", "type": [ "string", "null" ], "example": "PROD-12345" }, "documentDate": { "description": "Main date of the production document. Null when the document carries no date.", "type": [ "string", "null" ], "format": "date", "example": "2024-01-15" }, "status": { "description": "Status of the production document", "type": "string", "enum": [ "draft", "started", "released", "completed", "cancelled" ], "example": "draft" }, "writeProtection": { "description": "Indicates if the production is write protected", "type": "boolean", "example": false }, "address": { "description": "Address entity of the production. By default, only the ID is returned. To get the full Address object, use the `include` parameter.", "example": { "id": "1" }, "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "properties": { "id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "project": { "description": "Project entity of the production. By default, only the ID is returned. To get the full Project object, use the `include` parameter.", "example": { "id": "1" }, "anyOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "salesOrder": { "description": "Sales order reference associated with the production", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "editor": { "description": "The employee responsible for the production, the reference the production document prints its editor name from. References an address, not a user — the same reference the business documents carry. Null when no employee is assigned; the document's legacy free-text editor name is not exposed.", "properties": { "id": { "description": "Address ID of the employee.", "type": "string", "example": "4" } }, "type": [ "object", "null" ], "example": { "id": "4" } }, "produceProduct": { "description": "The product the production produces. By default only its ID is returned; request `?include=produceProduct` for the product itself. The embedded product is the same curated subset a document line item carries (`?include=materials.product`): identity and catalog data, logistics and customs facts, tax classification, lifecycle and print flags. A token that additionally holds the `product:read` scope receives the full Product resource instead — purchasing, stock-operations and pricing configuration and internal notes stay tied to that scope, exactly as on the product endpoints.", "example": { "id": "1" }, "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "properties": { "id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "produceQuantity": { "description": "Quantity of the product to be produced", "type": [ "number", "null" ], "format": "float", "example": 10.5 }, "batch": { "description": "Batch number recorded for the goods this production produces. Completing the production with a batch replaces it. Null when no batch has been recorded.", "type": [ "string", "null" ], "example": "CH-2026-07" }, "bestBeforeDate": { "description": "Best-before date recorded for the goods this production produces. Completing the production with a best-before date replaces it. Null when none has been recorded.", "type": [ "string", "null" ], "format": "date", "example": "2027-01-31" }, "tags": { "description": "Tags for categorizing the production. Only returned when the `tags` include is used.", "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "internalDesignation": { "description": "Internal designation", "type": [ "string", "null" ], "example": "FB-3860-L" }, "materials": { "description": "Materials (line items) for the production. By default, this is not loaded. Use the `include` parameter to load.", "type": "array", "items": { "$ref": "#/components/schemas/ProductionLineItem" } }, "workInstructions": { "description": "The steps to carry out, in the order the production document prints them. Copied from the produced product when the production is created and editable per production afterwards, which is why they are read here and not on the product. Only present when requested via `?include=workInstructions`. The step image is not part of the payload.", "type": "array", "items": { "$ref": "#/components/schemas/ProductionWorkInstruction" } }, "materialReservation": { "description": "Material reservation method. Null when the production does not set one.", "type": [ "string", "null" ], "enum": [ "instant", "onRelease", "onStart" ], "example": "onRelease" }, "materialRetrieval": { "description": "Material retrieval method. Null when the production does not set one.", "type": [ "string", "null" ], "enum": [ "single", "collective" ], "example": "single" }, "resolveMultiLevelBOM": { "description": "Whether to resolve multi-level bill of materials", "type": "boolean", "example": false }, "functionTest": { "description": "Whether function testing is required", "type": "boolean", "example": true }, "createSerialNumbers": { "description": "Whether to create serial numbers", "type": "boolean", "example": false }, "recordSubSerialNumbers": { "description": "Whether to record sub-serial numbers", "type": "boolean", "example": false }, "stockRetrievalDate": { "description": "Date the finished goods are due to leave the warehouse for the customer (\"Delivery warehouse\" in the Xentral UI). Pre-filled from the sales order delivery date when the production is created from a sales order.", "type": [ "string", "null" ], "format": "date", "example": "2024-01-25" }, "stockProvisioningDate": { "description": "Date material provisioning starts (\"Deployment start\" in the Xentral UI)", "type": [ "string", "null" ], "format": "date", "example": "2024-01-20" }, "productionStartDate": { "description": "Production start date", "type": [ "string", "null" ], "format": "date", "example": "2024-01-15" }, "productionEndDate": { "description": "Production end date", "type": [ "string", "null" ], "format": "date", "example": "2024-01-20" }, "quantitySuccessful": { "description": "Quantity that has been produced successfully and booked into stock so far. Zero until the production is completed or a partial quantity has been stored.", "type": "number", "format": "float", "example": 8 }, "quantityScrap": { "description": "Quantity that was recorded as scrap when completing the production. Scrapped goods are not booked into stock.", "type": "number", "format": "float", "example": 2 }, "completionComment": { "description": "Note recorded when the production was completed", "type": [ "string", "null" ], "example": "Completed after the second function test." }, "bodyText": { "description": "Body text for production notes", "type": [ "string", "null" ], "example": "Additional production notes" }, "internalComment": { "description": "Internal comment", "type": [ "string", "null" ], "example": "Internal production comment" }, "printSettings": { "description": "Print settings configuration", "properties": { "showTaskDescription": { "description": "Whether to show task descriptions when printing", "type": "boolean", "example": true } }, "type": "object", "example": { "showTaskDescription": true } }, "preferredWarehouse": { "description": "Preferred warehouse for the production. If set, only stock from this warehouse is considered for stock reservations, and the production cannot be started if the selected warehouse does not have sufficient stock.", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "relatedDocuments": { "description": "Documents linked to this production — currently the sales order it was created for. Only present when requested via `?include=relatedDocuments`. The reverse direction exists as well: a sales order lists its productions here.", "type": "array", "items": { "$ref": "#/components/schemas/RelatedDocumentSubResource" } }, "activity": { "description": "Activity log entries for the production. By default, this is not loaded. Use the `include` parameter to load.", "type": "array", "items": { "$ref": "#/components/schemas/ActivityLogEntry" }, "example": [] } }, "type": "object" } ], "x-example-ignore": true }, "ProductionLineItem": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "ID of the line item", "type": "string", "example": "1" }, "number": { "description": "The Number of the material. Usually the product SKU, but can be adjusted if required.", "type": [ "string", "null" ], "example": "2462-SK-D" }, "name": { "description": "The name of the material Usually the product name, but can be adjusted if required.", "type": "string", "example": "Strawberry Jam" }, "description": { "description": "The description of the material. Usually the product description, but can be adjusted if required.", "type": [ "string", "null" ], "example": "Delicious strawberry jam made from fresh strawberries." }, "quantity": { "description": "The quantity of the material", "type": "number", "format": "float", "example": 2 }, "product": { "description": "The product master data of the material. Only present when requested via `?include=materials.product`, otherwise the material carries the product id only. What the embedded product contains follows the scope of the token, the same boundary the product endpoints draw: with `production:read` alone it is the curated subset a business document embeds — identity and catalog data, logistics and customs facts, tax classification, lifecycle and print flags — while a token that also holds `product:read` receives the full Product resource, and only then can it request `?include=materials.product.storageLocations` for the material's physical stock per storage location. The product's own sub-resources are embedded on demand: `?include=materials.product.salesPrices` for the discount scales — only the rows a document would render: currently valid, not flagged as hidden for documents, no group tiers and no prices assigned to an individual customer; the internal price fields are likewise excluded — and `?include=materials.product.customFields` for the product custom fields.", "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "properties": { "id": { "type": "string", "example": "3" } }, "type": "object" } ] }, "hasChildLineItems": { "description": "Indicates if this line item has child line items (exploded line items)", "type": "boolean", "example": false }, "parentLineItem": { "description": "If this line item is a child line item, this will contain the parent line item ID", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ], "example": { "id": "1" } }, "customFields": { "description": "The material's own free fields with their values and metadata, labelled from the same company settings the legacy position dialog uses. Only present when requested via `?include=materials.customFields`.", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "customField1" }, "value": { "description": "The free-field value. Legacy free fields are always strings.", "example": "Aluminium", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string", "example": "Material" }, "type": { "description": "The data type of the free field. Legacy free fields always report `string`.", "type": "string", "enum": [ "string", "integer", "float", "date", "datetime", "boolean", "translatable_string", "object" ], "example": "string" } }, "type": "object" }, "example": [ { "key": "customField1", "value": "Aluminium", "label": "Material", "type": "string" } ] }, "sort": { "description": "The sort order of the line item", "type": "integer", "example": 1 } }, "type": "object" } ] }, "ProductionWorkInstruction": { "description": "A work instruction of a production: one step to carry out, copied from the produced product when the production is created and editable per production afterwards.", "required": [ "id", "name", "timePerUnit", "order", "status" ], "properties": { "id": { "description": "Work instruction ID.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "name": { "description": "Short name of the work instruction.", "type": "string", "example": "Assemble housing" }, "description": { "description": "Detailed description of the work instruction. Only printed on the production document when `printSettings.showTaskDescription` is set.", "type": [ "string", "null" ], "example": "Attach the front panel using four M3 screws." }, "timePerUnit": { "description": "Time required per produced unit, in seconds. The total is not stored: the production document multiplies this by the produced quantity.", "type": "integer", "example": 120 }, "workstationGroup": { "description": "Workstation group the step is carried out at.", "properties": { "id": { "description": "Workstation group ID.", "type": "string", "pattern": "[0-9]+" }, "name": { "description": "Workstation group name, as printed on the production document.", "type": "string" } }, "type": [ "object", "null" ], "example": { "id": "5", "name": "Assembly" } }, "plannedEmployee": { "description": "Employee planned for this step. References an address, not a user — the same records the production document resolves its editor through.", "properties": { "id": { "description": "Address ID of the planned employee.", "type": "string", "pattern": "[0-9]+" } }, "type": [ "object", "null" ], "example": { "id": "42" } }, "status": { "description": "Progress of the step. `notStarted` is also what a step reports that was never touched: the underlying column holds no value for it.", "type": "string", "enum": [ "notStarted", "started", "completed" ], "example": "notStarted" }, "order": { "description": "Sort order of the work instruction.", "type": "integer", "example": 10 } }, "type": "object", "additionalProperties": false }, "Project": { "required": [ "id", "name", "abbreviation" ], "properties": { "id": { "type": "string", "example": "54" }, "name": { "type": "string", "example": "Standard Project" }, "abbreviation": { "type": "string", "example": "STANDARD" } }, "type": "object", "additionalProperties": false }, "ProjectReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the project", "type": "string", "example": "13" } }, "type": "object" }, "ProjectReferenceResource": { "properties": { "project": { "description": "Project the resource belongs to. By default, only the ID is returned. To get the full Project object, use the `include` parameter.", "example": { "id": "1" }, "anyOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "id": { "type": "string", "pattern": "[0-9]+" } }, "type": "object" }, { "type": "null" } ] } }, "type": "object" }, "RelatedDocumentSubResource": { "description": "A document linked to this document.", "required": [ "type", "id", "documentNumber", "documentDate" ], "properties": { "type": { "description": "Kind of the linked document.", "type": "string", "enum": [ "offer", "salesOrder", "deliveryNote", "invoice", "creditNote", "proformaInvoice", "returnOrder", "production" ], "example": "deliveryNote" }, "id": { "description": "ID of the linked document.", "type": "string", "example": "41" }, "documentNumber": { "description": "Document number of the linked document. Null while it is still a draft.", "type": [ "string", "null" ], "example": "LS2201" }, "documentDate": { "description": "Document date of the linked document. Null while it is still a draft.", "type": [ "string", "null" ], "format": "date", "example": "2026-07-04" } }, "type": "object", "additionalProperties": false }, "SalesOrderReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the sales order", "type": "string", "example": "13" } }, "type": "object" }, "Tag": { "description": "A tag (label) assigned to a resource.", "required": [ "id" ], "properties": { "id": { "description": "Tag ID.", "type": "string", "pattern": "[0-9]+", "example": "4" }, "title": { "description": "Display name of the tag.", "type": "string", "example": "important" }, "color": { "description": "Hex color code of the tag.", "type": "string", "example": "#FFFFFF" } }, "type": "object", "additionalProperties": false }, "TagReferenceData": { "description": "References an existing tag by `id` or names a tag by `title`, which is created if it does not exist; exactly one of the two.", "properties": { "id": { "description": "ID of an existing tag to assign. Unlike `title`, an unknown id never creates a tag.", "type": "string", "pattern": "[0-9]+", "example": "1337" }, "title": { "description": "Title of the Tag. A tag with this title is created if none exists.", "type": "string", "example": "important" } }, "type": "object", "oneOf": [ { "required": [ "id" ] }, { "required": [ "title" ] } ] }, "TimestampsResource": { "properties": { "createdAt": { "description": "The date and time when the resource was created.", "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" }, "updatedAt": { "description": "The date and time when the resource was last updated.", "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Production", "description": "Production" } ], "paths": { "/api/v3/productions": { "post": { "tags": [ "Production" ], "summary": "🔒 Create production V3", "description": "This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.\n\nThis endpoint requires the following scopes: `production:create`.\n\nCreate a new production.", "operationId": "POST::api-v3-productions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductionData" } } } }, "responses": { "201": { "description": "Create a new production.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Production" } }, "type": "object" } } } }, "400": { "description": "Failed validation", "content": { "application/problem+json": { "schema": { "properties": { "type": { "description": "Error messages", "type": "string", "example": "https://api.xentral.biz/problems/request-validation" }, "title": { "description": "Error messages", "type": "string", "example": "Request payload validation failed." }, "violations": { "description": "Error messages", "type": "object", "example": { "address": [ "The address field is required." ], "project": [ "The project field must be an array." ], "salesOrder": [ "The sales order field must be an array." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Too Many Requests", "type": "string", "example": "Too Many Requests" } }, "type": "object" } } } } }, "x-beta": true, "x-scopes": [ "production:create" ] } } } } ```