> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase orders

> Learn how to create and manage purchase orders in Tesouro.

## Overview

A purchase order is a document created by an [organization](/finops/support/glossary#organization) with precise information about products and/or services that the organization intends to purchase from a [counterpart](/finops/support/glossary#counterpart) (vendor). It also contains the organization and counterpart data.

Each item in the purchase order must have:

* name
* quantity
* unit
* price (with currency)
* tax\_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

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`:

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payable-purchase-orders' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_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": "units",
            "price": 100,
            "currency": "USD",
            "tax_rate": 10000.0
          }
        ],
        "message": "This is a purchase order.",
        "currency": "USD",
      }'
```

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

```json expandable lines theme={null}
{
  "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "valid_for_days": 7,
  "items": [
    {
      "name": "Ice cream",
      "quantity": 10,
      "unit": "units",
      "price": 100,
      "currency": "USD",
      "tax_rate": 10000.0
    }
  ],
  "message": "This is a purchase order.",
  "currency": "USD",
  "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": "US",
        "city": "Austin",
        "postal_code": "78701",
        "state": "TX",
        "line1": "123 Congress Ave",
        "line2": "Additional address"
      }
    }
  },
  "issued_at": null,
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity": {
    "address": {
      "country": "US",
      "city": "Austin",
      "postal_code": "78702",
      "state": "TX",
      "line1": "456 Oak St",
      "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/<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",
      "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:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payable-purchase-orders/9d2b4c8f...9683c49a4/preview' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_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 lines theme={null}
{
  "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.

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payable-purchase-orders/9d2b4c8f...9683c49a4/send' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_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 lines theme={null}
{
  "mail_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

Notes:

* The purchase order will be sent to the email address of the counterpart's [default contact](/finops/guides/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](/finops/reference/openapi/partner-settings/patch-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.

<Info>Resending a purchase order does not change its `status` or `issued_at` date.</Info>

## List all purchase orders

To get information about all purchase orders associated with the specified organization, 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.