--- updatedAt: 2026-07-03T14:15:52.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Update invoice V3 This endpoint requires the following scopes: `invoice:update`. Update an invoice. Line items can be written inline through `lineItems`: an entry with an `id` updates, an entry without one creates, an entry with `deleted: true` deletes. The response body carries the updated line items and tags, so an inline-created line item comes back with its new id. # 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" }, "BusinessDocument": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProjectReferenceResource" }, { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "id": { "description": "ID of the document", "type": "string", "example": "1" }, "documentNumber": { "description": "Document number. For drafts, this will be null.", "type": [ "string", "null" ], "example": "I-12343" }, "documentDate": { "description": "Main date of the document.", "type": [ "string", "null" ], "format": "date", "example": "2023-10-01" }, "writeProtection": { "description": "Indicates if the document is write protected.", "type": "boolean", "example": false }, "customerNumber": { "description": "Customer number of the document.", "type": [ "string", "null" ], "example": "CUST-54321" }, "address": { "description": "Address entity of the document. Returned as an ID reference; the list and get endpoints can return the full Address object via the `include` parameter.", "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "properties": { "id": { "type": "string" } }, "type": "object" }, { "type": "null" } ] }, "tags": { "description": "Tags assigned to the document. On GET requests this property is only returned if the `tags` include is used; create and update responses always carry it.", "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "documentAddress": { "oneOf": [ { "$ref": "#/components/schemas/PostalAddress", "description": "The recipients postal address of the document. This is is usually the postal address of the document's address entitiy, (e.g. customer), or is populated based on the preceding document. As this address is persisted on the document level, it can however be modified independently, and does not reflect changes that occurred since the document was created. May be null for legacy documents saved without a recipient." }, { "type": "null" } ], "description": "The recipients postal address of the document. This is is usually the postal address of the document's address entitiy, (e.g. customer), or is populated based on the preceding document. As this address is persisted on the document level, it can however be modified independently, and does not reflect changes that occurred since the document was created. May be null for legacy documents saved without a recipient." }, "internalDesignation": { "description": "Internal designation, might be displayed in the letterhead.", "type": [ "string", "null" ], "example": "FB-3860-L" }, "isDocumentSent": { "description": "Indicates if the document has been sent to the recipient.", "type": "boolean", "example": false }, "language": { "description": "ISO 639-1 Language of the document.", "type": "string", "example": "de" }, "bodyIntroduction": { "description": "Text displayed on the document before the line items.", "type": [ "string", "null" ], "example": "Dear customer, we are pleased to send you the following invoice." }, "bodyOutroduction": { "description": "Text displayed on the document after the line items.", "type": [ "string", "null" ], "example": "Thank you for your business." }, "vatId": { "description": "VAT ID of the document.", "type": [ "string", "null" ], "example": "DE123456789" }, "deliveryTerms": { "description": "Delivery terms of the document.", "type": [ "string", "null" ], "example": "DDP" }, "internalComment": { "description": "Internal comment, does not show up on the document. Intended to be used for company-internal notes.", "type": [ "string", "null" ], "example": "This is an internal comment." }, "editor": { "properties": { "id": { "description": "ID of the user who is responsible for the document.", "type": "string", "example": "4" } }, "type": [ "object", "null" ] }, "printSettings": { "properties": { "withoutLetterhead": { "description": "For PDFs or physical documents, hide the letterhead", "type": "boolean", "example": false }, "withoutProductText": { "description": "For PDFs or physical documents, hide the product text", "type": "boolean", "example": false } }, "type": "object" }, "activity": { "description": "Activity log entries associated with the document. To get activity object, use the `include` parameter.", "type": "array", "items": { "$ref": "#/components/schemas/ActivityLogEntry" } }, "customFields": { "description": "Custom fields with their values and metadata", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "customField1" }, "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": "prospect", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "null" } ] }, "label": { "type": "string", "example": "lifecycle" }, "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" } }, "type": "object" }, "example": [ { "key": "customer_category", "value": "Premium", "label": "Customer Category", "type": "string" }, { "key": "priority_level", "value": "High", "label": "Priority Level", "type": "string" } ] }, "relatedDocuments": { "description": "Documents linked to this document. Only present when requested via ?include=relatedDocuments.", "type": "array", "items": { "$ref": "#/components/schemas/RelatedDocumentSubResource" } }, "files": { "description": "Files attached to the document, in ascending sort order. Only the document's own attachments are returned; files scoped to a single line item are not exposed here. Only present when requested via ?include=files. Requesting this include requires the file permission of the document's module; a token whose user lacks it receives a 403 with an empty body, while a request that does not ask for the include is served normally.", "type": "array", "items": { "$ref": "#/components/schemas/BusinessDocumentFile" } } }, "type": "object" } ] }, "BusinessDocumentExchangeRate": { "properties": { "financials": { "properties": { "exchangeRate": { "description": "Per-document exchange rate, used when the document currency differs from the system base currency. Overrides the rate from the global currency exchange table for this document. A value of 0 means: use the global rate from currency exchange.", "type": "number", "format": "float", "minimum": 0, "example": 1.0875 } }, "type": "object" } }, "type": "object" }, "BusinessDocumentFile": { "description": "A file attached to a business document.", "required": [ "id", "sort" ], "properties": { "id": { "description": "ID of the file — the id the document's file endpoints take as {fileId}, and the one its upload endpoint returns.", "type": "string", "pattern": "[0-9]+", "example": "4711" }, "title": { "description": "Title of the underlying file.", "type": [ "string", "null" ], "example": "Signed delivery note" }, "description": { "description": "Description of the underlying file.", "type": [ "string", "null" ], "example": "Customer copy" }, "keyword": { "description": "What the file is filed as on the document. Null when it is filed under a keyword outside the standard set, for example one this Xentral instance defined itself.", "type": [ "string", "null" ], "enum": [ "otherFile", "coverPage", "attachment", "eInvoice", "receipt", "paymentReceipt" ], "example": "attachment" }, "sort": { "description": "Position of the file in the document's attachment list, in ascending order.", "type": "integer", "example": 0 }, "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/rechnung/4711.pdf?signature=abc123" } }, "type": "object", "additionalProperties": false }, "BusinessDocumentFinancials": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/DocumentTaxation" }, { "properties": { "financials": { "properties": { "currency": { "description": "Currency of the document, e.g. \"EUR\" or \"USD\".", "type": "string", "example": "EUR" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethodReferenceData", "description": "Reference to the payment method used for the document. Defaults to the customer or supplier payment settings when omitted on create." }, "paymentTerms": { "description": "Payment terms of the document. Default to the customer or supplier payment settings when omitted on create.", "properties": { "paymentTargetDays": { "description": "Number of days until the payment is due.", "type": "integer", "example": 30 }, "paymentTargetDiscount": { "description": "Cash discount percentage granted when paying within the discount period.", "type": "number", "format": "float", "example": 2.5 }, "paymentTargetDiscountDays": { "description": "Number of days within which the cash discount can be claimed.", "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] }, "BusinessDocumentTaxDisplay": { "properties": { "financials": { "properties": { "tax": { "properties": { "taxDisplay": { "description": "Whether the document shows net or gross prices. \"automatic\" defers to the customer, project and company settings. Setting it through this API does not recalculate prices, tax rates or totals.", "type": "string", "enum": [ "automatic", "net", "gross" ], "example": "net" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "BusinessDocumentTaxNotice": { "properties": { "financials": { "properties": { "tax": { "properties": { "disableTaxNotice": { "description": "Suppresses the EU/export tax notice line on the printed document. Print flag only - it does not change tax rates or totals.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "CanBeHiddenOnPDF": { "properties": { "printSettings": { "description": "Print settings for this line item", "properties": { "hidden": { "description": "Whether to hide this line item when printing the document", "type": "boolean", "default": false } }, "type": "object" } }, "type": "object" }, "CostCenter": { "properties": { "costCenter": { "description": "Cost center for the document", "type": "string", "maxLength": 35, "example": "CC-1234" } }, "type": "object" }, "CreateInvoiceLineItemData": { "allOf": [ { "$ref": "#/components/schemas/CreateProductLineItemData" }, { "$ref": "#/components/schemas/LineItemFinancials" }, { "$ref": "#/components/schemas/LineItemPurchasePrice" }, { "$ref": "#/components/schemas/LineItemTaxRate" }, { "$ref": "#/components/schemas/CanBeHiddenOnPDF" } ] }, "CreateProductLineItemData": { "required": [ "product", "quantity" ], "properties": { "product": { "description": "Product information.", "required": [ "id" ], "properties": { "id": { "description": "ID of the product", "type": "string", "example": "13" } }, "type": "object" }, "quantity": { "description": "Quantity of the line item.", "type": "number", "format": "float", "exclusiveMinimum": 0, "example": 10.5 }, "name": { "description": "Line item name. If not provided, the product name will be used.", "type": "string", "maxLength": 255, "example": "Product X" }, "description": { "description": "Line item description. If not provided, the product description will be used.", "type": "string", "example": "Description of Product X" }, "countryOfOrigin": { "description": "Country of origin for the product. If not provided, the product's country of origin will be used.", "type": "string", "maxLength": 128, "example": "DE" }, "hsCode": { "description": "Harmonized System (HS) code for the product. If not provided, the product's HS code will be used.", "type": "string", "maxLength": 128, "example": "0101.21" }, "deliveryDate": { "description": "Delivery date of the line item.", "type": "string", "format": "date", "example": "2025-07-20" }, "deliveryDateAsCalendarWeek": { "description": "Whether to show the delivery date as calendar week or explicit.", "type": "boolean", "default": false }, "internalComment": { "description": "Internal comment for the line item.", "type": "string", "example": "This is an internal note." }, "customerProductNumber": { "description": "Customer product number for the line item.", "type": "string", "maxLength": 128, "example": "CUS-10077" }, "unit": { "description": "Unit of the line item (e.g., \"kg\", \"pcs\"). If not provided, the product's unit will be used.", "type": "string", "maxLength": 128, "example": "pcs" }, "packagingUnit": { "description": "Packaging unit (VPE) of the line item — how many units one package contains. On purchase orders a numeric value greater than 1 makes the generated PDF present the line in packages: the price is printed per package, the quantity in packages, and the unit as \"VPE\". On all other document types the value is stored and carried over on document conversion, but nothing reads it — in particular, the stored quantity, the stored unit price, and the values returned by the API are never derived from it.", "type": "string", "maxLength": 255, "example": "box" }, "project": { "oneOf": [ { "$ref": "#/components/schemas/ProjectReferenceData", "description": "Project of the line item. If not provided, the product's project will be used. Explicitly pass null to assign no project." }, { "type": "null" } ], "description": "Project of the line item. If not provided, the product's project will be used. Explicitly pass null to assign no project." }, "customFields": { "description": "Custom field values for the line item. Accepts the `customField1` to `customField40` keys as well as any custom field configured for this line item in your Xentral instance. Listed keys are written, keys that are not listed are left untouched.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldsData" } }, "position": { "$ref": "#/components/schemas/LineItemPositionData", "description": "Where to place the line item. If omitted, it is appended after the last line item of the document." } }, "type": "object" }, "CustomFieldsData": { "required": [ "key", "value" ], "properties": { "key": { "description": "Custom field key: either a `customField` key or the key of a custom field configured in your Xentral instance. Which keys are accepted is documented on the `customFields` property of each resource.", "type": "string", "example": "customField1" }, "label": { "description": "Custom field label. Accepted for symmetry with the read payload, but ignored on write.", "type": "string", "example": "lifecycle" }, "value": { "description": "Custom field value. Pass `null` to clear the field.", "type": [ "string", "null" ], "example": "prospect" } }, "type": "object" }, "DeleteInlineLineItemData": { "required": [ "id", "deleted" ], "properties": { "id": { "description": "ID of the line item to delete from the document.", "type": "string", "example": "101" }, "deleted": { "description": "Set to true to delete the referenced line item. An entry carrying `deleted: true` must not carry any other field - deletion is not combined with an update.", "type": "boolean", "example": true } }, "type": "object" }, "DeliveryNoteReferenceResource": { "properties": { "deliveryNote": { "description": "Delivery Note reference", "properties": { "id": { "description": "ID of the offer", "type": "string", "example": "13" } }, "type": [ "object", "null" ] } }, "type": "object" }, "DocumentTaxation": { "properties": { "financials": { "properties": { "tax": { "description": "Tax properties of the document", "properties": { "taxation": { "description": "Taxation of the document, e.g. \"domestic\" or \"eu\". Defaults to the taxation of the document address when omitted on create.", "type": "string", "enum": [ "domestic", "eu", "export", "exempt" ], "example": "domestic" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "FinancialLineItemResource": { "properties": { "taxRate": { "description": "Tax rate type applied to this line item", "oneOf": [ { "type": "string", "enum": [ "standard", "reduced", "exempt" ], "example": "standard" }, { "type": "number", "format": "float", "example": 12 } ] }, "effectiveTaxRate": { "description": "Effective tax rate for this line item", "type": "number", "format": "float", "example": 19 }, "price": { "description": "Price information for this line item", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" }, "discount": { "description": "Discount percentage applied to this line item", "type": "number", "format": "float", "example": 10 }, "itemRevenue": { "description": "Revenue for a single unit of this line item (unit price after discount)", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" }, "lineItemRevenue": { "description": "Total revenue for all quantities of this line item", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" }, "purchasePrice": { "description": "Purchase price information for this line item", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" }, "contributionMargin": { "description": "Contribution margin for this line item", "type": "number", "format": "float", "example": 0.25 }, "taxLegalNotice": { "description": "Legal notice regarding tax for this line item", "type": [ "string", "null" ], "example": "Tax exempt according to §19 UStG" }, "printSettings": { "description": "Print settings for this line item.", "properties": { "withoutPrice": { "description": "Hide the prices for this line item when printing.", "type": "boolean", "example": false } }, "type": "object" }, "noDiscountAllowed": { "description": "If true, no discount may be applied to this line item.", "type": "boolean", "example": false }, "baseDiscount": { "description": "Read-only base discount percentage. Derived and maintained by Xentral from the customer or customer-group discount; it is combined multiplicatively with the line-item discount (and the further rabatt1-5 tiers), not simply added before it.", "type": "number", "format": "float", "example": 5 }, "quantityFormula": { "description": "Formula used to compute the quantity.", "type": [ "string", "null" ], "example": "menge*2" }, "priceFormula": { "description": "Formula used to compute the price.", "type": [ "string", "null" ], "example": "preis*0.9" }, "costCenter": { "description": "Cost center for this line item.", "type": [ "string", "null" ], "example": "CC-100" }, "revenueAccount": { "description": "Revenue account this line item is booked to in the accounting export. Read-only: the tax rules derive it from the product tax group and the document taxation, unless it is frozen. Null when no rule matched, in which case the export falls back to the company default.", "type": [ "string", "null" ], "example": "8400" }, "revenueAccountFixed": { "description": "Whether the revenue account is frozen. Read-only. While true, the tax rules leave the revenue account untouched instead of re-deriving it on every recalculation.", "type": "boolean", "example": false } }, "type": "object" }, "FinancialResource": { "properties": { "financials": { "description": "Financials properties of the document", "properties": { "paymentMethod": { "description": "Payment method of the document. This is a reference to the payment method used for the document.", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] }, "paymentTerms": { "description": "Payment terms of the document", "properties": { "paymentTargetDays": { "description": "Number of days until the payment is due.", "type": "integer", "example": 30 }, "paymentTargetDiscount": { "description": "Cash discount percentage granted when paying within the discount period.", "type": "number", "format": "float", "example": 2.5 }, "paymentTargetDiscountDays": { "description": "Number of days within which the cash discount can be claimed.", "type": "integer", "example": 10 }, "paymentTargetDiscountAmount": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "The amount by which the payment is reduced when the cash discount is claimed. Covers only the line items eligible for it - products excluded from cash discount do not count towards it. Read-only, and null as long as no amount has been calculated." }, { "type": "null" } ], "description": "The amount by which the payment is reduced when the cash discount is claimed. Covers only the line items eligible for it - products excluded from cash discount do not count towards it. Read-only, and null as long as no amount has been calculated." }, "paymentTargetDiscountApplied": { "description": "Whether the cash discount amount has already been calculated for this document. Read-only. While it is false, no calculated amount is available.", "type": "boolean", "example": false } }, "type": "object" }, "tax": { "description": "Tax properties of the document", "properties": { "taxation": { "description": "Taxation of the document, e.g. \"domestic\" or \"eu\".", "type": "string", "enum": [ "domestic", "eu", "export", "exempt" ], "example": "domestic" }, "disableTaxNotice": { "description": "Suppresses the EU/export tax notice line on the printed document. Print flag only - it does not change tax rates or totals.", "type": "boolean", "example": false }, "taxRates": { "description": "Tax rates of the document. These values cannot be edited directly via the Xentral UI, and are set based on the tax settings and the delivery or billing region.", "properties": { "standard": { "description": "Standard tax rate of the document in percent.", "type": "number", "format": "float", "example": 19 }, "reduced": { "description": "Reduced tax rate of the document in percent.", "type": "number", "format": "float", "example": 7 } }, "type": "object" } }, "type": "object" }, "currency": { "description": "Currency of the document as an ISO 4217 code, e.g. \"EUR\" or \"USD\".", "type": [ "string", "null" ], "example": "EUR" }, "exchangeRate": { "description": "Per-document exchange rate snapshot. `null` means the document type does not carry a per-document exchange rate (e.g. purchase orders, proforma invoices); `0` means the document type supports it but no override is set — the system falls back to the global currency exchange table; any other value is the document-specific override.", "type": [ "number", "null" ], "format": "float", "example": 1.0875 } }, "type": "object" }, "totals": { "description": "Totals of the document. These values cannot be set directly, but are calculated based on the line items", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Net total of the document." }, { "type": "null" } ], "description": "Net total of the document." }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Gross total of the document." }, { "type": "null" } ], "description": "Gross total of the document." }, "contributionMargin": { "description": "Contribution margin of the document.", "type": "number", "format": "float", "example": 42 }, "taxBreakdown": { "description": "Tax amounts grouped by effective tax rate, ascending. Per rate: taxable net, tax amount (gross - net) and gross - the per-rate tax lines of the document PDF totals block.", "type": "array", "items": { "properties": { "rate": { "description": "Effective tax rate in percent", "type": "number", "format": "float", "example": 19 }, "net": { "$ref": "#/components/schemas/Money" }, "taxAmount": { "$ref": "#/components/schemas/Money" }, "gross": { "$ref": "#/components/schemas/Money" } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "GroupTotalLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "group_total" ], "example": "group_total" }, "name": { "type": [ "string", "null" ], "example": "Group Total" }, "description": { "type": [ "string", "null" ], "example": "Total for this group" }, "amount": { "description": "Sum of the product line items in the group, i.e. since the preceding heading. Both net and gross are provided; which of the two a document layout displays depends on its configuration. Null on documents that do not carry prices (e.g. delivery notes).", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" } }, "type": "object" } ] }, "HasSales": { "properties": { "sales": { "description": "Sales information", "properties": { "id": { "description": "Sales address ID", "type": "string", "example": "5" } }, "type": "object" } }, "type": "object" }, "HasShippingMethod": { "properties": { "shippingMethod": { "$ref": "#/components/schemas/ShippingMethodReferenceData", "description": "Reference to the shipping method used for this document. Defaults to the address, project or company shipping method when omitted." } }, "type": "object" }, "HeadingLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "heading" ], "example": "heading" }, "name": { "type": [ "string", "null" ], "example": "Main Section" }, "description": { "type": [ "string", "null" ], "example": "Section description" } }, "type": "object" } ] }, "ImageLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "image" ], "example": "image" }, "name": { "type": [ "string", "null" ], "example": "Product Image" }, "description": { "type": [ "string", "null" ], "example": "Image description" }, "image": { "properties": { "id": { "type": "string", "example": "123" } }, "type": [ "object", "null" ] }, "imageHeight": { "type": [ "number", "null" ], "example": 200 }, "imageWidth": { "type": [ "number", "null" ], "example": 300 } }, "type": "object" } ] }, "IntermediateLineItem": { "required": [ "id" ], "properties": { "id": { "type": "string", "example": "il-3" }, "order": { "description": "The ordering sequence of the line item. This value is calculated across all line items of the document, so it is only returned when line items are embedded in the document payload — the single line-item view endpoints do not return it.", "type": "integer", "example": 5 } }, "type": "object" }, "Invoice": { "description": "Invoice document", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BusinessDocument" }, { "$ref": "#/components/schemas/FinancialResource" }, { "$ref": "#/components/schemas/SalesOrderReferenceResource" }, { "$ref": "#/components/schemas/DeliveryNoteReferenceResource" }, { "$ref": "#/components/schemas/SalesReferenceResource" }, { "$ref": "#/components/schemas/ShippingMethodResource" }, { "$ref": "#/components/schemas/TaxDisplayResource" }, { "properties": { "status": { "description": "Status of the document.", "type": "string", "enum": [ "draft", "released", "sent", "cancelled", "completed", "partiallyCancelled" ], "example": "cancelled" }, "customerOrderNumber": { "description": "Customer order number of the invoice, e.g. the customer's purchase order number.", "type": [ "string", "null" ], "example": "PO-12345" }, "deliveryDate": { "description": "Delivery date of the invoice. This is the date when the goods or services were delivered.", "type": [ "string", "null" ], "format": "date", "example": "2023-10-15" }, "deviatingDebtorAccountNumber": { "description": "Deviating debtor account number for the invoice. Used for accounting export.", "type": [ "string", "null" ], "example": "4001-12345" }, "useAlternativeDocumentTitle": { "description": "Indicates if the alternative document title should be used. The alternative document title can be configured per document type in the system settings.", "type": "boolean", "example": false }, "lineItems": { "type": "array", "items": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/InvoiceLineItem" }, { "$ref": "#/components/schemas/HeadingLineItem" }, { "$ref": "#/components/schemas/SubtotalLineItem" }, { "$ref": "#/components/schemas/GroupTotalLineItem" }, { "$ref": "#/components/schemas/ImageLineItem" }, { "$ref": "#/components/schemas/PageBreakLineItem" } ] } }, "masterReferenceNumber": { "description": "Master reference number of the document.", "type": [ "string", "null" ], "example": "24DE1234567890ABCD" }, "effectiveAddresses": { "description": "Effective addresses of the invoice.", "properties": { "billTo": { "$ref": "#/components/schemas/PostalAddress" } }, "type": "object" }, "paymentStatus": { "description": "Payment status of the invoice.", "type": [ "string", "null" ], "enum": [ "pending", "paid", "partiallyPaid", "cancelled", "partiallyCancelled", "badDebt", "debited" ], "example": "paid" }, "dunningSettings": { "description": "Dunning settings of the invoice.", "properties": { "level": { "description": "Dunning level of the invoice.", "type": [ "string", "null" ], "enum": [ "paymentReminder1", "reminder1", "reminder2", "reminder3", "debtCollection", "lossOfReceivables" ], "example": "reminder1" }, "date": { "description": "Date of the last dunning.", "type": [ "string", "null" ], "format": "date", "example": "2024-01-15" }, "blocked": { "description": "Whether the invoice is blocked for dunning.", "type": "boolean", "example": false }, "comment": { "description": "Internal comment regarding dunning.", "type": [ "string", "null" ], "example": "Customer promised payment next week." }, "isDunningSent": { "description": "Indicates whether a dunning notice has been sent for the invoice.", "type": "boolean", "example": false } }, "type": "object" }, "financials": { "description": "Financial properties specific to invoices, such as the direct debit collection date.", "properties": { "paymentTerms": { "description": "Invoice-specific payment terms.", "properties": { "directDebitDate": { "description": "Date on which the invoice amount is collected via direct debit.", "type": [ "string", "null" ], "format": "date", "example": "2024-02-01" } }, "type": "object" } }, "type": "object" }, "dunningSetManually": { "description": "Indicates whether dunning values are manually set.", "type": "boolean", "example": false }, "dunningManualSettings": { "description": "Manual dunning settings.", "properties": { "paidAt": { "description": "Date when the invoice was paid.", "type": [ "string", "null" ], "format": "date", "example": "2024-01-15" }, "actualAmount": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Actual amount received." }, { "type": "null" } ], "description": "Actual amount received." }, "discountGiven": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Discount amount given." }, { "type": "null" } ], "description": "Discount amount given." }, "difference": { "oneOf": [ { "$ref": "#/components/schemas/Money", "description": "Difference between actual amount and expected amount plus discount given." }, { "type": "null" } ], "description": "Difference between actual amount and expected amount plus discount given." } }, "type": "object" }, "costCenter": { "description": "Cost center of the document.", "type": [ "string", "null" ], "example": "CC-123" }, "isCollectiveBill": { "description": "Indicates whether the invoice was created as a collective bill (billing multiple sales orders / delivery notes).", "type": "boolean", "example": false } }, "type": "object" } ] }, "InvoiceLineItem": { "description": "Invoice Line Item", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProductLineItem" }, { "$ref": "#/components/schemas/FinancialLineItemResource" }, { "$ref": "#/components/schemas/SalesOrderLineItemReferenceResource" }, { "properties": { "printSettings": { "description": "Print settings for this line item.", "properties": { "hidden": { "description": "Hide this line item when printing.", "type": "boolean", "example": false } }, "type": "object" }, "salesOrderLineItems": { "description": "Sales order line items billed by this line item when the invoice is a collective bill. Empty for regular invoices, whose direct link is exposed via salesOrderLineItem. Only present when the line item is embedded in an invoice payload.", "type": "array", "items": { "properties": { "id": { "description": "ID of the sales order line item", "type": "string", "example": "1" } }, "type": "object" } }, "deliveryNoteLineItems": { "description": "Delivery note line items billed by this line item when the invoice is a collective bill. Empty for regular invoices. Only present when the line item is embedded in an invoice payload.", "type": "array", "items": { "properties": { "id": { "description": "ID of the delivery note line item", "type": "string", "example": "1" } }, "type": "object" } } }, "type": "object" } ] }, "LineItemFinancials": { "properties": { "discount": { "description": "Discount percentage", "type": "number", "format": "float", "example": 5 }, "price": { "description": "Price information", "properties": { "net": { "description": "Net price", "properties": { "amount": { "description": "Net amount", "type": "number", "format": "float", "example": 99.99 }, "currency": { "description": "Currency code", "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" }, "taxLegalNotice": { "description": "Legal notice regarding tax for this line item", "type": "string", "maxLength": 255, "example": "Tax exempt according to §19 UStG" }, "printSettings": { "description": "Print settings for this line item", "properties": { "withoutPrice": { "description": "Whether to hide the price for this line item when printing", "type": "boolean", "default": false } }, "type": "object" }, "noDiscountAllowed": { "description": "If true, no discount may be applied to this line item.", "type": "boolean", "default": false }, "quantityFormula": { "description": "Formula used to compute the quantity.", "type": [ "string", "null" ], "maxLength": 255 }, "priceFormula": { "description": "Formula used to compute the price.", "type": [ "string", "null" ], "maxLength": 255 }, "costCenter": { "description": "Cost center for this line item.", "type": [ "string", "null" ], "maxLength": 35 } }, "type": "object" }, "LineItemPositionData": { "properties": { "afterLineItem": { "oneOf": [ { "$ref": "#/components/schemas/LineItemReferenceData", "description": "The line item after which this line item is placed, matching the order the API returns. The anchor has to be a product line item; an intermediate line item is not accepted, because several of them can share one anchor and the target would be ambiguous. Pass null to place the item at the top of the document, above the first line item. An anchor that carries intermediate line items keeps them - the placed item follows both the anchor and its intermediate line items. Note: on documents whose line items were manually re-ordered in the legacy UI (non-consecutive numbering), the printed PDF may place intermediate line items slightly differently - a pre-existing renderer behaviour that positioning a product line item repairs, because it renumbers the document." }, { "type": "null" } ], "description": "The line item after which this line item is placed, matching the order the API returns. The anchor has to be a product line item; an intermediate line item is not accepted, because several of them can share one anchor and the target would be ambiguous. Pass null to place the item at the top of the document, above the first line item. An anchor that carries intermediate line items keeps them - the placed item follows both the anchor and its intermediate line items. Note: on documents whose line items were manually re-ordered in the legacy UI (non-consecutive numbering), the printed PDF may place intermediate line items slightly differently - a pre-existing renderer behaviour that positioning a product line item repairs, because it renumbers the document." } }, "type": "object" }, "LineItemPurchasePrice": { "properties": { "purchasePrice": { "description": "Purchase price (cost price) of this line item. The currency must match the document currency. Setting it marks the price as manually provided (not resolved from a price list) and it is used for the contribution margin calculation.", "properties": { "net": { "description": "Net purchase price", "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Net amount", "type": "number", "format": "float", "example": 42.5 }, "currency": { "description": "Currency code (must match the document currency)", "type": "string", "example": "EUR" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "LineItemReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of a product line item of the document", "type": "string", "example": "101" } }, "type": "object" }, "LineItemTaxRate": { "properties": { "taxRate": { "description": "The tax rate applied to this line item. Either one of the predefined tax categories - `standard` and `reduced` use the corresponding tax rate of the document (see `financials.tax.taxRates`), `exempt` uses 0% - or an explicit percentage that replaces the category. Stored with two decimals. When omitted on creation, the tax category of the product applies.", "oneOf": [ { "type": "string", "enum": [ "standard", "reduced", "exempt" ], "example": "reduced" }, { "type": "number", "format": "float", "maximum": 999.99, "minimum": 0, "example": 12.5 } ] } }, "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 }, "PageBreakLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "page_break" ], "example": "page_break" } }, "type": "object" } ] }, "PaymentMethodReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the payment method", "type": "string", "example": "13" } }, "type": "object" }, "PostalAddress": { "description": "Represents a postal address with contact information.", "required": [ "name" ], "properties": { "name": { "description": "Represents an address consisting of a physical address and contact information.\nIt is used in various documents, such as invoices, delivery notes, etc.", "type": "string", "example": "John" }, "type": { "type": [ "string", "null" ], "enum": [ "mrs", "mr", "company", "other" ], "example": "mr" }, "title": { "type": [ "string", "null" ], "example": "Ms." }, "contactPerson": { "type": [ "string", "null" ], "example": "Laura Schneider" }, "department": { "type": [ "string", "null" ], "example": "Research & Development" }, "subDepartment": { "type": [ "string", "null" ], "example": "AI Lab" }, "addressSupplement": { "type": [ "string", "null" ], "example": "Gebäude B, 4. Etage" }, "street": { "type": [ "string", "null" ], "example": "Fuggerstraße 11" }, "zipCode": { "type": [ "string", "null" ], "example": "86150" }, "city": { "type": [ "string", "null" ], "example": "Augsburg" }, "state": { "type": [ "string", "null" ], "example": "BY" }, "country": { "type": [ "string", "null" ], "example": "DE" }, "salutation": { "type": [ "string", "null" ], "example": "Sehr geehrte Damen und Herren" }, "gln": { "type": [ "string", "null" ], "example": "1234567890123" }, "email": { "type": [ "string", "null" ], "example": "laura.schneider@xentral.com" }, "phone": { "type": [ "string", "null" ], "example": "+1-234-567-8900" }, "fax": { "type": [ "string", "null" ], "example": "+1-234-567-8901" }, "mobile": { "type": [ "string", "null" ], "example": "+1-234-567-8902" } }, "type": "object", "example": { "name": "John", "type": "mr", "title": "Ms.", "contactPerson": "Laura Schneider", "department": "Research & Development", "subDepartment": "CAI Lab", "addressSupplement": "Gebäude B, 4. Etage", "street": "Fuggerstraße 11", "zipCode": "86150", "city": "Augsburg", "state": "BY", "country": "DE", "salutation": "Sehr geehrte Damen und Herren", "gln": "1234567890123", "email": "alice@example.com", "phone": "+1-234-567-8900", "fax": "+1-234-567-8901", "mobile": "+1-234-567-8902" }, "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 }, "ProductLineItem": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProjectReferenceResource" }, { "$ref": "#/components/schemas/TimestampsResource" }, { "properties": { "type": { "type": "string", "enum": [ "product" ], "example": "product" }, "id": { "description": "ID of the line item.", "type": "string", "example": "1" }, "number": { "description": "The Number of the line item. Usually the product SKU, but can be adjusted if required.", "type": [ "string", "null" ], "example": "2462-SK-D" }, "name": { "description": "The name of the line item. Usually the product name, but can be adjusted if required.", "type": "string", "example": "Strawberry Jam" }, "description": { "description": "The description of the line item. 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 line item.", "type": "number", "format": "float", "example": 2 }, "product": { "description": "The product master data of the line item, for headless UIs and PDF rendering: EAN, manufacturer and manufacturer number, measurements (weight, net weight, dimensions), customs data. Only present when requested via `?include=lineItems.product`, otherwise the line item carries the product id only. The embedded product is a curated subset of the `Product` schema: identity and catalog data, logistics and customs facts, tax classification, lifecycle and print flags. Purchasing, stock-operations, pricing/costing configuration and internal notes are never embedded here — reading those requires the product endpoints. The product's own sub-resources are embedded on demand: `?include=lineItems.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=lineItems.product.customFields` for the product custom fields.", "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "properties": { "id": { "type": "string", "example": "3" } }, "type": "object" } ] }, "countryOfOrigin": { "description": "The country of origin for the line item. When the line item has no own value, the product's country of origin is used when the document is generated (e.g. in the customs block of the proforma invoice PDF).", "type": [ "string", "null" ] }, "hsCode": { "description": "The HS (Harmonized System) code for the line item. When the line item has no own value, the product's HS code is used when the document is generated (e.g. in the customs block of the proforma invoice PDF).", "type": [ "string", "null" ] }, "customFields": { "description": "Custom fields with their values and metadata.", "type": "array", "items": { "properties": { "key": { "type": "string", "example": "customField1" }, "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": "prospect", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object" }, { "type": "null" } ] }, "label": { "type": "string", "example": "lifecycle" }, "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" } }, "type": "object" }, "example": [ { "key": "customer_category", "value": "Premium", "label": "Customer Category", "type": "string" }, { "key": "priority_level", "value": "High", "label": "Priority Level", "type": "string" } ] }, "unit": { "description": "The unit of the line item.", "type": [ "string", "null" ], "example": "kg" }, "deliveryDate": { "description": "The delivery date of the line item.", "type": [ "string", "null" ], "format": "date" }, "deliveryDateAsCalendarWeek": { "description": "Whether to show the delivery date as calendar week or explicit.", "type": "boolean", "default": false }, "packagingUnit": { "description": "The unit of packaging for the line item.", "type": [ "string", "null" ], "example": "box" }, "internalComment": { "description": "Internal comment, does not show up on the document. Intended to be used for company-internal notes.", "type": [ "string", "null" ], "example": "This is an internal comment." }, "customerProductNumber": { "description": "Customer product number for the line item.", "type": [ "string", "null" ], "example": "CUS-10077" }, "order": { "description": "The ordering sequence of the line item. This value is calculated across all line items of the document, so it is only returned when line items are embedded in the document payload — the single line-item view endpoints do not return it.", "type": "integer", "example": 5 }, "project": { "description": "Project the line item belongs to. By default, only the ID is returned.", "example": { "id": "1" }, "anyOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "id": { "type": "string", "pattern": "[0-9]+" } }, "type": "object" }, { "type": "null" } ] } }, "type": "object" } ] }, "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 }, "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 }, "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 }, "SalesOrderLineItemReferenceResource": { "properties": { "salesOrderLineItem": { "description": "sales order line item reference.", "properties": { "id": { "description": "ID of the line item", "type": "string", "example": "1" } }, "type": [ "object", "null" ] } }, "type": "object" }, "SalesOrderReferenceResource": { "properties": { "salesOrder": { "description": "Sales order reference.", "properties": { "id": { "description": "ID of the sales order", "type": "string", "example": "13" } }, "type": [ "object", "null" ] } }, "type": "object" }, "SalesReferenceResource": { "properties": { "sales": { "description": "Sales person responsible for the document.", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] } }, "type": "object" }, "ShippingMethodReferenceData": { "required": [ "id" ], "properties": { "id": { "description": "ID of the shipping method", "type": "string", "example": "13" } }, "type": "object" }, "ShippingMethodResource": { "properties": { "shippingMethod": { "description": "Shipping method of the document.", "properties": { "id": { "description": "ID of the shipping method", "type": "string", "example": "16" }, "name": { "description": "Name of the shipping method", "type": "string", "example": "Standard Shipping" } }, "type": [ "object", "null" ] } }, "type": "object" }, "SubtotalLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "subtotal" ], "example": "subtotal" }, "name": { "type": [ "string", "null" ], "example": "Subtotal" }, "description": { "type": [ "string", "null" ], "example": "Section subtotal" }, "amount": { "description": "Cumulative sum of all product line items from the top of the document up to this subtotal. Both net and gross are provided; which of the two a document layout displays depends on its configuration. Null on documents that do not carry prices (e.g. delivery notes).", "properties": { "net": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "gross": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object" } }, "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" ] } ] }, "TaxDisplayResource": { "properties": { "financials": { "properties": { "tax": { "properties": { "taxDisplay": { "description": "Whether the document shows net or gross prices. \"automatic\" defers to the customer, project and company settings. Setting it through this API does not recalculate prices, tax rates or totals.", "type": "string", "enum": [ "automatic", "net", "gross" ], "example": "net" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "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" }, "UpdateBusinessDocumentData": { "properties": { "address": { "$ref": "#/components/schemas/AddressReferenceData", "description": "The business partner the document is issued to. Re-pointing it to a different partner re-derives every partner-dependent value from the new partner: documentAddress, project, language, taxation, tax rates, payment method and terms, VAT ID, delivery terms, shipping method, preferred warehouse, sales representative, editor, and the line item discounts. Line item prices and the document currency are deliberately kept unchanged, so negotiated prices survive the change. Fields sent in the same request take precedence over the derived values; a project sent alongside also replaces the one the new partner would bring, and the project-dependent values derive from it. Passing the id the document already has has no effect. Write-protected documents are rejected." }, "documentDate": { "description": "Date of the document", "type": "string", "format": "date", "example": "2025-07-15" }, "documentAddress": { "$ref": "#/components/schemas/UpdatePostalAddressData", "description": "The recipients postal address of the document" }, "project": { "oneOf": [ { "$ref": "#/components/schemas/ProjectReferenceData", "description": "The project associated with the document. Set to null to remove project association." }, { "type": "null" } ], "description": "The project associated with the document. Set to null to remove project association." }, "internalDesignation": { "description": "Internal designation, might be displayed in the letterhead", "type": "string", "maxLength": 255, "example": "FB-3860-L" }, "bodyIntroduction": { "description": "Introduction text for the body of the document", "type": "string", "example": "Sehr geehrte Damen und Herren," }, "bodyOutroduction": { "description": "Outroduction text for the body of the document", "type": "string", "example": "Mit freundlichen Grüßen" }, "vatId": { "description": "VAT ID of the business partner", "type": "string", "maxLength": 255, "example": "DE123456789" }, "deliveryTerms": { "description": "Delivery terms for the document", "type": "string", "example": "Lieferung frei Haus" }, "internalComment": { "description": "Internal comment for the document", "type": "string", "example": "This is an internal comment." }, "language": { "description": "Language of the document in an ISO-639-1 format.", "type": "string", "example": "en" }, "printSettings": { "description": "Print settings for the document", "properties": { "withoutLetterhead": { "description": "If true, the document will be printed without letterhead", "type": "boolean", "example": false }, "withoutProductText": { "description": "If true, the document will be printed without product text", "type": "boolean", "example": false } }, "type": "object" }, "editor": { "description": "Editor information", "properties": { "id": { "description": "Editor address ID", "type": "string", "example": "6" } }, "type": "object" }, "tags": { "description": "Tags assigned to the document. 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" } }, "customFields": { "description": "Custom field values for the document. Only custom fields configured for this document in your Xentral instance are accepted here; the `customField1` to `customField40` keys exist on line items only. Listed keys are written, keys that are not listed are left untouched. Pass `value: null` to clear a single field.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldsData" } } }, "type": "object" }, "UpdateInvoiceData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/UpdateBusinessDocumentData" }, { "$ref": "#/components/schemas/CostCenter" }, { "$ref": "#/components/schemas/BusinessDocumentExchangeRate" }, { "$ref": "#/components/schemas/BusinessDocumentFinancials" }, { "$ref": "#/components/schemas/HasSales" }, { "$ref": "#/components/schemas/HasShippingMethod" }, { "$ref": "#/components/schemas/BusinessDocumentTaxDisplay" }, { "$ref": "#/components/schemas/BusinessDocumentTaxNotice" }, { "properties": { "dunningSettings": { "properties": { "level": { "description": "Dunning level of the invoice.", "type": "string", "enum": [ "paymentReminder1", "reminder1", "reminder2", "reminder3", "debtCollection", "lossOfReceivables" ], "example": "reminder1" }, "date": { "description": "Dunning date of the invoice.", "type": [ "string", "null" ], "format": "date", "example": "2025-08-15" }, "blocked": { "description": "Indicates whether dunning is blocked for the invoice.", "type": "boolean", "example": false }, "comment": { "description": "Comment regarding the dunning of the invoice.", "type": [ "string", "null" ], "example": "Customer has paid partially." } }, "type": "object" }, "dunningSetManually": { "description": "Indicates whether dunning values are manually set.", "type": "boolean", "example": false }, "dunningManualSettings": { "description": "Manual dunning settings. Only applicable when dunningSetManually is true.", "properties": { "paymentStatus": { "description": "Manually set payment status.", "type": "string", "enum": [ "pending", "paid", "partiallyPaid", "cancelled", "partiallyCancelled", "badDebt", "debited" ], "example": "paid" }, "paidAt": { "description": "Date when the invoice was paid.", "type": [ "string", "null" ], "format": "date", "example": "2024-01-20" }, "actualAmount": { "$ref": "#/components/schemas/Money", "description": "Actual amount received." }, "discountGiven": { "$ref": "#/components/schemas/Money", "description": "Discount amount given." } }, "type": [ "object", "null" ] }, "masterReferenceNumber": { "description": "Master reference number for the invoice.", "type": "string", "maxLength": 255, "example": "MRN-123456" }, "lineItems": { "description": "Line items to write together with the invoice. An entry with an `id` updates that product line item of this invoice (only the provided fields), an entry without an `id` creates a new line item appended at the end, and an entry with `deleted: true` deletes the referenced line item. Line items not included in the list are left unchanged - only an explicit `deleted` entry removes one. Intermediate line items (ids prefixed with `il-`) can be updated inline as well, limited to their name and description; creating or deleting them requires the dedicated line-item endpoints.", "type": "array", "items": { "$ref": "#/components/schemas/UpdateInvoiceInlineLineItemRequest" }, "maxItems": 100 }, "customerOrderNumber": { "description": "Customer order number / reference.", "type": "string", "maxLength": 255, "example": "PO-2024-12345" }, "deliveryDate": { "description": "Delivery date of the order the invoice is associated with.", "type": [ "string", "null" ], "format": "date", "example": "2025-01-15" }, "useAlternativeDocumentTitle": { "description": "Indicates if the alternative document title should be used.", "type": "boolean", "example": false }, "deviatingDebtorAccountNumber": { "description": "Deviating debtor account number for accounting purposes.", "type": "string", "maxLength": 32, "example": "10001" } }, "type": "object" } ] }, "UpdateInvoiceInlineLineItemData": { "required": [ "id" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/UpdateInvoiceLineItemData" }, { "properties": { "id": { "description": "ID of the invoice line item to update. Product line items are referenced by their numeric id, intermediate line items by their `il-` prefixed id. Inline entries for intermediate line items support name and description only.", "type": "string", "example": "101" } }, "type": "object" } ] }, "UpdateInvoiceInlineLineItemRequest": { "anyOf": [ { "$ref": "#/components/schemas/UpdateInvoiceInlineLineItemData" }, { "$ref": "#/components/schemas/CreateInvoiceLineItemData" }, { "$ref": "#/components/schemas/DeleteInlineLineItemData" } ] }, "UpdateInvoiceLineItemData": { "allOf": [ { "$ref": "#/components/schemas/UpdateProductLineItemData" }, { "$ref": "#/components/schemas/LineItemFinancials" }, { "$ref": "#/components/schemas/LineItemPurchasePrice" }, { "$ref": "#/components/schemas/LineItemTaxRate" }, { "$ref": "#/components/schemas/CanBeHiddenOnPDF" } ] }, "UpdatePostalAddressData": { "properties": { "type": { "description": "Type of the recipient", "type": [ "string", "null" ], "enum": [ "mrs", "mr", "company", "other" ], "example": "company" }, "name": { "description": "Name of the recipient", "type": "string", "example": "John Doe" }, "title": { "description": "Title of the recipient", "type": [ "string", "null" ], "example": "Dr." }, "contactPerson": { "description": "Contact person", "type": [ "string", "null" ], "example": "Jane Smith" }, "department": { "description": "Department", "type": [ "string", "null" ], "example": "Sales" }, "subDepartment": { "description": "Sub-department", "type": [ "string", "null" ], "example": "International" }, "addressSupplement": { "description": "Address supplement", "type": [ "string", "null" ], "example": "Building A" }, "street": { "description": "Street address", "type": [ "string", "null" ], "example": "Fuggerstraße 11" }, "zipCode": { "description": "ZIP Code", "type": [ "string", "null" ], "example": "86150" }, "city": { "description": "City", "type": [ "string", "null" ], "example": "Augsburg" }, "state": { "description": "State", "type": [ "string", "null" ], "example": "BY" }, "country": { "description": "Country (ISO 3166-1 alpha-2).", "type": [ "string", "null" ], "maxLength": 2, "pattern": "^[A-Z]{2}$", "example": "DE" }, "gln": { "description": "Global Location Number", "type": [ "string", "null" ], "example": "1234567890123" }, "salutation": { "description": "Salutation", "type": [ "string", "null" ], "example": "Dear John," }, "email": { "description": "Email address", "type": [ "string", "null" ], "example": "john@example.com" }, "phone": { "description": "Phone number", "type": [ "string", "null" ], "example": "+1-234-567-8900" }, "fax": { "description": "Fax number", "type": [ "string", "null" ], "example": "+1-234-567-8901" }, "mobile": { "description": "Mobile number", "type": [ "string", "null" ], "example": "+1-234-567-8902" } }, "type": "object" }, "UpdateProductLineItemData": { "properties": { "name": { "description": "Name of the line item.", "type": "string", "maxLength": 255, "example": "Product Name" }, "description": { "description": "Description of the line item.", "type": [ "string", "null" ], "example": "Detailed product description" }, "quantity": { "description": "Quantity of the line item.", "type": "number", "format": "float", "exclusiveMinimum": 0, "example": 10.5 }, "deliveryDate": { "description": "Delivery date of the line item.", "type": [ "string", "null" ], "format": "date", "example": "2025-08-15" }, "deliveryDateAsCalendarWeek": { "description": "Whether to show the delivery date as calendar week or explicit.", "type": "boolean", "default": false }, "internalComment": { "description": "Internal comment for the line item.", "type": [ "string", "null" ], "example": "This is an internal note." }, "unit": { "description": "Unit of the line item (e.g., \"kg\", \"pcs\").", "type": [ "string", "null" ], "maxLength": 128, "example": "pcs" }, "countryOfOrigin": { "description": "Country of origin for the product. The legacy empty value \"0\" is returned as null.", "type": [ "string", "null" ], "maxLength": 128, "example": "DE" }, "hsCode": { "description": "Harmonized System (HS) code for the product.", "type": [ "string", "null" ], "maxLength": 128, "example": "0101.21" }, "customerProductNumber": { "description": "Customer product number for the line item.", "type": [ "string", "null" ], "maxLength": 128, "example": "CUS-10077" }, "packagingUnit": { "description": "Packaging unit (VPE) of the line item — how many units one package contains. On purchase orders a numeric value greater than 1 makes the generated PDF present the line in packages: the price is printed per package, the quantity in packages, and the unit as \"VPE\". On all other document types the value is stored and carried over on document conversion, but nothing reads it — in particular, the stored quantity, the stored unit price, and the values returned by the API are never derived from it.", "type": [ "string", "null" ], "maxLength": 255, "example": "box" }, "project": { "oneOf": [ { "$ref": "#/components/schemas/ProjectReferenceData", "description": "Project of the line item. Pass null to remove the project assignment." }, { "type": "null" } ], "description": "Project of the line item. Pass null to remove the project assignment." }, "customFields": { "description": "Custom field values for the line item. Accepts the `customField1` to `customField40` keys as well as any custom field configured for this line item in your Xentral instance. Listed keys are written, keys that are not listed are left untouched. Pass `value: null` to clear a single field.", "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldsData" } }, "position": { "$ref": "#/components/schemas/LineItemPositionData", "description": "Moves the line item to a new position. The line items that follow are renumbered, and the intermediate line items anchored to them keep their place." } }, "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Invoice", "description": "Invoice" } ], "paths": { "/api/v3/invoices/{id}": { "patch": { "tags": [ "Invoice" ], "summary": "Update invoice V3", "description": "This endpoint requires the following scopes: `invoice:update`.\n\nUpdate an invoice. Line items can be written inline through `lineItems`: an entry with an `id` updates, an entry without one creates, an entry with `deleted: true` deletes. The response body carries the updated line items and tags, so an inline-created line item comes back with its new id.", "operationId": "PATCH::api-v3-invoices-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoiceData" } } } }, "responses": { "200": { "description": "Update an invoice. Line items can be written inline through `lineItems`: an entry with an `id` updates, an entry without one creates, an entry with `deleted: true` deletes. The response body carries the updated line items and tags, so an inline-created line item comes back with its new id.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "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": { "dunningSettings.level": [ "The dunningSettings.level field is invalid." ], "dunningSettings.date": [ "The dunningSettings.date field is invalid." ], "dunningSettings.blocked": [ "The dunningSettings.blocked field is invalid." ] } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "409": { "description": "Problem occurred", "content": { "application/problem+json": { "schema": { "properties": { "type": { "description": "A URI reference that identifies the problem type.", "type": "string", "example": "https://api.xentral.biz/problems/write-protected" }, "title": { "description": "A short, human-readable summary of the problem type.", "type": "string", "example": "The resource is write-protected." } }, "type": "object" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Too Many Requests", "type": "string", "example": "Too Many Requests" } }, "type": "object" } } } } }, "x-scopes": [ "invoice:update" ] } } } } ```