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:

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 from draft to issued and the issued_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 or issued_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.