# Purchasing and stock

> How a YoPrint shop buys what it prints on, vendors, purchase orders, needs ordering, receiving, and the stock it keeps at each location. What the API can and can't do with them.

Web page: https://developer.yoprint.com/how-yoprint-works/purchasing-and-stock/

A shop buys the blanks it prints on, such as tees and hats, from **vendors** with **purchase orders**, and keeps **stock** at its locations. In the web app this is **Stock Control**: **Purchase Order**, **Needs Ordering**, **Inventory**, stock takes, adjustments and transfers, and **Vendors**.

> **Caution: Read-mostly in the API**
>
> The public API can read a purchase order, change its status, link it to sales orders, export purchase orders and read stock levels. Creating and receiving purchase orders and adjusting stock happen in the web app, or through an [AI app](https://developer.yoprint.com/ai-apps/capabilities.md).

## What a purchase order holds

**Diagram:** A purchase order's totals are in thousandths when you read one (12500 is 12.50), and decimal strings in exports and reports.

- **Vendor**, a supplier the shop buys from, with its contacts
  - **Purchase order**, with a status, an issue date and a due date
    - **Delivers to** one of the shop's locations (a warehouse in the API)
    - **Lines**: your products, supplier catalog products, custom items or fees
    - **Receipts**: what has arrived, line by line
    - **Linked sales orders**: the orders it buys for

## From an order's needs to stock

When a sales order needs goods the shop doesn't have, its lines show up in **Needs Ordering**. Each needed item then moves through four stages:

**Diagram:** Each line tracks how many are needed, ordered, received and allocated.

1. **Needs ordering**: A sales order needs goods the shop doesn't have
2. **Ordered**: On a purchase order to a vendor
3. **Received**: Arrived at the location
4. **Allocated**: Set aside for the sales order

Goods can arrive in several deliveries. Each delivery is a **receipt**, and once every line (fees aside) has fully arrived, the purchase order moves to its end status, "Completed", by itself. Every status change fires `purchase_order.status_changed`.

The purchase order statuses a new team starts with: Pending, then Awaiting approval, PO confirmed, Awaiting fulfillment and Partially fulfilled, then Completed.

## Stock

Stock is kept per product, and per location (warehouse):

| Number              | What it counts                                            |
| ------------------- | --------------------------------------------------------- |
| `stock_on_hand`     | What's on the shelf, counted from every recorded movement |
| `stock_incoming`    | What's on open purchase orders and hasn't arrived yet     |
| `qty_need_ordering` | What sales orders need that hasn't been ordered           |

Stock changes only through recorded movements: a received delivery, a **stock adjustment** at one location, a **stock transfer** between locations, or a defect. A **stock take** is a count of the shelf that ends as an adjustment. Publishing a sales order holds stock for its lines, and lowering a quantity or deleting a line releases it.

## In the API

[Work with purchase orders](https://developer.yoprint.com/guides/purchase-orders.md): What the API can do with purchase orders today, and what stays in the web app.

[Purchase orders reference](https://developer.yoprint.com/reference/purchase-orders.md): Read, change status, link, export and history.