# Retrieve a purchase order

Operation ID: `getPurchaseOrder`

Group: Accounting › Purchase Orders

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/getPurchaseOrder)

`GET /accounting/purchase-orders/{id}`

Read-only: Reads and returns; changes nothing.

Retrieves a purchase order. Use the purchase order's id, not its poNumber.

The response has the order's lines and approval decisions.

POST accounting/purchase-orders/search returns the same fields for many orders, except approvals. GET accounting/purchase-orders returns orders without their lines.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |
| `id` | path | string | yes | The unique identifier of the purchase order you want to retrieve. Example: `"3d910e5e-0cd0-4b42-a477-1085bcc97fe7"`. |

## Response

`200` Success

Under `data` (getPurchaseOrderOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the purchase order. |
| `poNumber` | string | no | The purchase order number, for example 'PO-3'. Absent while none has been assigned. |
| `description` | string | no | The description of the order, shown to the vendor. |
| `internalDescription` | string | no | Internal notes on the order, not shown to the vendor. |
| `externalMemo` | string | no | A memo intended for the vendor. |
| `externalPONumber` | string | no | The order reference in the vendor's or an upstream system. It is not unique. |
| `approvalStatus` | string | no | The approval status of the order. Possible values: 'approved', 'pendingApproval', 'rejected'. |
| `budgetStatus` | string | no | The budget-check status of the order. Possible values: 'approved', 'rejected', 'pendingApproval'. Independent of approvalStatus. |
| `status` | string | no | The order lifecycle status. Possible values: 'open', 'inprogress', 'closed', 'overMatched'. This is not the vendor-bill matching status, which is per line in each line's matchStatus. |
| `currency` | string | no | The currency the order is denominated in. Format ISO 4217, for example 'USD'. Governs every amount on the order and its lines. |
| `totalAmount` | decimal | no | The total ordered amount, the sum of the line totals, in the order currency. |
| `invoicedTotalAmount` | decimal | no | The portion of the order already invoiced by vendor bills, in the order currency. |
| `receivedTotalAmount` | decimal | no | The portion of the order already received as goods, in the order currency. |
| `startDate` | date | no | The first day of the period the order covers. Format YYYY-MM-DD. |
| `endDate` | date | no | The last day of the period the order covers. Format YYYY-MM-DD. |
| `needByDate` | date | no | The date the goods or services are needed by. Format YYYY-MM-DD. |
| `paymentTerms` | string | no | The payment-terms code applied to this order, for example 'net30', 'net60', 'dueOnReceipt' or 'custom'. Inherited from the vendor unless overridden. |
| `hasInventoryItems` | boolean | no | Whether any line references an inventory item. |
| `vendorId` | string | no | The vendor this order is placed with. See id on GET accounting/vendors/:id. |
| `vendorName` | string | no | The name of the vendor this order is placed with. |
| `vendorContactEmail` | string | no | The main contact email at the vendor. |
| `entityId` | string | no | The legal entity this order is placed by. See id on GET base/entities. |
| `entityName` | string | no | The name of the legal entity this order is placed by. |
| `lastModifiedDate` | date-time | yes | The date and time the purchase order last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `approvals` | array<object> | no | The approval decisions on this order, oldest first. An empty array when no approval policy has matched the order. |
| `approvals[].decision` | string | yes | What was decided. Values include 'approve' and 'reject'. |
| `approvals[].employeeName` | string | no | The name of the employee who decided. |
| `approvals[].message` | string | no | The reviewer's note, where one was given. |
| `approvals[].decidedAt` | date-time | yes | The date and time the decision was recorded, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lines` | array<object> | no | The order line items, in their order on the order. An empty array when the order has none. |
| `lines[].id` | string | yes | The unique identifier for the line item. |
| `lines[].lineNumber` | string | no | The line number, for example 'POL-3'. |
| `lines[].description` | string | no | A description of the line item. |
| `lines[].isItem` | boolean | no | Whether the line is an item line. True when the line references an item, false when it is an expense line. |
| `lines[].quantity` | decimal | no | The quantity ordered, as a decimal. |
| `lines[].price` | decimal | no | The unit price, in the order currency. Set on item lines. On an expense line the amount is in editableAmount instead. |
| `lines[].editableAmount` | decimal | no | The directly entered line amount, in the order currency. Used on expense lines, where there is no unit price to multiply. |
| `lines[].total` | decimal | no | The line total, in the order currency: price times quantity on an item line, editableAmount on an expense line. |
| `lines[].discountPercentage` | decimal | no | The discount applied to the line, as a percentage. 10 means 10%, not 0.10. |
| `lines[].currency` | string | no | The currency of the line. Format ISO 4217, for example 'USD'. It always matches the order currency. |
| `lines[].status` | string | no | The delivery status of the line. Possible values: 'undelivered', 'delivering', 'delivered'. |
| `lines[].matchStatus` | string | no | The vendor-bill matching status of the line. Possible values: 'unmatched', 'partiallyMatched', 'matched', 'overMatched'. |
| `lines[].invoicedStatus` | string | no | The invoicing status of the line. Possible values: 'uninvoiced', 'partiallyInvoiced', 'invoiced', 'overInvoiced'. |
| `lines[].receivedStatus` | string | no | The goods-receipt status of the line. Possible values: 'unreceived', 'partiallyReceived', 'received', 'overReceived'. |
| `lines[].invoicedQuantity` | decimal | no | The quantity invoiced against this line so far, as a decimal. |
| `lines[].invoicedAmount` | decimal | no | The amount invoiced against this line so far, in the order currency. |
| `lines[].receivedQuantity` | decimal | no | The quantity received against this line so far, as a decimal. |
| `lines[].receivedAmount` | decimal | no | The amount received against this line so far, in the order currency. |
| `lines[].remainingAmount` | decimal | no | The amount still open on this line, in the order currency: the line total less what has been invoiced. |
| `lines[].startDate` | date | no | The first day of the period this line covers. Format YYYY-MM-DD. |
| `lines[].endDate` | date | no | The last day of the period this line covers. Format YYYY-MM-DD. |
| `lines[].deliveryDate` | date | no | The date this line was delivered. Format YYYY-MM-DD. |
| `lines[].estimatedDeliveryDate` | date | no | The expected delivery date for this line. Format YYYY-MM-DD. |
| `lines[].unitOfMeasure` | string | no | The name of the unit of measure for the quantity. |
| `lines[].unitOfMeasureId` | string | no | The unit of measure for the quantity. |
| `lines[].itemId` | string | no | The item this line orders. Present on item lines. |
| `lines[].departmentId` | string | no | The department this line is charged to. See id on GET people/departments/:id. |

```json
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "poNumber": "<poNumber>",
    "description": "<description>",
    "internalDescription": "<internalDescription>",
    "externalMemo": "<externalMemo>",
    "externalPONumber": "<externalPONumber>",
    "approvalStatus": "<approvalStatus>",
    "budgetStatus": "<budgetStatus>",
    "status": "<status>",
    "currency": "<currency>",
    "totalAmount": "19.99",
    "invoicedTotalAmount": "19.99",
    "receivedTotalAmount": "19.99",
    "startDate": "2026-01-15",
    "endDate": "2026-01-15",
    "needByDate": "2026-01-15",
    "paymentTerms": "<paymentTerms>",
    "hasInventoryItems": true,
    "vendorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vendorName": "<vendorName>",
    "vendorContactEmail": "<vendorContactEmail>",
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "entityName": "<entityName>",
    "lastModifiedDate": "2026-01-15T09:30:00.000Z",
    "approvals": [
      {
        "decision": "<decision>",
        "employeeName": "<employeeName>",
        "message": "<message>",
        "decidedAt": "2026-01-15T09:30:00.000Z"
      }
    ],
    "lines": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "lineNumber": "<lineNumber>",
        "description": "<description>",
        "isItem": true,
        "quantity": "19.99",
        "price": "19.99",
        "editableAmount": "19.99",
        "total": "19.99",
        "discountPercentage": "19.99",
        "currency": "<currency>",
        "status": "<status>",
        "matchStatus": "<matchStatus>",
        "invoicedStatus": "<invoicedStatus>",
        "receivedStatus": "<receivedStatus>",
        "invoicedQuantity": "19.99",
        "invoicedAmount": "19.99",
        "receivedQuantity": "19.99",
        "receivedAmount": "19.99",
        "remainingAmount": "19.99",
        "startDate": "2026-01-15",
        "endDate": "2026-01-15",
        "deliveryDate": "2026-01-15",
        "estimatedDeliveryDate": "2026-01-15",
        "unitOfMeasure": "<unitOfMeasure>",
        "unitOfMeasureId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "departmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: NOT_FOUND
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error