docs
/
AI skills

Purchase orders and receiving

Order from a vendor with a Business Made purchase order (stock, equipment and expense lines), approve it, receive each delivery against it so the bill is matched to the order, send goods back for a credit, replacement or refund, and close it. What each step puts in stock, in assets and in Books, and what is refused.

A purchase order (PO) is what the business asks a vendor to supply, at an agreed price, before the goods arrive. It lives in Business Made Storefront › Inventory, on the Purchase orders tab:

  • /storefront/inventory?tab=purchase-orders lists them;
  • &open=<sk> opens one in a drawer;
  • &vendor=<id> opens a vendor.

Returns are on the Supplier returns tab (tab=supplier-returns). The endpoints are under business-made/purchase-orders and business-made/supplier-returns (appengine business-made/controllers/procurement.controller.ts, services/purchase-order.service.ts, services/supplier-return.service.ts), called with call_appengine.

draft ──send for approval──→ awaiting_approval ──approve──→ approved ──receive part──→ partially_received ──receive rest──→ received
  │                               │                           │                            │                                 │
  └────────────approve────────────┼───────────────────────────┘                            └──────────close──────────────────┴──→ closed
                                  └──cancel (nothing received)──→ cancelled

The screen shows Draft, Waiting for approval, Approved, Partly received, Received, Closed and Cancelled. After approval, the server works the status out from what was received. Don't set it yourself.

Nothing is owed and nothing is in the books until goods are received. Each delivery makes its own bill. When the delivery matches the order, that bill is approved and posted in the same step.

Stock that arrives with no order is received in Inventory instead; see Stock levels. A supplier's bill that isn't for goods on an order is entered by hand; see Enter a vendor bill.

Ask first

  • Which vendor, and which location the goods go to.
  • Each line: what it is, how many, and the price agreed with the vendor. It's one of three kinds:
    • Stock: a product you sell, by SKU.
    • Asset: equipment you keep, in whole units.
    • Expense: freight, a service, and so on, with the account it's booked to.
  • Is there a supplier agreement? If the vendor has one in Contracts, the order can use its prices, lead time and payment terms (step 1).
  • Approve now, or send for approval?
  • When goods arrive: how many of each line came, and the price on the vendor's invoice if it differs from the order.

Steps

1. Storefront › Inventory › Purchase orders: New purchase order

New purchase order opens a drawer with these parts:

  • Vendor and delivery: vendor, location, order date and expected delivery.
  • Lines: each with a kind (Stock, Asset or Expense), the item, quantity and unit cost.
    • An asset line also takes an Asset kind.
    • An expense line takes the account.
  • Tax and notes: Tax the vendor charges, and notes for the order.

Save draft keeps it as Draft. Each order gets a number like PO-FVPTAPGA.

Hands on: POST business-made/purchase-orders:

{ "vendorId": "<bm_vendor sk>", "businessLocationId": "<location>", "orderDate": "2026-10-20", "expectedDate": "2026-10-25",
  "contractId": "<bm_contract sk, optional>",
  "lines": [
    { "kind": "stock", "sku": "TEE-M", "description": "Tee, medium", "quantity": 10, "unitCost": 4 },
    { "kind": "asset", "description": "Oven", "quantity": 2, "unitCost": 50, "assetKind": "Kitchen equipment" },
    { "kind": "expense", "description": "Freight", "quantity": 1, "unitCost": 7, "glAccountCode": "6000" } ],
  "taxTotal": 3, "notes": "Deliver to the back door" }

Look the vendor up first with GET business-made/vendors. To change a draft, use POST business-made/purchase-orders/<sk>/update with the same fields.

Check: the order reads Draft, with each line and the totals. Tested: lines of 40 + 100 + 7 and tax 3 read subtotal 147, total 150.

AnswerWhy
"Add at least one line: a product, an asset or an expense."No lines. Tested.
"No product with SKU nope-x. Choose one of your products."A stock line's SKU isn't a product. Tested.
"That location was not found. Choose a saved business location."Tested.
"Line 1 (Freight): choose the expense account."An expense line with no account. Tested.
"Line 1 (Oven): assets are counted in whole units."Tested.
"Line 2 (x): enter a quantity above zero."Tested.
"Order … is waiting for approval; only a draft can be changed."Edit after sending for approval. Tested.

An expense line's account isn't checked. The account code is taken as typed. If it isn't in the chart yet, it's added at the first bill, under the seeded chart's name for that code (tested: code 6000 was added as "Rent Expense"). Pick the account from Books › Chart of accounts.

