Purchase orders
Learn how to create and manage purchase orders in Monite.
Overview
A purchase order is a document created by an entity with precise information about products and/or services that the entity intends to purchase from a 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 and send it via email to the counterpart.
Purchase orders lifecycle
Purchase orders can move through different statuses during their lifecycle:
- Draft: This is the initial status for all new purchase orders. A
draft
purchase order is not sent yet and can be edited anytime. - 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
To create a purchase order, call POST /payable_purchase_orders
:
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders' \
-H 'X-Monite-Version: 2023-06-04' \
-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"
}'
The successful response contains the information about the recently created purchase order, including its ID:
{
"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": "[email protected]",
"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": "[email protected]",
"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/<random_UUID_1>/<random_UUID_2>.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"
}
Preview the purchase order
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:
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/preview' \
-H 'X-Monite-Version: 2023-06-04' \
-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:
{
"subject_preview": "New purchase order",
"body_preview": "Body of the email."
}
Send the purchase order 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.
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/send' \
-H 'X-Monite-Version: 2023-06-04' \
-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:
{
"mail_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
Once the purchase order is sent, its
status
field changes fromdraft
toissued
and theissued_at
field is set to the current date.
Resend the purchase order
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.
Resending a purchase order does not change its
status
orissued_at
date.
List all purchase orders
To get information about all purchase orders associated with the specified entity, call GET /payable_purchase_orders
.
Retrieve a purchase order
To get information about a specific purchase order, call GET /payable_purchase_orders/{purchase_order_id}
.
Edit a purchase order
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
To delete a specific purchase order, call DELETE /payable_purchase_orders/{purchase_order_id}
. Only purchase orders in the draft
status can be deleted.
Updated 5 days ago