iotoms Docs

Create a purchase order

POST
/api/v1/procurement/purchase-orders

Creates a draft purchase order for a vendor with its line items and an automatic PO number (PO-YYYYMMDD-NNN). Lines without a unit cost are priced from an agreed price, the last price paid, the vendor's cost list or the item's cost price; the order is rejected if no cost is found.

How to use it

  1. Get the vendor ID from List vendors, item codes from List items and, optionally, a receiving location from List inventory locations.
  2. Send the order date and lines; give unitCost per line or leave it out to use an agreed price, the last price paid, the vendor's cost list or the item's cost price.
  3. The order is created as DRAFT with a PO number and total; lines priced above the agreed or last-paid rate are logged as price variances.
  4. Next, move it through Submit a purchase order, Approve a purchase order and Send a purchase order to the vendor.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
vendorId*string

ID of the vendor to order from — get it from List vendors. Required.

Formatuuid
orderDate*string

Date of the order (YYYY-MM-DD). Required; also used in the generated PO number.

Formatdate
expectedDeliveryDate?|

Date you expect the goods (YYYY-MM-DD). Optional.

Formatdate
notes?|

Free-text notes for the order.

items*array<>

Line items to order. Every item code must exist in the catalog.

rfqId?|

Request for quote this order comes from. Normally set only when the order is created by awarding a quote.

Formatuuid
sourceQuotationId?|

Supplier quotation this order comes from. Normally set only when the order is created by awarding a quote.

Formatuuid

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The purchase order after the call, with its line items.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/procurement/purchase-orders' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "vendorId": "e9b57fab-1850-44d4-8499-71fd15c845a0",  "orderDate": "2019-08-24",  "items": [    {      "itemId": "string",      "orderedQty": 0,      "unitOfMeasure": "string"    }  ]}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "poNumber": "string",    "vendorId": "e9b57fab-1850-44d4-8499-71fd15c845a0",    "vendorName": "string",    "status": "string",    "orderDate": "2019-08-24",    "expectedDeliveryDate": "2019-08-24",    "totalAmount": 0,    "notes": "string",    "items": [      {        "id": 0,        "itemId": "string",        "itemName": "string",        "orderedQty": 0,        "receivedQty": 0,        "outstandingQty": 0,        "unitCost": 0,        "unitOfMeasure": "string",        "uomId": "4df47f00-a69d-4ff2-b50d-4a7649a4b70c",        "receivingLocationId": "f1f8626b-ea08-4582-99e5-64aabd817e6a",        "receivingLocationName": "string",        "sourceQuotationItemId": 0      }    ],    "rfqId": "5483c05b-f58d-4a80-82f1-a80d2c5d2632",    "sourceQuotationId": "5ebd081a-5e1a-48e9-b096-b5f5f5f7febd",    "createdAt": "2019-08-24T14:15:22Z"  }}