Create Purchase Change Order

Published on Oct 7, 2026

Post

/po-rest-api/jersey/v1/po-change-order

PO Change Order — Create from Purchase Order

Overview

Creates a new change order header from its parent purchase order and automatically generates
all of its summary lines. The caller only identifies which purchase order and release to base
the change order on — the change order number, every header value, and the summary lines are
all generated automatically.

Notes

The whole operation — release validation, header build, line population — runs inside a
single transaction. If any step fails the transaction is rolled back and nothing is
persisted.
header.pocohNum is ignored if supplied by the client (a warning is logged) — the change
order number is always generated by the database from the PO/release.
Database routines invoked (no business logic reimplemented in Java):
- da.dbk_po_comst.validate_rel_num — rejects if an open CO already exists for the release
  (PO-000033-ERR), or the PO is not in an eligible status for a Change Order at that release
  (PO-000179-ERR, requires status O/A, or C with default receiving code A).
- da.dbk_po_comst.create_co_from_po — generates the CO number and copies the header from
  the PO.
- da.dbk_po_comst.populate_co_details — generates the summary lines.
The header's virtual UUID (pocohVUuid) is generated on the Java side via sys_guid()
(Utility.generateVuuid), available before the row is even posted.
On success, the response is built by re-reading the created change order the same way as
GET /{vuuid} — header from PO_COMAST_API_V, lines from PO_COSUMMARY_API_V.

Asset Management → Purchase Order → Change Orders → Enter Change Order

Finders

Not applicable — this is a create operation.

HTTP Method & Endpoint

POST {base_url}/po-rest-api/jersey/v1/po-change-order
Content-Type: application/json

Path Parameters

None.

Query Parameters

None.

Example Request

curl -X POST "{base_url}/po-rest-api/jersey/v1/po-change-order" \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "pocohCompCode": "ALT",
      "pocohPoNum": "PO000004",
      "pocohReleaseNum": 1
    }
  }'

Example Response (201 Created)

{
  "header": {
    "pocohVUuid": "57583E9AF08A542CE0630B811DACCB66",
    "pocohCompCode": "ALT",
    "pocohPoNum": "PO000004",
    "pocohNum": "2",
    "pocohReleaseNum": 1,
    "pocohStatCode": "O"
  },
  "lines": [
    { "pocsVUuid": "...", "pocsLineNum": 1, "pocsItmCode": "PAPER-A4" }
  ]
}

Attributes

Request body — `header` object

Name	Description	Type	Required	Notes
pocohCompCode	Company code of the parent PO	String(8)	True	Uppercased before use
pocohPoNum	Parent Purchase Order number	String(11)	True	Uppercased before use
pocohReleaseNum	PO release number the change order is created against	Number(11)	True	Must resolve via `validate_rel_num`
pocohNum	Change order number	String(11)	Ignored if supplied	Always generated by `create_co_from_po`; a client-supplied value is logged and discarded

No other header fields are read from the request body on create — every other attribute on the
response header is copied from the parent PO by create_co_from_po.

Response body — `header` object

