> This page is for version v2024-05-25 (default). > For other versions, use one of these documentation indexes: > - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt > - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt > - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Purchase orders ## Overview A purchase order is a document created by an [entity](../references/glossary#entity) with precise information about products and/or services that the entity intends to purchase from a [counterpart](../references/glossary#counterpart) (vendor). It also contains the entity and counterpart data. Each item in the purchase order must have: * name * quantity * unit * price (with currency) * vat\_rate The list of items should be carefully filled to match the external catalog of products/services that the vendor offers. It is possible to [preview the purchase order](#preview) and [send it via email](#send-via-email) to the counterpart. ## Purchase orders lifecycle \[#lifecycle] Purchase orders can move through different statuses during their lifecycle: 1. **Draft**: This is the initial status for all new purchase orders. A `draft` purchase order is not sent yet and can be edited anytime. 2. **Issued**: Indicates that the purchase order has been sent to the counterpart. When a purchase order is issued its status is changed to `issued`. ## Create a purchase order \[#create] To create a purchase order, call `POST /payable_purchase_orders`: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "valid_for_days": 7, "items": [ { "name": "Ice cream", "quantity": 10, "unit": "Kg", "price": 100, "currency": "EUR", "vat_rate": 10000 } ], "message": "This is a purchase order.", "currency": "EUR", "entity_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }' ``` The successful response contains the information about the recently created purchase order, including its ID: ```json { "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "valid_for_days": 7, "items": [ { "name": "Ice cream", "quantity": 10, "unit": "Kg", "price": 100, "currency": "EUR", "vat_rate": 10000 } ], "message": "This is a purchase order.", "currency": "EUR", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created_at": "2022-11-17T14:10:54.349Z", "updated_at": "2022-11-17T14:10:54.349Z", "counterpart": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created_at": "2022-11-17T14:10:54.349Z", "updated_at": "2022-11-17T14:10:54.349Z", "type": "individual", "created_automatically": false, "individual": { "first_name": "Adnan", "last_name": "Singh", "title": "Mr.", "is_vendor": true, "is_customer": true, "phone": "5553211234", "email": "asingh@example.net", "residential_address": { "country": "DE", "city": "Berlin", "postal_code": "10115", "state": "BE", "line1": "Flughafenstrasse 52", "line2": "Additional address" } } }, "issued_at": null, "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity": { "address": { "country": "DE", "city": "Berlin", "postal_code": "12233", "state": "BE", "line1": "Flughafenstrasse 105", "line2": "Additional address" }, "email": "user@example.com", "phone": "55331166", "created_at": "2022-11-17T14:10:54.349Z", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "logo": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created_at": "2022-11-17T14:10:54.349Z", "file_type": "payables", "name": "invoice.pdf", "region": "eu-central-1", "md5": "31d1a2dd1ad3dfc39be849d70a68dac0", "mimetype": "application/pdf", "url": "https://bucketname.s3.amazonaws.com//.pdf", "size": 24381, "previews": [], "pages": [] }, "status": "active", "updated_at": "2022-11-17T14:10:54.349Z", "type": "individual", "individual": { "first_name": "First name", "last_name": "Last name", "vat_id": "Vat ID", "tax_id": "Tax ID", "title": "Mr." } }, "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft", "document_id": "PO-00123", "file_url": "https://file.url/67890.pdf", "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_vat_id": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "country": "DE", "type": "eu_vat", "value": "DE12345678" } } ``` ## Preview the purchase order \[#preview] To preview a `draft` purchase order before sending via email, call `POST /payable_purchase_orders/{purchase_order_id}/preview`, passing the purchase order ID in the URL: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/preview' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "subject_text": "New purchase order", "body_text": "Body of the email." }' ``` The successful response contains information about the preview: ```json { "subject_preview": "New purchase order", "body_preview": "Body of the email." } ``` ## Send the purchase order via email \[#send-via-email] To send a purchase order via email to a counterpart, call `POST /payable_purchase_orders/{purchase_order_id}/send` and provide the email subject and body text. The purchase order will be attached as a PDF file to the email. ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/send' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "subject_text": "New purchase order", "body_text": "Body of the email." }' ``` The successful response contains the ID of the sent email: ```json { "mail_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` Notes: * The purchase order will be sent to the email address of the counterpart's [default contact](../common/counterparts/contacts#default). If no default contact is set (or the contact list is empty), the purchase order will be sent to the email address present in the counterpart object. * Once the purchase order is sent, its `status` field changes from `draft` to `issued` and the `issued_at` field is set to the current date. * You can also opt to attach the purchase order's PDF to the email sent to the counterpart. To do this, you must update the value of the `mail.attach_documents_as_pdf` field to `true` in your partner settings. For more information, see [Update partner settings](/api/partner-settings/patch-settings). ### Resend the purchase order \[#resend] To resend an already issued purchase order, you can call `POST /payable_purchase_orders/{purchase_order_id}/send` again, optionally with different `subject_text` and `body_text` templates. > **Info** > > Resending a purchase order does not change its `status` or `issued_at` date. ## List all purchase orders \[#list-all] To get information about all purchase orders associated with the specified entity, call `GET /payable_purchase_orders`. ## Retrieve a purchase order \[#retrieve] To get information about a specific purchase order, call `GET /payable_purchase_orders/{purchase_order_id}`. ## Edit a purchase order \[#edit] To edit an existing purchase order, call `PATCH /payable_purchase_orders/{purchase_order_id}`. Only purchase orders in the `draft` status can be edited. ## Delete a purchase order \[#delete] To delete a specific purchase order, call `DELETE /payable_purchase_orders/{purchase_order_id}`. Only purchase orders in the `draft` status can be deleted.