> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-guides/purchase-orders.md).

# Purchase Orders

Create a Purchase Order on a project, and receive stock against it, from a warehouse or supplier system.

When a warehouse system or a supplier's portal handles your deliveries, it needs to tell OrderEazi what arrived. Then your stock is right, and nobody receives it twice. The OrderEazi API can create a Purchase Order (the order you send a supplier) on a project (OrderEazi's record of an order), and receive stock against it.

### Before you start

You'll need:

* **Permissions:** Your key needs **Write** on **For Project**. See [Authentication](/central/developers/authentication.md).
* **A project with the products on it:** A Purchase Order is created from a project's lines.
* **Supplier costs:** Each line needs a cost price.
* **Version 2.0:** Receiving stock is version 2.0 only, so send `x-api-version: 2.0`.

### How to create a Purchase Order

Create it as a document on the project, with `POST /api/project/{pro}/document`, where `{pro}` is the project number, such as `PRO001234`:

```json
{
  "DocumentType": "PurchaseOrder",
  "SupplierName": "Cap Supplier (Pty) Ltd",
  "WarehouseName": "Johannesburg Warehouse",
  "Lines": [
    { "Code": "CAP-PLN", "Quantity": 200, "CostPrice": 38.50 }
  ]
}
```

* **`SupplierName`:** The supplier must exist in OrderEazi, and be the supplier on the project's lines.
* **`WarehouseName`:** This is the warehouse that receives the stock. It's required on the Enterprise licence.
* **`Lines`:** Each line must be on the project. You can't order more than is still to be ordered from that supplier.
* **`DocumentNumber`:** This is optional. Send your system's number for the Purchase Order, to link the two. It must be unique.

The response has the `DocumentNumber` of the new Purchase Order, such as `PO000321`.

### How to receive stock

When the delivery arrives, send a POST to `/api/purchaseorder/receive`:

```json
{
  "PurchaseOrderNumber": "PO000321",
  "SupplierReference": "SUPINV-5541",
  "ReceiveFullPurchaseOrder": false,
  "Lines": [
    { "Code": "CAP-PLN", "Quantity": 196, "Serial": [] }
  ]
}
```

* **`PurchaseOrderNumber`:** The Purchase Order must be open.
* **`SupplierReference`:** This is required. Use the supplier's delivery note or invoice number.
* **`Lines`:** These are the products and quantities that arrived. Send `Serial` on every line, as an empty list if the product has no serial numbers.
* **`ReceiveFullPurchaseOrder`:** Send `true`, with no lines, to receive everything on the Purchase Order.

OrderEazi creates a GRV (Goods Received Voucher, the record of a delivery received) and completes it. The stock is added to the Purchase Order's warehouse, and the product's average cost is updated. When everything has arrived, the Purchase Order's status changes to Received. The response has the GRV's `DocumentNumber`.

**Example:** Purchase Order PO000321 is for 200 caps, and the supplier delivers 196. Your warehouse system receives them with `Quantity` 196 and the supplier's invoice number. The Purchase Order stays open for the last 4.

### When stock can't be received

* **"Purchase order supplied does not exist.":** Check the number, and that the Purchase Order is still open.
* **"Supplier Reference cannot be empty.":** Send the supplier's reference.
* **More than was ordered:** You can't receive more than the Purchase Order asked for, unless the organisation allows over-receiving.

### Related pages

* [Projects and documents](/central/developers/api-guides/projects-and-documents.md): projects and their documents
* [Products and stock levels](/central/developers/api-guides/products-and-stock-levels.md): check stock after receiving