Name	Object	Description	Type	Data Length	Example	Mandatory
pocohVUuid	header	Virtual UUID, unique row identifier	String	64	57583E9AF08A542CE0630B811DACCB66	System Generated
pocohCompCode	header	Company code	String	8	ALT	Key
pocohCompName	header	Company name (lookup)	String	30	ALT Company	System Generated
pocohPoNum	header	Parent Purchase Order number	String	11	PO000004	Key
pocohNum	header	Change order number	String	11	1	Key
pocohBchNum	header	Posting batch number	Number(11)	11	42	System Assigned
pocohVenCode	header	Vendor code	String	8	V0001	False
pocohVenName	header	Vendor name (lookup)	String	50	ACME Supplies	System Generated
pocohDeptCode	header	Department code	String	6	ADMIN	False
pocohDeptName	header	Department name (lookup)	String	30	Administration	System Generated
pocohExptdDate	header	Expected date	Date	—	2026-09-01	False
pocohOrdDate	header	Order date	Date	—	2026-08-20	False
pocohRecDate	header	Receipt date	Date	—	2026-09-05	False
pocohTypeCode	header	Change order type code	String	1	S	False
pocohAdjCode	header	Adjustment code	String	1	A	False
pocohStatCode	header	Status code	String	1	O	System Assigned
pocohChgCode	header	Change code	String	1	C	False
pocohTermCode	header	Payment terms code	String	6	NET30	False
pocohTermName	header	Payment terms name (lookup)	String	30	Net 30 Days	System Generated
pocohInvCode	header	Invoice code	String	20	INV001	False
pocohInvDate	header	Invoice date	Date	—	2026-09-10	False
pocohInvDueDate	header	Invoice due date	Date	—	2026-10-10	False
pocohInvDiscDate	header	Invoice discount date	Date	—	2026-09-20	False
pocohInvDiscAmt	header	Invoice discount amount	Number(18,2)	18,2	25.00	False
pocohCurrCode	header	Currency code	String	3	USD	False
pocohCurrName	header	Currency name (lookup)	String	30	US Dollar	System Generated
pocohFobCode	header	FOB code	String	2	FO	False
pocohBuyCode	header	Buyer code	String	30	BUYER01	False
pocohAddCode	header	Ship-to address code	String	8	ADDR01	False
pocohShplneCode	header	Shipping line code	String	3	UPS	False
pocohShpmetCode	header	Shipping method code	String	5	GRND	False
pocohTxt1Code	header	Text code 1	String	8	TXT01	False
pocohTxt2Code	header	Text code 2	String	8	TXT02	False
pocohShpinstDesc	header	Shipping instructions	String	2000	Deliver to loading dock	False
pocohDesc1	header	Description line 1	String	2000	Revised material order	False
pocohDesc2	header	Description line 2	String	2000	Adds 2 items	False
pocohAdjPrice	header	Adjusted price total	Number(18,4)	18,4	1250.0000	False
pocohUnadjPrice	header	Unadjusted price total	Number(18,4)	18,4	1200.0000	False
pocohCurrConvNum	header	Currency conversion rate	Number(16,8)	16,8	1.00000000	False
pocohCostedCode	header	Costed flag	String	1	Y	False
pocohRefNum	header	Reference number	String	11	REF001	False
pocohRefDate	header	Reference date	Date	—	2026-08-15	False
pocohReqCode	header	Requisition code	String	30	RQ000003	False
pocohRecCode	header	Receiving code	String	30	REC001	False
pocohReprintDate	header	Reprint date	Date	—	2026-08-22	False
pocohWipAccCode	header	WIP account code	String	16	WIP-01	False
pocohWipAccName	header	WIP account name (lookup)	String	30	Work In Progress 01	System Generated
pocohWipDeptCode	header	WIP department code	String	6	WIPD01	False
pocohWipDeptName	header	WIP department name (lookup)	String	30	WIP Department 01	System Generated
pocohShipinstTxt1Code..5Code	header	Shipping instruction text codes 1-5	String	8 each	TXT01	False
pocohReleaseNum	header	PO release number this change order belongs to	Number(11)	11	1	Key
pocohBilltoAddCode	header	Bill-to address code	String	8	BILL01	False
pocohReqReason	header	Requisition reason	String	255	Scope change	False
pocohInvTypeCode	header	Invoice type code	String	1	S	False
pocohImageFilename	header	Attached image filename	String	255	co_scan.pdf	False
pocohInvSerCode	header	Invoice series code	String	4	2026	False
pocohVendOrderAddCode	header	Vendor order address code	String	5	VOA01	False
pocohComplianceFlag	header	Compliance flag (Y/N)	String	1	Y	False
pocohJobCompCode	header	Job company code	String	8	ALT	False
pocohJobCompName	header	Job company name (lookup)	String	30	ALT Company	System Generated
pocohJobCode	header	Job code	String	10	JOB001	False
pocohJobName	header	Job name (lookup)	String	60	Office Renovation	System Generated
pocohContactCode	header	Contact code	String	10	CONT01	False
pocohAddCompCode	header	Ship-to address company code	String	8	ALT	False
pocohAddCompName	header	Ship-to address company name (lookup)	String	30	ALT Company	System Generated
pocohPrintDate	header	Print date	Date	—	2026-08-21	False
pocohDefaultRecCode	header	Default receiving code	String	1	A	False
pocohDate	header	Change order date	Date	—	2026-08-20	False
pocohPoTotal	header	Total PO amount (calculated)	Number	—	12500.00	System Generated
pocohIuCreateDate	header	Record creation timestamp (ISO-8601)	Timestamp	—	2026-08-20T10:15:00-04:00	System Generated
pocohIuCreateUser	header	User who created the record	String	30	DA	System Generated
pocohIuUpdateDate	header	Record last update timestamp (ISO-8601)	Timestamp	—	2026-08-21T09:00:00-04:00	System Generated
pocohIuUpdateUser	header	User who last updated the record	String	30	DA	System Generated
pocohAcctDescription	header	Account description (lookup)	String	500	General WIP Account	System Generated
pocohDiscountPct	header	Discount percentage	Number(16,3)	16,3	2.500	False
pocohAddName	header	Ship-to address name (lookup)	String	195	Main Warehouse	System Generated