Under a supplier agreement. Set contractId to an active Supplier agreement in Contracts (see Contracts tracker). Then:

  • Price: a line sent with no unit cost takes the agreement's price for that SKU. When several prices are listed, it takes the one with the highest Min. quantity the line reaches. Tested: 25 units took the 20-and-up price of 3, and 5 units took 3.50.
  • Expected delivery: with none given, it is the order date plus the agreement's lead time. Tested: +7 days.
  • Bill terms: each bill's due date uses the agreement's payment terms (tested: Net 15). Without an agreement, the vendor's own terms apply, or 30 days.
  • Returns: a return after the agreement's return window is refused (RETURN_WINDOW_CLOSED).
  • Ended agreements: an agreement that has been terminated or has expired is refused for a new order. Tested: "skilltest-supply-agreement has been terminated, so nothing is bought under it now. Choose an agreement in force, or none." A draft order already made under it can still be edited.

The agreement's Minimum order isn't enforced. Tested: an agreement with a minimum order of 500 took a $17.50 order. Check it yourself.

2. Storefront › Inventory › Purchase orders: Send for approval, Approve

Open the order:

  • Send for approval (POST …/<sk>/submit) moves it to Waiting for approval, and the lines are locked.
  • Approve (POST …/<sk>/approve) works from Draft or from Waiting for approval.

Approving posts nothing to the books. It opens the lines for receiving.

Stop: approving is what you send the vendor against. Show the vendor, each line with its quantity and price, the total and the expected date. Wait for yes. Appmint doesn't send the order to the vendor. Send it yourself, by the vendor's usual channel, only when you're told to.

Check: the order reads Approved, with who approved it and when.

Send for approval tells nobody. It records who sent it and when, but no notice or email goes out. Tell the approver yourself.

3. Storefront › Inventory › Purchase orders: Receive

On an approved order, each line shows Ordered, Received, Billed, Returned and To come. To receive a line, type how many arrived and press Receive. The screen receives at the order's price.

Hands on: POST business-made/purchase-orders/<sk>/deliveries:

{ "items": [ { "poLineId": "ln-ux5pziji4r", "quantity": 6, "unitCost": 4 } ],
  "reference": "Vendor invoice 1182", "receive": true }
  • unitCost is optional and defaults to the order's price. Send it when the vendor's invoice says something else.
  • Several lines can arrive in one delivery.
  • With receive: false, the delivery is saved as pending. Receive it later with POST business-made/purchase-orders/deliveries/<intakeId>/receive, or with Receive the delivery on the line. Receiving the same delivery twice does nothing more (tested).

Stop: receiving adds the stock and records what's owed to the vendor in Books. Show each line, the quantity and the price. Wait for yes.

Receiving one delivery does all of this:

WhatWhere it goes
Stock linesInto stock at the order's location. The unit cost is averaged in.
Asset linesOne asset per unit, named " #1", "#2"… It's in service, depreciated straight-line over 60 months, and linked to the bill. Tested.
The billB-<order #>-<n>. It's dated the location's business date and due by the agreement's or vendor's terms. Its lines are the goods received: stock to Inventory 1200, assets to Fixed Assets 1500, expenses to their own account.
BooksA matched bill is approved and posted: Dr each line's account, Cr Accounts Payable 2000. Tested: 6 units at 4 posted Dr 24 on 1200 and Cr 24 on 2000.

A price that differs from the order holds the bill. It is saved as Held for review (disputed), with nothing posted. Its note says what differs. Tested:

"Held for review — this bill does not match purchase order PO-…. skilltest PO widget: ordered at $4.00, delivered at $4.50. Check the vendor's invoice, correct the bill if needed, then approve it in Books › Payable."

Later deliveries on the same order are added to the held bill, not to a new one (tested). Settle it in Books › Payable: correct it if needed, then Approve; see Enter a vendor bill. Tested: approving it posted the stock, asset and expense lines together.

Check: the line's Received count went up and To come went down. The order reads Partly received or Received. The bill is in Books › Payable, and its journal entry is in Books › Journal.

AnswerWhy
"Approve order PO-… before receiving against it."Tested.
OVER_RECEIPT"…10 still to come on order …, so 11 cannot be received. Receive what was ordered and send any extra back to the vendor." Tested.
"Order … is closed; nothing more is received on it."Tested.

The order's tax never reaches the bill. Bills made from deliveries carry the goods only, with tax 0. Tested: an order of 147 + 3 tax made bills totalling 147. If the vendor's invoice charges tax, add it to the bill in Books › Payable before you approve it, or enter it as its own bill.

4. Storefront › Inventory › Supplier returns: send goods back

