--- updatedAt: 2026-07-03T14:10:24.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # List sales orders V3 This endpoint requires the following scopes: `salesOrder:read`. Paginated list of Sales Orders # 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" } ] }, "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" } ] }, "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 }, "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" } ] }, "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" }, "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 }, "OfferReferenceResource": { "properties": { "offer": { "description": "Offer reference", "properties": { "id": { "description": "ID of the offer", "type": "string", "example": "13" } }, "type": [ "object", "null" ] } }, "type": "object" }, "PageBreakLineItem": { "required": [ "type" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntermediateLineItem" }, { "properties": { "type": { "type": "string", "enum": [ "page_break" ], "example": "page_break" } }, "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 }, "PreferredReferenceResource": { "properties": { "preferredWarehouse": { "description": "Preferred warehouse for the document.", "properties": { "id": { "description": "ID of the preferred warehouse", "type": "string", "example": "15" } }, "type": [ "object", "null" ] } }, "type": "object" }, "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 }, "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 }, "SalesOrder": { "description": "Sales order document", "type": "object", "allOf": [ { "$ref": "#/components/schemas/BusinessDocument" }, { "$ref": "#/components/schemas/ShippingMethodResource" }, { "$ref": "#/components/schemas/FinancialResource" }, { "$ref": "#/components/schemas/OfferReferenceResource" }, { "$ref": "#/components/schemas/PreferredReferenceResource" }, { "$ref": "#/components/schemas/SalesReferenceResource" }, { "$ref": "#/components/schemas/TaxDisplayResource" }, { "properties": { "status": { "description": "Status of the document", "type": "string", "enum": [ "draft", "released", "completed", "cancelled" ], "example": "released" }, "supplierNumber": { "description": "The supplier number of the sales order's customer. This is only set if the sales order is a sales order to a supplier.", "type": [ "string", "null" ] }, "deviatingShipToAddress": { "oneOf": [ { "$ref": "#/components/schemas/PostalAddress", "description": "The deviating ship-to postal address of the sales order, if set. Null otherwise - which leads to the document address becoming the ship-to address." }, { "type": "null" } ], "description": "The deviating ship-to postal address of the sales order, if set. Null otherwise - which leads to the document address becoming the ship-to address." }, "isSalesOrderToSupplier": { "description": "Indicates if this sales order is a sales order to a supplier. Writable: setting it requires the document address to have a supplier number.", "type": "boolean", "example": false }, "externalOrderNumber": { "description": "External order number of the sales order, e.g. from a webshop", "type": [ "string", "null" ], "example": "EXT-12345" }, "customerOrderNumber": { "description": "Customer order number of the sales order, e.g. the customer's order number", "type": [ "string", "null" ], "example": "CUST-54321" }, "transactionNumber": { "description": "Transaction number of the sales order, e.g. for payment processing. Please not that this value can currently not be edited via the Xentral UI.", "type": [ "string", "null" ], "example": "TXN-1234567890" }, "externalOrderId": { "description": "External order ID of the sales order, e.g. from a webshop or external system. This is not the same as the external order number. The external order ID is often used for integration purposes, and is typically a technical identifier from a upstream system.", "type": [ "string", "null" ], "example": "EXT-ORDER-12345" }, "desiredDeliveryDate": { "description": "Desired delivery date of the sales order. This is the date when the customer expects the order to be delivered.", "type": [ "string", "null" ], "format": "date", "example": "2023-10-15" }, "desiredDeliveryDateAsCalendarWeek": { "description": "Indicates if the desired delivery date is expressed as a calendar week. If true, the `desiredDeliveryDate` should be interpreted as the start of the calendar week.", "type": "boolean", "example": false }, "earliestFulfillmentDate": { "description": "Earliest fulfillment date of the sales order. This is the date when the order can be fulfilled at the earliest.", "type": [ "string", "null" ], "format": "date", "example": "2023-10-10" }, "reservationDate": { "description": "Reservation date of the sales order. Before this date (if set), the order is not considered for stock reservations.", "type": [ "string", "null" ], "format": "date", "example": "2023-10-05" }, "commissionConsignmentStorageLocation": { "description": "Commission/consignment storage location for the sales order. This is used by the commission/consignment module.", "properties": { "id": { "type": "string", "example": "16" } }, "type": [ "object", "null" ] }, "storageCountry": { "description": "Storage country of the sales order. This is used for tax calculations and compliance. Please note that the value of this field cannot be edited or viewed in the Xentral UI", "type": [ "string", "null" ], "example": "DE" }, "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 }, "autoDispatch": { "description": "Whether the sales order may be picked up by the automatic dispatch run. The run only picks up released sales orders that also pass its own checks.", "type": "boolean", "example": true }, "vatChecked": { "description": "Indicates if the sales order has been checked for export / VAT compliance. For non-domestic sales orders, if this is false, the sales order cannot be dispatched.", "type": "boolean", "example": true }, "createDocuments": { "description": "Indicates the type of documents that will be created if this sales order is processed using auto dispatch.", "type": "string", "enum": [ "deliveryNote", "invoice", "deliveryNoteAndInvoice" ], "example": "deliveryNoteAndInvoice" }, "manualPaymentApproval": { "description": "Use this field to manual approve the payment of the sales order. Depending on the payment method configuration, this might be required before the sales order can be dispatched.", "type": "boolean", "example": false }, "manualShippingCostApproval": { "description": "Use this field to manually approve the shipping costs of the sales order. Depending on the shipping method configuration, this might be required before the sales order can be dispatched.", "type": "boolean", "example": false }, "manualDeliveryBlockApproval": { "description": "Use this field to manually approve the delivery block of the sales order. If this is true, the sales order can be dispatched despite having a delivery block.", "type": "boolean", "example": false }, "fastLane": { "description": "Indicates if the sales order is a fast lane order. Fast lane orders are processed with higher priority during auto dispatch, and stock is allocated preferentially to them.", "type": "boolean", "example": false }, "disableCancellationEmail": { "description": "Indicates if the cancellation email should be disabled for this sales order. If true, no cancellation email will be sent when the sales order is cancelled. Please note that the cancellation email has to be enabled in the project settings for this to take effect.", "type": "boolean", "example": false }, "disableTrackingEmail": { "description": "Indicates if the tracking email should be disabled for this sales order. If true, no tracking email will be sent when the sales order is dispatched. Please note that the tracking email has to be enabled in the project and shipping method settings for this to take effect.", "type": "boolean", "example": false }, "disablePaymentEmail": { "description": "Whether payment notification / reminder emails are disabled for this sales order. Mirrors the \"Keine Zahlungseingangsmail\" checkbox in the legacy sales order UI, which is stored as the sentinel value 2 in the dunning counter (auftrag.zahlungsmailcounter).", "type": "boolean", "example": false }, "deviatingDebtorAccountNumber": { "description": "Deviating debtor account number for the sales order. Used for accounting export.", "type": [ "string", "null" ], "example": "4001-12345" }, "lineItems": { "type": "array", "items": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/SalesOrderLineItem" }, { "$ref": "#/components/schemas/HeadingLineItem" }, { "$ref": "#/components/schemas/SubtotalLineItem" }, { "$ref": "#/components/schemas/GroupTotalLineItem" }, { "$ref": "#/components/schemas/ImageLineItem" }, { "$ref": "#/components/schemas/PageBreakLineItem" } ] } }, "directDebitDate": { "description": "Direct debit date of the sales order. If the sales order is paid via direct debit, the direct debit will not be executed before this date", "type": [ "string", "null" ], "format": "date", "example": "2023-10-05" }, "effectiveAddresses": { "description": "Effective addresses of the sales order. These (read-only) postal addresses will always be set, regardless\n of whether a deviating ship-to address is set or not. Use these fields if you need to easily determine the ship-to and bill-to addresses of the sales order. For updating, use the `documentAddress` and `deviatingShipToAddress` fields.", "properties": { "soldTo": { "$ref": "#/components/schemas/PostalAddress" }, "shipTo": { "$ref": "#/components/schemas/PostalAddress" } }, "type": "object" }, "masterReferenceNumber": { "description": "Master reference number of the document", "type": [ "string", "null" ], "example": "24DE1234567890ABCD" }, "partialDelivery": { "description": "Set when this sales order is a partial (Teillieferung) that was split off another one, and null otherwise, so the object itself answers whether the document is a partial. Read-only: partials are created through the `createPartialSalesOrder` action. This says the sales order *is* a partial — not that partial delivery is permitted for it, which is a separate setting carrying the same name.", "properties": { "number": { "description": "Mirrors the `-n` suffix of the document number. Treat it as that suffix rather than as an ordinal: it does not count the partials of this document, it is not unique, and two partials of one document can end up sharing a number and a document number.", "type": "integer", "example": 2 }, "splitFrom": { "description": "The sales order this one was split directly off. That is the direct predecessor, which can itself be a partial, so this must not be read as the main order — usually it is one, because the `createPartialSalesOrder` action refuses to split a document that is already a partial, but that is not guaranteed. `null` where the sales order it names no longer exists, so that this is never a reference that 404s.", "properties": { "id": { "type": "string", "example": "1926" } }, "type": [ "object", "null" ] } }, "type": [ "object", "null" ] }, "salesChannel": { "description": "Sales channel of the sales order. This is typically used to indicate the webshop or sales platform from which the order originated.", "properties": { "id": { "type": "string", "example": "3" } }, "type": [ "object", "null" ] }, "costCenter": { "description": "Cost center of the document.", "type": [ "string", "null" ], "example": "CC-123" }, "trafficLights": { "description": "System and custom traffic light states of the sales order. Only present when the `trafficLights` include is requested. System traffic lights are computed and read-only; custom traffic lights can be set via the update endpoint.", "type": "array", "items": { "$ref": "#/components/schemas/SalesOrderTrafficLightValue" } }, "printDetails": { "description": "Tenant + document rendering context for an external/headless PDF renderer (company block, letterhead mode, display flags). Only present when the `printDetails` include is requested. See API-744.", "properties": { "company": { "properties": { "name": { "type": [ "string", "null" ] }, "senderLine": { "description": "Preformatted single-line return address.", "type": [ "string", "null" ] }, "address": { "properties": { "street": { "type": [ "string", "null" ] }, "zipCode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "type": "object" }, "email": { "type": [ "string", "null" ] }, "vatId": { "description": "Company VAT ID (the \"steuernummer\" setting; holds a tax number only as a fallback when no VAT ID is set).", "type": [ "string", "null" ] }, "footer": { "description": "The legacy 4-column footer band verbatim (bank, tax IDs, register, managing directors as free text).", "properties": { "visible": { "description": "Whether the footer band is printed (the \"footersichtbar\" switch, also forced off by project stationery without labels).", "type": "boolean", "example": true }, "columns": { "description": "Four columns of six rows each, verbatim; blank cells are kept as empty strings so row alignment is preserved.", "type": "array", "items": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } }, "type": "object" }, "logo": { "description": "Company logo asset (a raster image), or null when the logo is not printed (letterhead switched off, project stationery) or the instance has no S3 backend.", "properties": { "url": { "description": "Temporary signed URL.", "type": "string", "format": "uri" }, "mimeType": { "description": "Image MIME type (from the logo_type setting; typically image/jpeg).", "type": "string", "example": "image/jpeg" } }, "type": [ "object", "null" ] }, "letterhead": { "properties": { "mode": { "description": "Letterhead background mode, and the authoritative flag for what is rendered: the firstPage/followingPages assets are only printed when mode is \"letterhead\". They may be non-null under \"logo\"/\"none\" (the files still sign), so branch on mode, never on asset presence.", "type": "string", "enum": [ "none", "logo", "letterhead" ], "example": "letterhead" }, "applied": { "description": "Whether the letterhead is applied to this document (inverse of printSettings.withoutLetterhead).", "type": "boolean", "example": true }, "firstPage": { "description": "First-page letterhead asset (a PDF), or null. Only rendered when mode is \"letterhead\"; may be present but unused under other modes.", "properties": { "url": { "description": "Temporary signed URL.", "type": "string", "format": "uri" }, "mimeType": { "type": "string", "example": "application/pdf" } }, "type": [ "object", "null" ] }, "followingPages": { "description": "Following-pages letterhead asset (a PDF), or null. Only rendered when mode is \"letterhead\"; may be present but unused under other modes.", "properties": { "url": { "description": "Temporary signed URL.", "type": "string", "format": "uri" }, "mimeType": { "type": "string", "example": "application/pdf" } }, "type": [ "object", "null" ] } }, "type": "object" }, "display": { "properties": { "showGrossPrices": { "description": "Whether prices are shown gross (true) or net (false) on this document.", "type": "boolean", "example": false }, "homeCountry": { "type": [ "string", "null" ], "example": "DE" }, "decimalPlaces": { "description": "Number of decimal places used for amounts on documents.", "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } }, "type": "object" } ] }, "SalesOrderLineItem": { "description": "Sales Order Line Item", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProductLineItem" }, { "$ref": "#/components/schemas/FinancialLineItemResource" }, { "properties": { "externalNumber": { "description": "External number for the line item, typically used for shop/web order line item references.", "type": [ "string", "null" ], "example": "WEB-12345" }, "hasChildLineItems": { "description": "Indicates if this line item has child line items (exploded line items).", "type": "boolean", "example": false }, "parentLineItem": { "description": "If this line item is a child line item, this will contain the parent line item ID.", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] }, "desiredQualityControlAttributes": { "description": "Desired quality control attributes for the line item.", "properties": { "bestBeforeDate": { "description": "Preferred best before date for the line item.", "type": [ "string", "null" ], "format": "date", "example": "2024-12-31" }, "batch": { "description": "Preferred batch for the line item.", "type": [ "string", "null" ], "example": "BATCH-12345" } }, "type": [ "object", "null" ] }, "printSettings": { "description": "Print settings for this line item.", "properties": { "hidden": { "description": "Hide this line item when printing.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } ] }, "SalesOrderTrafficLightValue": { "description": "A traffic light value for a sales order", "required": [ "id", "type", "state" ], "properties": { "id": { "description": "The unique identifier of the traffic light", "type": "string", "example": "stock" }, "type": { "description": "The type of traffic light", "type": "string", "enum": [ "system", "custom" ], "example": "system" }, "state": { "description": "The current state of this traffic light", "example": true, "oneOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "type": "object", "additionalProperties": false }, "SalesReferenceResource": { "properties": { "sales": { "description": "Sales person responsible for the document.", "properties": { "id": { "type": "string", "example": "1" } }, "type": [ "object", "null" ] } }, "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 }, "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" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "SalesOrder", "description": "SalesOrder" } ], "paths": { "/api/v3/salesOrders": { "get": { "tags": [ "SalesOrder" ], "summary": "List sales orders V3", "description": "This endpoint requires the following scopes: `salesOrder:read`.\n\nPaginated list of Sales Orders", "operationId": "GET::api-v3-salesorders", "parameters": [ { "name": "filter", "in": "query", "description": "The filter parameter is used to filter the results of the given endpoint. \n\n\n**Supported filter operators by key:** \n\n`id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`documentNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`writeProtection`: *equals*, *notEquals* \n\n`address.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`project.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`tags`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`tags.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`language`: *equals*, *notEquals*, *in*, *notIn* \n\n`bodyIntroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`bodyOutroduction`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`project.abbreviation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`internalDesignation`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`vatId`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deliveryTerms`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`internalComment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`isDocumentSent`: *equals*, *notEquals* \n\n`editor.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`createdAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`updatedAt`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`lineItems.product.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`lineItems.number`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.name`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.title`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.contactPerson`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.department`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.subDepartment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.addressSupplement`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.street`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.zipCode`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.city`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.state`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.country`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.gln`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.email`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.phone`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`documentAddress.fax`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`financials.paymentMethod.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`financials.tax.disableTaxNotice`: *equals*, *notEquals* \n\n`financials.tax.taxRates.standard`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`financials.tax.taxRates.reduced`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`financials.tax.taxation`: *equals*, *notEquals*, *in*, *notIn* \n\n`totals.net.amount`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`totals.net.currency`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`financials.paymentTerms.paymentTargetDays`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`financials.paymentTerms.paymentTargetDiscount`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`financials.paymentTerms.paymentTargetDiscountDays`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`totals.gross.amount`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`trafficLights.stock`: *equals*, *notEquals* \n\n`trafficLights.vat`: *equals*, *notEquals* \n\n`trafficLights.cashOnDelivery`: *equals*, *notEquals* \n\n`trafficLights.autoShipping`: *equals*, *notEquals* \n\n`trafficLights.customerCheck`: *equals*, *notEquals* \n\n`trafficLights.dateOfDelivery`: *equals*, *notEquals* \n\n`trafficLights.creditLimit`: *equals*, *notEquals* \n\n`trafficLights.deliveryBlock`: *equals*, *notEquals* \n\n`trafficLights.addressValidation`: *equals*, *notEquals* \n\n`trafficLights.production`: *equals*, *notEquals*, *in*, *notIn* \n\n`trafficLights.payment`: *equals*, *notEquals*, *in*, *notIn* \n\n`trafficLights.stockAvailableOpenSupply`: *equals*, *notEquals*, *in*, *notIn* \n\n`trafficLights.stockAvailableFifo`: *equals*, *notEquals*, *in*, *notIn* \n\n`status`: *equals*, *notEquals*, *in*, *notIn* \n\n`sales.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`costCenter`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`customerNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`supplierNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.name`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.title`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.contactPerson`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.department`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.subDepartment`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.addressSupplement`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.street`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.zipCode`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.city`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.state`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.country`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.gln`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.email`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.phone`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`deviatingDeliveryAddress.fax`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`isSalesOrderToSupplier`: *equals*, *notEquals* \n\n`externalOrderNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`customerOrderNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`transactionNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`externalOrderId`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`masterReferenceNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`desiredDeliveryDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`desiredDeliveryDateAsCalendarWeek`: *equals*, *notEquals* \n\n`earliestFulfillmentDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`reservationDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`preferredWarehouse.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`commissionConsignmentStorageLocation.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`storageCountry`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`useAlternativeDocumentTitle`: *equals*, *notEquals* \n\n`autoDispatch`: *equals*, *notEquals* \n\n`vatChecked`: *equals*, *notEquals* \n\n`createDocuments`: *equals*, *notEquals*, *in*, *notIn* \n\n`manualPaymentApproval`: *equals*, *notEquals* \n\n`manualShippingCostApproval`: *equals*, *notEquals* \n\n`manualDeliveryBlockApproval`: *equals*, *notEquals* \n\n`fastLane`: *equals*, *notEquals* \n\n`disableCancellationEmail`: *equals*, *notEquals* \n\n`disableTrackingEmail`: *equals*, *notEquals* \n\n`disablePaymentEmail`: *equals*, *notEquals* \n\n`directDebitDate`: *equals*, *notEquals*, *lessThan*, *lessThanOrEquals*, *greaterThan*, *greaterThanOrEquals*, *isNull*, *isNotNull* \n\n`shippingMethod.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`lineItems.externalNumber`: *equals*, *notEquals*, *in*, *notIn*, *contains*, *notContains*, *startsWith*, *endsWith*, *isNull*, *isNotNull* \n\n`hasInvoice`: *equals*, *notEquals* \n\n`partialDelivery.splitFrom.id`: *equals*, *notEquals*, *in*, *notIn*, *isNull*, *isNotNull* \n\n`isPartialDelivery`: *equals*, *notEquals* \n\n`hasPartialDeliveries`: *equals*, *notEquals*", "required": false, "style": "deepObject", "schema": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "id", "documentNumber", "documentDate", "writeProtection", "address.id", "project.id", "tags", "tags.id", "language", "bodyIntroduction", "bodyOutroduction", "project.abbreviation", "internalDesignation", "vatId", "deliveryTerms", "internalComment", "isDocumentSent", "editor.id", "createdAt", "updatedAt", "lineItems.product.id", "lineItems.number", "documentAddress.name", "documentAddress.title", "documentAddress.contactPerson", "documentAddress.department", "documentAddress.subDepartment", "documentAddress.addressSupplement", "documentAddress.street", "documentAddress.zipCode", "documentAddress.city", "documentAddress.state", "documentAddress.country", "documentAddress.gln", "documentAddress.email", "documentAddress.phone", "documentAddress.fax", "financials.paymentMethod.id", "financials.tax.disableTaxNotice", "financials.tax.taxRates.standard", "financials.tax.taxRates.reduced", "financials.tax.taxation", "totals.net.amount", "totals.net.currency", "financials.paymentTerms.paymentTargetDays", "financials.paymentTerms.paymentTargetDiscount", "financials.paymentTerms.paymentTargetDiscountDays", "totals.gross.amount", "trafficLights.stock", "trafficLights.vat", "trafficLights.cashOnDelivery", "trafficLights.autoShipping", "trafficLights.customerCheck", "trafficLights.dateOfDelivery", "trafficLights.creditLimit", "trafficLights.deliveryBlock", "trafficLights.addressValidation", "trafficLights.production", "trafficLights.payment", "trafficLights.stockAvailableOpenSupply", "trafficLights.stockAvailableFifo", "status", "sales.id", "costCenter", "customerNumber", "supplierNumber", "deviatingDeliveryAddress.name", "deviatingDeliveryAddress.title", "deviatingDeliveryAddress.contactPerson", "deviatingDeliveryAddress.department", "deviatingDeliveryAddress.subDepartment", "deviatingDeliveryAddress.addressSupplement", "deviatingDeliveryAddress.street", "deviatingDeliveryAddress.zipCode", "deviatingDeliveryAddress.city", "deviatingDeliveryAddress.state", "deviatingDeliveryAddress.country", "deviatingDeliveryAddress.gln", "deviatingDeliveryAddress.email", "deviatingDeliveryAddress.phone", "deviatingDeliveryAddress.fax", "isSalesOrderToSupplier", "externalOrderNumber", "customerOrderNumber", "transactionNumber", "externalOrderId", "masterReferenceNumber", "desiredDeliveryDate", "desiredDeliveryDateAsCalendarWeek", "earliestFulfillmentDate", "reservationDate", "preferredWarehouse.id", "commissionConsignmentStorageLocation.id", "storageCountry", "useAlternativeDocumentTitle", "autoDispatch", "vatChecked", "createDocuments", "manualPaymentApproval", "manualShippingCostApproval", "manualDeliveryBlockApproval", "fastLane", "disableCancellationEmail", "disableTrackingEmail", "disablePaymentEmail", "directDebitDate", "shippingMethod.id", "lineItems.externalNumber", "hasInvoice", "partialDelivery.splitFrom.id", "isPartialDelivery", "hasPartialDeliveries" ] }, "op": { "description": "operator", "type": "string", "enum": [ "equals", "notEquals", "in", "notIn", "isNull", "isNotNull", "contains", "notContains", "startsWith", "endsWith", "lessThan", "lessThanOrEquals", "greaterThan", "greaterThanOrEquals" ] }, "value": { "description": "The property value.", "oneOf": [ { "title": "String", "type": "string" }, { "title": "Array", "type": "array", "items": { "type": "string" } } ] } }, "type": "object", "additionalProperties": false } } }, { "name": "sort", "in": "query", "description": "Sort via id, -id, documentNumber, -documentNumber, documentDate, -documentDate, customerNumber, -customerNumber, documentAddress.country, -documentAddress.country, project.id, -project.id, createdAt, -createdAt, updatedAt and -updatedAt. Default sort is id", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "enum": [ "id", "-id", "documentNumber", "-documentNumber", "documentDate", "-documentDate", "customerNumber", "-customerNumber", "documentAddress.country", "-documentAddress.country", "project.id", "-project.id", "createdAt", "-createdAt", "updatedAt", "-updatedAt" ] } } }, { "name": "search", "in": "query", "description": "Full-text-style search across id, documentNumber, documentDate, documentAddress.name, documentAddress.email, documentAddress.zipCode, customerNumber, internalDesignation, customerOrderNumber, externalOrderNumber, externalOrderId, transactionNumber, masterReferenceNumber and supplierNumber.", "required": false, "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "lineItems", "project", "address", "lineItems.product", "lineItems.product.salesPrices", "lineItems.product.customFields", "tags", "activity", "customFields", "lineItems.customFields", "trafficLights", "relatedDocuments", "files" ] } } }, { "name": "x-pagination", "in": "header", "description": "Controls the pagination format. Available types: simple, table, cursor. Defaults to 'simple' if not specified.", "required": false, "schema": { "type": "string", "enum": [ "simple", "table", "cursor" ], "example": "simple" } }, { "name": "perPage", "in": "query", "description": "Number of items per page. Default: 15, Max: 1000. A larger value is reduced to the maximum; omitting it or sending 0 selects the default.", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 15 } }, { "name": "page", "in": "query", "description": "Page number. Only used with simple and table pagination. Omitting it or sending 0 selects the first page.", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 1 } }, { "name": "cursor", "in": "query", "description": "The cursor to use for the paginated call. Only used with cursor pagination. Not compatible with page parameter", "required": false, "schema": { "type": "string", "example": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } ], "responses": { "200": { "description": "Paginated list of Sales Orders", "content": { "application/json": { "schema": { "anyOf": [ { "title": "Paginated Response: simple", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" }, "x-description-ignore": true, "x-example-ignore": true }, "meta": { "description": "Pagination meta data", "properties": { "currentPage": { "description": "The current page number", "type": "integer", "example": 1 }, "from": { "description": "The first item being returned in the current page", "type": "integer", "example": 1, "nullable": true }, "path": { "description": "The base path for the paginated results", "type": "string", "example": "https://api.example.com/items" }, "perPage": { "description": "The number of items shown per page", "type": "integer", "example": 15 }, "to": { "description": "The last item being returned in the current page", "type": "integer", "example": 15, "nullable": true } }, "type": "object", "x-example-ignore": true }, "links": { "description": "Pagination links", "properties": { "first": { "description": "URL to the first page", "type": "string", "example": "https://api.example.com/items?page=1", "nullable": true }, "last": { "description": "URL to the last page", "type": "string", "example": null, "nullable": true }, "prev": { "description": "URL to the previous page", "type": "string", "example": null, "nullable": true }, "next": { "description": "URL to the next page", "type": "string", "example": "https://api.example.com/items?page=17", "nullable": true } }, "type": "object", "x-example-ignore": true } }, "type": "object" }, { "title": "Paginated Response: table", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" }, "x-description-ignore": true, "x-example-ignore": true }, "links": { "properties": { "first": { "description": "URL to the first page", "type": "string", "example": "https://api.example.com/items?page=1", "nullable": true }, "last": { "description": "URL to the last page", "type": "string", "example": "https://api.example.com/items?page=10", "nullable": true }, "prev": { "description": "URL to the previous page", "type": "string", "example": null, "nullable": true }, "next": { "description": "URL to the next page", "type": "string", "example": "https://api.example.com/items?page=2", "nullable": true } }, "type": "object", "x-description-ignore": true, "x-example-ignore": true }, "meta": { "properties": { "currentPage": { "description": "The current page number", "type": "integer", "example": 1 }, "from": { "description": "The first item being returned in the current page", "type": "integer", "example": 1, "nullable": true }, "lastPage": { "description": "The last page number", "type": "integer", "example": 10 }, "path": { "description": "The base path for the paginated results", "type": "string", "example": "https://api.example.com/items" }, "perPage": { "description": "The number of items shown per page", "type": "integer", "example": 15 }, "to": { "description": "The last item being returned in the current page", "type": "integer", "example": 15, "nullable": true }, "total": { "description": "The total number of items", "type": "integer", "example": 150 } }, "type": "object", "x-description-ignore": true, "x-example-ignore": true } }, "type": "object" }, { "title": "Paginated Response: cursor", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SalesOrder" }, "x-description-ignore": true, "x-example-ignore": true }, "links": { "description": "Pagination links", "properties": { "first": { "description": "URL to the first page", "type": "string", "example": "https://api.example.com/items?cursor=eyJpZCI6MSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ", "nullable": true }, "last": { "description": "URL to the last page", "type": "string", "example": null, "nullable": true }, "prev": { "description": "URL to the previous page", "type": "string", "example": null, "nullable": true }, "next": { "description": "URL to the next page", "type": "string", "example": "https://api.example.com/items?cursor=eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "nullable": true } }, "type": "object", "x-description-ignore": true, "x-example-ignore": true }, "meta": { "description": "Pagination meta data", "properties": { "path": { "description": "The base path for the paginated results", "type": "string", "example": "https://api.example.com/items" }, "perPage": { "description": "The number of items shown per page", "type": "integer", "example": 15 }, "nextCursor": { "description": "Cursor for the next page", "type": "string", "example": "eyJpZCI6MTYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "nullable": true }, "prevCursor": { "description": "Cursor for the previous page", "type": "string", "example": null, "nullable": true } }, "type": "object", "x-description-ignore": true, "x-example-ignore": true } }, "type": "object" } ] } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "properties": { "message": { "description": "Too Many Requests", "type": "string", "example": "Too Many Requests" } }, "type": "object" } } } } }, "x-scopes": [ "salesOrder:read" ] } } } } ```