Response body — `lines[]` items

Name	Object	Description	Type	Data Length	Example	Mandatory
pocsVUuid	line	Virtual UUID, unique row identifier	String	64	57583E9AF08B542CE0630B811DACCB66	System Generated
pocsCompCode	line	Company code	String	8	ALT	Key
pocsPoNum	line	Parent PO number	String	11	PO000004	Key
pocsNum	line	Change order number	String	11	1	Key
pocsReleaseNum	line	Release number	Number(11)	11	1	Key
pocsLineNum	line	Summary line number	Number(6)	6	1	Key
pocsCiitemtypCode	line	item type code	String	2	MA	False
pocsClassCode	line	Item class code	String	4	OFF1	False
pocsDesc	line	Line description	String	4000	Revised paper order	False
pocsDiscountPct	line	Discount percentage	Number	—	2.500	False
pocsExptdPriceAmt	line	Expected unit price	Number	—	12.5000	False
pocsExtdAmt	line	Extended amount (calculated)	Number	—	1250.00	System Generated
pocsItemLocCode	line	Item location code	String	7	ILOC01	False
pocsItmCode	line	Item/product code	String	16	PAPER-A4	False
pocsItmName	line	Item/product name (lookup)	String	4000	A4 Copy Paper	System Generated
pocsJobName	line	Job name (lookup)	String	60	Office Renovation	System Generated
pocsPhsName	line	Phase name (lookup)	String	50	Phase 1	System Generated
pocsCatName	line	Category name (lookup)	String	30	Supplies	System Generated
pocsLumpSumPoFlag	line	Lump-sum PO flag (Y/N, calculated)	String	1	N	System Generated
pocsOrdQty	line	Quantity ordered	Number	—	100.0000	False
pocsOvrdExptdPriceFlag	line	Override expected price flag (Y/N)	String	1	Y	False
pocsPoItemType	line	PO item type (I=Inventory, N=Non-stock, F=Free-form)	String	1	N	False
pocsPoOrdQty	line	PO ordered quantity (calculated)	Number	—	80.0000	System Generated
pocsPoOrderedQty	line	PO ordered quantity, alt calculation (calculated)	Number	—	80.0000	System Generated
pocsPoPriceAmt	line	PO price amount (calculated)	Number	—	12.5000	System Generated
pocsPobldLineNum	line	Source PO build line number (calculated)	Number(6)	6	1	System Generated
pocsRecIntoInvFlag	line	Receive into inventory flag (Y/N)	String	1	Y	False
pocsSuggestedPrice	line	Suggested price (calculated)	Number	—	12.5000	System Generated
pocsTax1Code / Tax2Code / Tax3Code	line	Tax codes 1-3	String	11 each	HST	False
pocsTax1TaxableFlag / Tax2.../Tax3...	line	Taxable flags for tax 1-3 (Y/N)	String	1 each	Y	False
pocsTaxAmt	line	Tax amount (calculated)	Number	—	150.00	System Generated
pocsTotAmt	line	Total amount (calculated)	Number	—	1400.00	System Generated
pocsUserField1..8	line	User-defined fields 1-8	String	60 each	—	False
pocsUserTypeCode	line	User-defined type code	String	3	STD	False
pocsWmCode	line	Unit of measure code	String	2	BX	False
pocsTavCode1..4	line	TAV codes 1-4	String	10 each	TAV01	False
pocsWbsvCode1..8	line	WBS value codes 1-8 (always disabled in CMiC UI)	String	60 each	—	System Generated
pocsWbsvCode9..12	line	WBS value codes 9-12	String	60 each	—	False
pocsIuCreateDate	line	Record creation timestamp (ISO-8601)	Timestamp	—	2026-08-20T10:15:00-04:00	System Generated
pocsIuUpdateDate	line	Record last update timestamp (ISO-8601)	Timestamp	—	2026-08-21T09:00:00-04:00	System Generated

Error Codes

