Purchase orders

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:

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

To create a purchase order, call POST /payable_purchase_orders:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -d '{
6
        "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
7
        "valid_for_days": 7,
8
        "items": [
9
          {
10
            "name": "Ice cream",
11
            "quantity": 10,
12
            "unit": "Kg",
13
            "price": 100,
14
            "currency": "EUR",
15
            "vat_rate": 10000
16
          }
17
        ],
18
        "message": "This is a purchase order.",
19
        "currency": "EUR",
20
        "entity_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
21
      }'

The successful response contains the information about the recently created purchase order, including its ID:

1
{
2
  "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3
  "valid_for_days": 7,
4
  "items": [
5
    {
6
      "name": "Ice cream",
7
      "quantity": 10,
8
      "unit": "Kg",
9
      "price": 100,
10
      "currency": "EUR",
11
      "vat_rate": 10000
12
    }
13
  ],
14
  "message": "This is a purchase order.",
15
  "currency": "EUR",
16
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
17
  "created_at": "2022-11-17T14:10:54.349Z",
18
  "updated_at": "2022-11-17T14:10:54.349Z",
19
  "counterpart": {
20
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
21
    "created_at": "2022-11-17T14:10:54.349Z",
22
    "updated_at": "2022-11-17T14:10:54.349Z",
23
    "type": "individual",
24
    "created_automatically": false,
25
    "individual": {
26
      "first_name": "Adnan",
27
      "last_name": "Singh",
28
      "title": "Mr.",
29
      "is_vendor": true,
30
      "is_customer": true,
31
      "phone": "5553211234",
32
      "email": "asingh@example.net",
33
      "residential_address": {
34
        "country": "DE",
35
        "city": "Berlin",
36
        "postal_code": "10115",
37
        "state": "BE",
38
        "line1": "Flughafenstrasse 52",
39
        "line2": "Additional address"
40
      }
41
    }
42
  },
43
  "issued_at": null,
44
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
45
  "entity": {
46
    "address": {
47
      "country": "DE",
48
      "city": "Berlin",
49
      "postal_code": "12233",
50
      "state": "BE",
51
      "line1": "Flughafenstrasse 105",
52
      "line2": "Additional address"
53
    },
54
    "email": "user@example.com",
55
    "phone": "55331166",
56
    "created_at": "2022-11-17T14:10:54.349Z",
57
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
58
    "logo": {
59
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
60
      "created_at": "2022-11-17T14:10:54.349Z",
61
      "file_type": "payables",
62
      "name": "invoice.pdf",
63
      "region": "eu-central-1",
64
      "md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
65
      "mimetype": "application/pdf",
66
      "url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
67
      "size": 24381,
68
      "previews": [],
69
      "pages": []
70
    },
71
    "status": "active",
72
    "updated_at": "2022-11-17T14:10:54.349Z",
73
    "type": "individual",
74
    "individual": {
75
      "first_name": "First name",
76
      "last_name": "Last name",
77
      "vat_id": "Vat ID",
78
      "tax_id": "Tax ID",
79
      "title": "Mr."
80
    }
81
  },
82
  "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
83
  "status": "draft",
84
  "document_id": "PO-00123",
85
  "file_url": "https://file.url/67890.pdf",
86
  "file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
87
  "entity_vat_id": {
88
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
89
    "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
90
    "country": "DE",
91
    "type": "eu_vat",
92
    "value": "DE12345678"
93
  }
94
}

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/preview' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -d '{
6
       "subject_text": "New purchase order",
7
       "body_text": "Body of the email."
8
     }'

The successful response contains information about the preview:

1
{
2
  "subject_preview": "New purchase order",
3
  "body_preview": "Body of the email."
4
}

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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_purchase_orders/9d2b4c8f...9683c49a4/send' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -d '{
6
       "subject_text": "New purchase order",
7
       "body_text": "Body of the email."
8
     }'

The successful response contains the ID of the sent email:

1
{
2
  "mail_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
3
}

Notes:

• The purchase order will be sent to the email address of the counterpart’s default contact. 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.

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.

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.