--- title: "Create a purchase order" slug: "create-a-purchase-order" updated: 2026-01-30T20:02:42Z published: 2026-02-10T12:53:32Z --- > ## Documentation Index > Fetch the complete documentation index at: https://www.bloxs.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a purchase order Post/api/v1/invoices/purchaseorders Create a new purchase order. **Description** This endpoint inserts (add) a purchase order. The 200 response contains a field named 'reference'. It is important to save this value since it is used as an identifier for all the other operations to recognise this specific entity. **Use Case** The user wants to add a purchase order from outside the Bloxs application. **Request****fields** The request contains the following fields: | Field | Description | | --- | --- | | externalIdentifier | The unique identifier for this specific purchase order, not created by Bloxs. | | ownerReference | The reference of the relation that is the buying party in this purchase order. This refers to the reference created by Bloxs, not to be confused with the externalIdentifier. | | relationReference | The reference of the relation that is the selling party in this purchase order (supplier). This reference is created by Bloxs. | | proposalReference | The reference of the proposal which (usually) preceded the purchase order. This reference is created by Bloxs. | | proposalTotalAmountExcl | The total amount excluding VAT in the proposal that preceded the purchase order. | | subject | The subject of the purchase order. | | automaticApprove | Purchase order that have the value true for automaticApprove will automatically proceed to workflowState = final. the finalizationState will remain on 'open'. This is especially useful if the Bloxs application is secondary in the purchase order creating process, another system is primary. Specific authorisations are necessary to enter value = true. If the user does not have these rights, an error will be returned. | | lineIndex | The order of this specific line in the purchase order. | | expectedDate | End date of the invoice payments of this specific line in the purchase order. | | description | Description of the specific line in the purchase order. | | ledgerAccountCode | The code of the ledger account of the specific line in the purchase order. | | realEstateObjectReference | This is the reference of the realestate object of the specific line in the purchase order.. This refers to the reference created by Bloxs, not to be confused with the externalIdentifier. | | taxRateCode | The code of the tax rate (including the percentage) of the specific line in the purchase order. | | amountExcl | The amount excluding VAT of the specific line in the purchase order. | **Response fields** In addition to the request, the 200 response contains the fields in the table below. | Field | Description | | --- | --- | | reference | The unique identifier for this specific purchase order, created by Bloxs. | | workflowState | 1 = Draft Concept status. Edits are still possible. 2 = OnHold This means that an purchase order is on hold before it can be approved, for example due to a dispute with the supplier. 3 = Cancelled This purchase order was, for example, not needed or created in error. 4 = ApprovalWorkflow Submitted for approval. For example, the purchase order is pending approval by person X. This may involve a simple or extended approval chain of multiple people. 7 = Final This is the most relevant status for integration partners. Purchase orders are then fully processed (and potentially sent). 9 = Disapproved The purchase order has been returned by an approver for adjustments by the creator. 10 = OwnerApprovalWorkflow Submitted for approval by the owner. The purchase order is then awaiting the owner’s approval via the owners’ portal. This is in addition to the normal approval process but is linked to the use of the owners’ portal. 11 = DisapprovedByOwner Disapproved by the owner. This requires further review. | | finalizationState | The status of payment. 0 = Open 1 = Completed 2 = Closed | | totalAmountExcl | Total amount of the purchase order excluding VAT. | | invoicedAmount | The amount that has been invoiced till today. | | outstandingAmount | The amount that of today has not been invoiced, and is therefore still outstanding. | SecurityHTTPType Bearer Please enter a valid token Body parametersExpand Allobject externalIdentifierstring | null Min length0Max length100 ownerReferencestring RequiredMin length0Max length100 relationReferencestring RequiredMin length0Max length100 proposalReferencestring RequiredMin length0Max length100 proposalTotalAmountExclnumber (double) | null subjectstring | null Min length0Max length512 automaticApproveboolean lines Array of object (PurchaseOrderLineAPIModel) | null object lineIndexinteger (int32) expectedDatestring (date) descriptionstring | null Min length0Max length512 ledgerAccountCodestring | null Min length0Max length12 realEstateObjectReferencestring | null Min length0Max length100 taxRateCodestring | null Min length0Max length12 amountExclnumber (double) Responses200 The purchase order was created Expand Allobject referencestring Min length0Max length100 externalIdentifierstring Min length0Max length100 ownerReferencestring Min length0Max length100 relationReferencestring Min length0Max length100 proposalReferencestring Min length0Max length100 proposalTotalAmountExclnumber (double) | null subjectstring | null Min length0Max length512 workflowStateinteger (int32) Valid values[ 1, 2, 3, 4, 7, 9, 10, 11 ] finalizationStateinteger (int32) Valid values[ 0, 1, 2 ] totalAmountExclnumber (double) invoicedAmountnumber (double) | null outstandingAmountnumber (double) | null lines Array of object (PurchaseOrderLineAPIModel) | null object lineIndexinteger (int32) expectedDatestring (date) descriptionstring | null Min length0Max length512 ledgerAccountCodestring | null Min length0Max length12 realEstateObjectReferencestring | null Min length0Max length100 taxRateCodestring | null Min length0Max length12 amountExclnumber (double) 400 The purchase order data has validation issues Expand Allobject typestring | null titlestring | null traceIdstring | null statusinteger (int32) errorsobject | null property* Array of string | null additionalPropertiesstring