--- title: "๐Ÿ”’ Create purchase order V3" method: POST path: "/api/v3/purchaseOrders" tags: ["PurchaseOrder"] --- # ๐Ÿ”’ Create purchase order V3 `POST /api/v3/purchaseOrders` This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues. This endpoint requires the following scopes: `purchaseOrder:create`. Create a new purchase order. ## Request body - object - `address` object, required - `id` string, required โ€” ID of the address - `project` object - `id` string, required โ€” ID of the project - `documentDate` string, date โ€” Date of the document. Current date is used when omitted. - `language` string โ€” Language of the document in an ISO-639-1 format. - `tags` object[] โ€” List of tags associated with the document. New tags will be automatically created if they do not exist. - `title` string, required โ€” Title of the Tag - `documentAddress` object โ€” The recipients postal address of the document. If not provided, the address of the business partner will be used. - `name` string, required โ€” Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc. - `type` 'mrs' | 'mr' | 'company' | 'other' - `title` string - `contactPerson` string - `department` string - `subDepartment` string - `addressSupplement` string - `street` string - `zipCode` string - `city` string - `state` string - `country` string - `salutation` string - `gln` string - `email` string - `phone` string - `fax` string - `mobile` string - `internalDesignation` string โ€” Internal designation, might be displayed in the letterhead - `bodyIntroduction` string โ€” Introduction text for the body of the document - `bodyOutroduction` string โ€” Outroduction text for the body of the document - `vatId` string โ€” VAT ID of the business partner - `deliveryTerms` string โ€” Delivery terms for the document - `internalComment` string โ€” Internal comment for the document - `printSettings` object - `withoutLetterhead` boolean โ€” If true, the document will be printed without letterhead. - `withoutProductText` boolean โ€” If true, the document will be printed without product text. - `withoutPrices` boolean โ€” For PDFs or physical documents, hide all prices. - `withoutProductNumbers` boolean โ€” For PDFs or physical documents, hide product numbers. - `editor` object โ€” Editor information - `id` string โ€” Editor address ID - `costCenter` string โ€” Cost center for the document - `financials` object - `tax` object โ€” Tax properties of the document - `taxation` 'domestic' | 'eu' | 'export' | 'exempt' โ€” Taxation of the document, e.g. "domestic" or "eu". - `currency` string โ€” Currency of the document, e.g. "EUR" or "USD". - `exchangeRate` number, float โ€” Per-document exchange rate, used when the document currency differs from the system base currency. Overrides the rate from the global currency exchange table for this document. A value of 0 means: use the global rate from currency exchange. - `lineItems` object[] โ€” List of line items for the purchase order. - `product` object, required โ€” Product information. - `id` string, required โ€” ID of the product - `name` string โ€” Line item name. If not provided, the product name will be used. - `description` string โ€” Line item description. If not provided, the product description will be used. - `countryOfOrigin` string โ€” Country of origin for the product. If not provided, the product's country of origin will be used. - `hsCode` string โ€” Harmonized System (HS) code for the product. If not provided, the product's HS code will be used. - `deliveryDate` string, date โ€” Delivery date of the line item. - `deliveryDateAsCalendarWeek` boolean โ€” Whether to show the delivery date as calendar week or explicit. - `internalComment` string โ€” Internal comment for the line item. - `customerProductNumber` string โ€” Customer product number for the line item. - `unit` string โ€” Unit of the line item (e.g., "kg", "pcs"). If not provided, the product's unit will be used. - `price` object โ€” Price information - `net` object โ€” Net price - `amount` number, float โ€” Net amount - `currency` string โ€” Currency code - `taxLegalNotice` string โ€” Legal notice regarding tax for this line item - `supplierProductNumber` string โ€” The supplier-specific product number. - `supplierProductName` string โ€” The supplier-specific product name. - `confirmedDeliveryDate` string, date โ€” Confirmed delivery date of the purchase order. - `desiredDeliveryDate` string, date โ€” Desired delivery date of the purchase order. - `useAlternativeDocumentTitle` boolean โ€” Indicates if the alternative document title should be used. - `confirmationType` 'internet' | 'email' | 'telephone' | 'telefax' | 'letter' | 'other' โ€” Type of confirmation for the purchase order. ## Response `201` Create a new purchase order. - object - `data` object โ€” Purchase order document - `id` string โ€” ID of the document - `documentNumber` string โ€” Document number. For drafts, this will be null. - `documentDate` string, date โ€” Main date of the document. - `writeProtection` boolean โ€” Indicates if the document is write protected. - `customerNumber` string โ€” Customer number of the document. - `address` union โ€” Address entity of the document. By default, only the ID is returned. To get the full Address object, use the `include` parameter. - object - `id` string, required - `isDeleted` boolean โ€” Flagged if the entry was deleted. - `createdAt` string, date-time, required โ€” Creation timestamp - `updatedAt` string, date-time, required โ€” Last update timestamp - object - `id` string - `project` union โ€” Project entity of the document. By default, only the ID is returned. To get the full Project object, use the `include` parameter. - object - `id` string, required - `name` string, required - `abbreviation` string, required - object - `id` string - `tags` object[] โ€” Tags assigned to the document. This property is only returned if the `tags` include is used. - `id` string โ€” ID of the tag - `title` string โ€” Title of the tag - `documentAddress` object โ€” 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. - `name` string, required โ€” Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc. - `type` 'mrs' | 'mr' | 'company' | 'other' - `title` string - `contactPerson` string - `department` string - `subDepartment` string - `addressSupplement` string - `street` string - `zipCode` string - `city` string - `state` string - `country` string - `salutation` string - `gln` string - `email` string - `phone` string - `fax` string - `mobile` string - `internalDesignation` string โ€” Internal designation, might be displayed in the letterhead. - `isDocumentSent` boolean โ€” Indicates if the document has been sent to the recipient. - `language` string โ€” ISO 639-1 Language of the document. - `bodyIntroduction` string โ€” Text displayed on the document before the line items. - `bodyOutroduction` string โ€” Text displayed on the document after the line items. - `vatId` string โ€” VAT ID of the document. - `deliveryTerms` string โ€” Delivery terms of the document. - `internalComment` string โ€” Internal comment, does not show up on the document. Intended to be used for company-internal notes. - `editor` object - `id` string โ€” ID of the user who is responsible for the document. - `printSettings` object - `withoutLetterhead` boolean โ€” For PDFs or physical documents, hide the letterhead - `withoutProductText` boolean โ€” For PDFs or physical documents, hide the product text - `withoutPrices` boolean โ€” For PDFs or physical documents, hide all prices - `withoutProductNumbers` boolean โ€” For PDFs or physical documents, hide product numbers - `isConfirmationRequestVisible` boolean โ€” For PDFs or physical documents, show confirmation request - `activity` object[] โ€” Activity log entries associated with the document. To get activity object, use the `include` parameter. - `message` string, required - `causer` string, required - `causedAt` string, date-time, required - `customFields` object[] โ€” Custom fields with their values and metadata - `key` string - `value` string - `label` string - `updatedAt` string, date-time - `createdAt` string, date-time - `status` 'draft' | 'released' | 'sent' | 'completed' | 'cancelled' โ€” Status of the document. - `supplierNumber` string โ€” Supplier number of the vendor. - `desiredDeliveryDate` string, date โ€” Desired delivery date of the purchase order. - `confirmedDeliveryDate` string, date โ€” Confirmed delivery date of the purchase order. - `useAlternativeDocumentTitle` boolean โ€” Indicates if the alternative document title should be used. The alternative document title can be configured per document type in the system settings. - `lineItems` union[] - union - object โ€” Purchase Order Line Item - `type` 'product' - `id` string โ€” ID of the line item. - `number` string โ€” The Number of the line item. Usually the product SKU, but can be adjusted if required. - `name` string โ€” The name of the line item. Usually the product name, but can be adjusted if required. - `description` string โ€” The description of the line item. Usually the product description, but can be adjusted if required. - `quantity` number, float โ€” The quantity of the line item. - `product` union โ€” The product of the line item. - object - โ€ฆ - object - โ€ฆ - `countryOfOrigin` unknown - `hsCode` unknown - `customFields` object[] โ€” Custom fields with their values and metadata. - `key` string - `value` string - `label` string - `unit` string โ€” The unit of the line item. - `deliveryDate` string, date โ€” The delivery date of the line item. - `deliveryDateAsCalendarWeek` boolean โ€” Whether to show the delivery date as calendar week or explicit. - `packagingUnit` string โ€” The unit of packaging for the line item. - `internalComment` string โ€” Internal comment, does not show up on the document. Intended to be used for company-internal notes. - `customerProductNumber` string โ€” Customer product number for the line item. - `order` integer โ€” The ordering sequence of the line item. - `updatedAt` string, date-time โ€” The date and time when the line item was last updated. - `createdAt` string, date-time โ€” The date and time when the line item was created. - `salesOrderLineItem` object โ€” sales order line item reference. - `id` string โ€” ID of the line item - `deliveredQuantity` unknown - `taxRate` union โ€” Tax rate type applied to this line item - 'standard' | 'reduced' | 'exempt' - number, float - `effectiveTaxRate` number, float โ€” Effective tax rate for this line item - `price` object โ€” Price information for this line item - `net` object โ€” Money - โ€ฆ - `taxLegalNotice` string โ€” Legal notice regarding tax for this line item - `supplierProductNumber` string โ€” The supplier-specific product number (from purchase prices). - `supplierProductName` string โ€” The supplier-specific product name (from purchase prices). - object - `id` string, required - `order` integer โ€” The ordering sequence of the line item - `type` 'heading', required - `name` string - `description` string - object - `id` string, required - `order` integer โ€” The ordering sequence of the line item - `type` 'subtotal', required - `name` string - `description` string - object - `id` string, required - `order` integer โ€” The ordering sequence of the line item - `type` 'group_total', required - `name` string - `description` string - object - `id` string, required - `order` integer โ€” The ordering sequence of the line item - `type` 'image', required - `name` string - `description` string - `image` object - `id` string - `imageHeight` unknown - `imageWidth` unknown - object - `id` string, required - `order` integer โ€” The ordering sequence of the line item - `type` 'page_break', required - `financials` object โ€” Financials properties of the document - `paymentMethod` object โ€” Payment method of the document. This is a reference to the payment method used for the document. - `id` string - `paymentTerms` object โ€” Payment terms of the document - `paymentTargetDays` integer - `paymentTargetDiscount` number, float - `paymentTargetDiscountDays` integer - `tax` object โ€” Tax properties of the document - `taxation` 'domestic' | 'eu' | 'export' | 'exempt' โ€” Taxation of the document, e.g. "domestic" or "eu". - `taxRates` object โ€” 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. - `standard` number, float - `reduced` number, float - `totals` object โ€” Totals of the document. These values cannot be set directly, but are calculated based on the line items - `gross` object โ€” Money - `amount` union - string - number - `currency` string โ€” Currency - `costCenter` string โ€” Cost center of the document. - `deviatingShipToAddress` object โ€” Represents a postal address with contact information. - `name` string, required โ€” Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc. - `type` 'mrs' | 'mr' | 'company' | 'other' - `title` string - `contactPerson` string - `department` string - `subDepartment` string - `addressSupplement` string - `street` string - `zipCode` string - `city` string - `state` string - `country` string - `salutation` string - `gln` string - `email` string - `phone` string - `fax` string - `mobile` string - `confirmationType` 'internet' | 'email' | 'telephone' | 'telefax' | 'letter' | 'other' โ€” How the order confirmation was received. - `isConfirmed` boolean โ€” Whether the purchase order has been confirmed. - `shippingMethod` object โ€” Shipping method reference. - `id` string - `supplierOrderNumber` string โ€” Order number provided by the supplier. - `supplierOfferNumber` string โ€” Offer number provided by the supplier. - `priceInquiry` object โ€” Price inquiry reference. - `id` string - `effectiveAddresses` object โ€” Effective addresses of the purchase order. These (read-only) postal addresses will always be set, regardless 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 purchase order. For updating, use the `documentAddress` and `deviatingShipToAddress` fields. - `billTo` object โ€” Represents a postal address with contact information. - `name` string, required โ€” Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc. - `type` 'mrs' | 'mr' | 'company' | 'other' - `title` string - `contactPerson` string - `department` string - `subDepartment` string - `addressSupplement` string - `street` string - `zipCode` string - `city` string - `state` string - `country` string - `salutation` string - `gln` string - `email` string - `phone` string - `fax` string - `mobile` string - `shipTo` object โ€” Represents a postal address with contact information. - `name` string, required โ€” Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc. - `type` 'mrs' | 'mr' | 'company' | 'other' - `title` string - `contactPerson` string - `department` string - `subDepartment` string - `addressSupplement` string - `street` string - `zipCode` string - `city` string - `state` string - `country` string - `salutation` string - `gln` string - `email` string - `phone` string - `fax` string - `mobile` string ## Other responses - `400` โ€” Failed validation - `401` โ€” Unauthorized - `403` โ€” Forbidden - `429` โ€” Too Many Requests --- [API](https://skmtc.net/xentral/apis/xentral-api.md) ยท [All operations](https://skmtc.net/xentral/apis/xentral-api/llms.txt) ยท [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xentral/xentral-api/versions/8a27ba392442/schema)