HTTP	Error Code	Reason
400	PO-000272-ERR	Request body is required
400	PO-000264-ERR	`header` object is required in the request payload
400	PO-000273-ERR	`header.pocohCompCode` is required
400	PO-000274-ERR	`header.pocohPoNum` is required
400	PO-000275-ERR	`header.pocohReleaseNum` is required
500	PO-000033-ERR	An open Change Order already exists for this company/PO/release (`validate_rel_num`)
500	PO-000179-ERR	The PO is not in an eligible status for a Change Order at that release (`validate_rel_num`)
500	PO-000221-ERR	The change order could not be re-read immediately after creation (should not occur under normal operation)
500	(unhandled exception)	Any other unexpected error; the transaction is rolled back

Security

HTTP

Type basic

Basic authentication

Header parameters

Content-Type

string

Exampleapplication/json

cmic-debug-token

string

Example59E49DF371288944E06327261DACB907

Body parameters

object

Example{ "header": { "pocohCompCode": "ZZ", "pocohPoNum": "8933", "pocohReleaseNum": "1" } }

Responses

201

Created

Headers

Content-Type

string

Exampleapplication/json

"{\n    \"header\": {\n        \"pocohVUuid\": \"596EF33010A84F19E0630B811DACF02D\",\n        \"pocohCompCode\": \"ZZ\",\n        \"pocohCompName\": \"CMiC-ZZ  Test Company Incorp\",\n        \"pocohPoNum\": \"987943\",\n        \"pocohNum\": \"2\",\n        \"pocohBchNum\": null,\n        \"pocohVenCode\": \"ZZ-ACME\",\n        \"pocohVenName\": \"ZZ-Acme & Supply\",\n        \"pocohDeptCode\": null,\n        \"pocohDeptName\": null,\n        \"pocohExptdDate\": null,\n        \"pocohOrdDate\": \"2021-01-28\",\n        \"pocohRecDate\": null,\n        \"pocohTypeCode\": \"S\",\n        \"pocohAdjCode\": null,\n        \"pocohStatCode\": \"N\",\n        \"pocohChgCode\": \"O\",\n        \"pocohTermCode\": \"NET30\",\n        \"pocohTermName\": \"Net 30\",\n        \"pocohInvCode\": null,\n        \"pocohInvDate\": null,\n        \"pocohInvDueDate\": null,\n        \"pocohInvDiscDate\": null,\n        \"pocohInvDiscAmt\": null,\n        \"pocohCurrCode\": \"US\",\n        \"pocohCurrName\": \"US Dollars\",\n        \"pocohFobCode\": null,\n        \"pocohBuyCode\": null,\n        \"pocohAddCode\": null,\n        \"pocohShplneCode\": null,\n        \"pocohShpmetCode\": null,\n        \"pocohTxt1Code\": null,\n        \"pocohTxt2Code\": null,\n        \"pocohShpinstDesc\": null,\n        \"pocohDesc1\": null,\n        \"pocohDesc2\": null,\n        \"pocohAdjPrice\": null,\n        \"pocohUnadjPrice\": null,\n        \"pocohCurrConvNum\": 1,\n        \"pocohCostedCode\": null,\n        \"pocohRefNum\": null,\n        \"pocohRefDate\": null,\n        \"pocohReqCode\": null,\n        \"pocohRecCode\": null,\n        \"pocohReprintDate\": null,\n        \"pocohWipAccCode\": null,\n        \"pocohWipAccName\": null,\n        \"pocohWipDeptCode\": null,\n        \"pocohWipDeptName\": null,\n        \"pocohShipinstTxt1Code\": null,\n        \"pocohShipinstTxt2Code\": null,\n        \"pocohShipinstTxt3Code\": null,\n        \"pocohShipinstTxt4Code\": null,\n        \"pocohShipinstTxt5Code\": null,\n        \"pocohReleaseNum\": 1,\n        \"pocohBilltoAddCode\": null,\n        \"pocohReqReason\": null,\n        \"pocohInvTypeCode\": null,\n        \"pocohImageFilename\": null,\n        \"pocohInvSerCode\": null,\n        \"pocohVendOrderAddCode\": null,\n        \"pocohComplianceFlag\": \"N\",\n        \"pocohJobCompCode\": \"ZZ\",\n        \"pocohJobCompName\": \"CMiC-ZZ  Test Company Incorp\",\n        \"pocohJobCode\": null,\n        \"pocohJobName\": null,\n        \"pocohContactCode\": null,\n        \"pocohAddCompCode\": \"ZZ\",\n        \"pocohAddCompName\": \"CMiC-ZZ  Test Company Incorp\",\n        \"pocohPrintDate\": null,\n        \"pocohDefaultRecCode\": \"A\",\n        \"pocohDate\": null,\n        \"pocohPoTotal\": 46,\n        \"pocohIuCreateDate\": \"2026-08-19T18:57:08-04:00\",\n        \"pocohIuCreateUser\": \"YASHB\",\n        \"pocohIuUpdateDate\": null,\n        \"pocohIuUpdateUser\": null,\n        \"pocohAcctDescription\": null,\n        \"pocohDiscountPct\": 0,\n        \"pocohAddName\": null\n    },\n    \"lines\": [\n        {\n            \"pocsVUuid\": \"596EF33010A94F19E0630B811DACF02D\",\n            \"pocsCompCode\": \"ZZ\",\n            \"pocsPoNum\": \"987943\",\n            \"pocsNum\": \"2\",\n            \"pocsReleaseNum\": 1,\n            \"pocsLineNum\": 1,\n            \"pocsCiitemtypCode\": null,\n            \"pocsClassCode\": null,\n            \"pocsDesc\": null,\n            \"pocsDiscountPct\": 0,\n            \"pocsExptdPriceAmt\": 2,\n            \"pocsExtdAmt\": 0,\n            \"pocsItemLocCode\": null,\n            \"pocsItmCode\": \"ITEM 77\",\n            \"pocsItmName\": \"77\",\n            \"pocsJobName\": null,\n            \"pocsPhsName\": null,\n            \"pocsCatName\": null,\n            \"pocsLumpSumPoFlag\": null,\n            \"pocsOrdQty\": 0,\n            \"pocsOvrdExptdPriceFlag\": null,\n            \"pocsPoItemType\": \"F\",\n            \"pocsPoOrdQty\": 23,\n            \"pocsPoOrderedQty\": 23,\n            \"pocsPoPriceAmt\": 2,\n            \"pocsPobldLineNum\": null,\n            \"pocsRecIntoInvFlag\": \"N\",\n            \"pocsSuggestedPrice\": null,\n            \"pocsTax1Code\": null,\n            \"pocsTax1TaxableFlag\": \"Y\",\n            \"pocsTax2Code\": null,\n            \"pocsTax2TaxableFlag\": \"Y\",\n            \"pocsTax3Code\": null,\n            \"pocsTax3TaxableFlag\": \"Y\",\n            \"pocsTaxAmt\": 0,\n            \"pocsTotAmt\": 0,\n            \"pocsUserField1\": \"ZZ\",\n            \"pocsUserField2\": \"00\",\n            \"pocsUserField3\": \"1000.100\",\n            \"pocsUserField4\": null,\n            \"pocsUserField5\": null,\n            \"pocsUserField6\": null,\n            \"pocsUserField7\": null,\n            \"pocsUserField8\": null,\n            \"pocsUserTypeCode\": \"G\",\n            \"pocsWmCode\": \"EA\",\n            \"pocsTavCode1\": null,\n            \"pocsTavCode2\": null,\n            \"pocsTavCode3\": null,\n            \"pocsTavCode4\": null,\n            \"pocsWbsvCode1\": null,\n            \"pocsWbsvCode2\": null,\n            \"pocsWbsvCode3\": null,\n            \"pocsWbsvCode4\": null,\n            \"pocsWbsvCode5\": null,\n            \"pocsWbsvCode6\": null,\n            \"pocsWbsvCode7\": null,\n            \"pocsWbsvCode8\": null,\n            \"pocsWbsvCode9\": null,\n            \"pocsWbsvCode10\": null,\n            \"pocsWbsvCode11\": null,\n            \"pocsWbsvCode12\": null,\n            \"pocsIuCreateDate\": \"2026-08-19T18:57:08-04:00\",\n            \"pocsIuUpdateDate\": null\n        }\n    ]\n}"

string

Create Purchase Change Order

PO Change Order — Create from Purchase Order

Overview

Notes

UI Navigation

Finders

HTTP Method & Endpoint

Path Parameters

Query Parameters

Example Request

Example Response (201 Created)

Attributes

Request body — `header` object

Response body — `header` object

Response body — `lines[]` items

Error Codes

Contact Us

Create Purchase Change Order

PO Change Order — Create from Purchase Order

Overview

Notes

UI Navigation

Finders

HTTP Method & Endpoint

Path Parameters

Query Parameters

Example Request

Example Response (201 Created)

Attributes

Request body — header object

Response body — header object

Response body — lines[] items

Error Codes

Request body — `header` object

Response body — `header` object

Response body — `lines[]` items