This guide walks the purchasing lifecycle end to end with the Internal Teams API: technicians raise purchase requests (PRs), your purchasing system turns them into purchase orders (POs) with a vendor, and goods arrive as receipts that update stock. It assumes you have a partner API key (see the introduction).
All examples assume:
Status vocabulary
Purchase requests: requested, denied, cancelled, approved, orderInProgress, ordered, partially_ordered, fulfilled, partially_fulfilled. A PR’s status is recomputed from its line items as they get associated to POs, so most of the movement happens automatically.
Purchase orders: new, ordered, received, partially_received, cancelled, closed.
1. Read approved purchase requests
Any query parameter other than the paging parameters acts as an equality filter on the entity’s columns (status=approved, stockLocationId=42), always inside your company’s scope.
For a cross-PR worklist, query line items directly:
PR statuses can also be set directly when your approval flow lives outside OpenWrench: PATCH .../purchase_requests/{id}/{status} for any status in the vocabulary, and PATCH .../purchase_requests/{id}/cancelled to cancel (only from requested or approved; otherwise 400).
2. Create the purchase order
POST /v1/partners/inventory/purchase_orders creates the PO with its line items in one call. Required: status (typically new), partEquipmentVendorId, currencyId, and createdByEmail. totalCost is required unless your company’s inventory settings mark PO cost as non-mandatory (it is mandatory by default). supplierCompanyId and supplierFacilityId are derived from your key.
Each line item sets isEquipmentLine and then either the part* fields or the equipment* fields. prLineItemIds records which PR lines the PO line fulfils. Passing a top-level id replaces an existing PO’s writable fields instead of creating a new one.
Associate PR line items
If you did not link PRs via prLineItemIds at creation time, associate them explicitly:
Each listed PR line item moves to orderInProgress with its associatedPurchaseOrderLineItemId set, and each parent PR’s status is recomputed. Ids your key cannot read are silently skipped (the call can return an empty list), so verify the returned items against what you sent.
Revise line items
POST /v1/partners/inventory/purchase_order_line_items/bulk takes a JSON array of line items, all referencing the same supplierPurchaseOrderId, and has replace semantics:
All existing non-received line items on the PO are deleted first, then the submitted ones are created. Send the complete intended set of open lines every time. Line status is not settable here: new lines start as new, and a line resubmitted with its id keeps its status.
supplierFacilityId/supplierCompanyId per item come from your key; items without write permission are silently skipped.
3. Mark the order placed
This sets the PO to ordered and emails the order to the vendor. The success response is the confirmation string envelope ("type": "Email", "data": "Email has been sent"), not the PO; re-fetch the PO for its new state. To abort instead, PATCH .../purchase_orders/{id}/cancel (which does return the updated PO).
4. Record receipts as goods arrive
PUT /v1/partners/inventory/purchase_order_receipts records receiving against one PO line item. On this endpoint updatedBy and supplierFacilityId must be supplied in the body; they are not derived from the key.
Rules:
receiptNumber, purchaseOrderId, purchaseOrderLineItemId, receivedQuantity, updatedBy, and supplierFacilityId are required.receivedQuantity must be non-zero; a negative value records a return.- Updating a receipt adjusts the received quantities and costs on the PO line item and the stock records at the destination stock location.
- For serialized equipment, send one entry per unit in
equipmentPerStockLocationReceiptValues, assetReceiptValues, or receiptValuesWithoutId. The array length must equal receivedQuantity, these arrays may not accompany a return, and serial or asset numbers already in use are rejected.
- Vendor invoice metadata (
invoiceNumber, invoiceCurrency, invoiceTotal, exchangeRate, invoiceTotalPostExchange) can be captured on the receipt.
Read a receipt back with GET /v1/partners/inventory/purchase_order_receipts/{id}.
Idempotency and error handling
- Creates are not idempotent: retrying a timed-out PO create can duplicate the order. Use the list endpoint with a filter (for example on your
receiptNumber-style external references) to check before retrying.
- Permission problems surface as
400 (with the standard error envelope), and silently-skipped ids on the bulk and associate endpoints mean a “successful” call may have done less than you asked. Always reconcile the response payload against your request.
- The catalog endpoints supply the
partId, equipmentTypeId, partEquipmentVendorId, and stockLocationId values this flow needs.
- Every purchase order, line item, and receipt change made through these endpoints is recorded on the purchase order’s audit trail in OpenWrench, attributed to the contact behind your API key.