On a received line, press Send back. The return drawer asks:

  • what goes back and how many;
  • why;
  • the vendor's return number (RMA);
  • what the vendor will do: credit, replace or refund.

Save return keeps it as Draft.

Hands on:

  • Create it with POST business-made/supplier-returns { purchaseOrderId, rmaNumber?, outcome: "credit"|"replace"|"refund", lines: [{ poLineId, quantity, reason }], notes? }.
  • For an asset unit, send assetId on the line too.
  • A return with no order takes vendorId and sku or assetId instead.

Then the return goes through three steps:

  1. Send the goods back (POST …/<sk>/send). The stock leaves the location, and an asset is marked returned. The order's Returned count goes up. Tested: stock went from 10 to 8, and the average unit cost stayed the same.
  2. When the vendor has acted, press Record what the vendor did (POST …/<sk>/complete { outcome, refundDate?, bankAccountId? }).
  3. The outcome decides what's recorded:
OutcomeWhat's recorded
CreditA vendor credit CR-<return #>, approved: Dr 2000, Cr the goods' account. It's valued at what was billed, oldest delivery first. Tested: 2 units credited at 4 = 8, with the RMA as the vendor ref. Use it on the vendor's next bill with Use credits; see Enter a vendor bill.
ReplaceNo credit. The order line reopens, so the replacement is received in step 3. It isn't billed twice. Tested: one oven sent back reopened the line, and receiving 2 billed only 1.
RefundThe credit is made and paid back at once: Dr the bank (or cash), Cr 2000. Read in code, not tested.

Stop: sending stock back and recording a credit or refund change stock and what's owed. Show the lines, the quantities and the outcome. Wait for yes at each step. Nothing is sent to the vendor.

Check: the return reads Sent back, then Credited, Replaced or Refunded. The order line's Returned count is right.

AnswerWhy
"10 received and not already returned; 11 cannot go back."Tested.
"Send return … first: the goods have not left yet."Recording an outcome before sending. Tested.

A draft return can be cancelled (POST …/<sk>/cancel).

5. Storefront › Inventory › Purchase orders: Close or cancel

  • Close order (POST …/<sk>/close) ends an approved or partly received order. What arrived stays received and billed, and nothing more is received on it.
  • Cancel order (POST …/<sk>/cancel { reason }) is only for an order with nothing received.

Stop: show the order and what's still to come. Wait for yes.

AnswerWhy
"Delivery INT-… is still waiting to be received on this order. Receive or cancel it, then close the order."A pending delivery. Tested.
"Goods have been received on order … Close it instead: what arrived stays received and billed."Cancel after receiving. Tested.
"Say why the order is being cancelled."No reason.

Check: the order reads Closed or Cancelled.

What's still to come

  • GET business-made/purchase-orders?status=approved,partially_received lists the orders open for receiving. The screen's status filter Open for receiving does the same.
  • q searches the order number, vendor name, line SKUs and descriptions, and notes. vendorId and businessLocationId filter. Tested: q=<sku>&status=closed,received.
  • GET business-made/purchase-orders/<sk> gives each line's ordered, received, billed, returned and outstanding counts, the deliveries, bills and returns, and the actions allowed now.
  • The Inventory Intakes tab's Receive against a purchase order opens the same open-for-receiving list.

When it's done

  • The order reads Received or Closed. Every line's To come is 0, or the rest was let go when it was closed.
  • Each delivery has a bill in Books › Payable. A matched bill is approved and posted. A held one has been checked and approved.
  • Each return reads Credited, Replaced or Refunded. Credits are used against the vendor's next bill.

What it can't do yet

  • No sending the order to the vendor. No email or PDF of the order goes out.
  • The order's tax isn't billed (step 3).
  • The agreement's Minimum order isn't checked (step 1).
  • Bill numbers can skip. A delivery's bill number counts the credits on the order as well. Tested: after a credit, the next bill was -4, not -3.
  • A quantity difference can't be held. More than is still to come is refused, and less is a part delivery. Only a price difference holds a bill.
  • No approval notice when an order is sent for approval (step 2).

Don'ts

  • Don't approve, receive, send back or record a credit without a yes on that order.
  • Don't contact the vendor or send them the order unless you're told to.
  • Don't receive more than arrived to make the numbers match. Receive what came, and send any extra back.
  • Don't approve a held bill without checking the vendor's invoice against the order.
  • Don't edit the status, counts or bills on the order record by hand (repo_update). Use the actions above.
  • Don't delete an order, delivery or bill that has been received or posted. Close the order, or void the bill in Books › Payable.