Purchase Order Change API

Use the purchase order change API to modify orders that are are already in flight, either in approvals or sent to the supplier.

Overview

Use this API to modify orders that are already in flight, either in approvals or sent to the supplier.

Note

Purchase Order Changes GET API is not intended to retrieve PO revisions to out to ERP.

For PO Revisions, always use PO GET API with exported = false, and use the 'version' value to identify whether the PO is a new one or a revised PO.

Actions

Purchase order changes API allows you to:

Verb Path Action Description
PUT /api/purchase_order_changes/:id/add_approver add_approver Manually add an approver for an order header change
POST /api/purchase_order_changes create Create purchase order change
GET /api/purchase_order_changes index Query purchase order changes
PUT /api/purchase_order_changes/:id/remove_approval remove_approval Remove an approver who was manually added
GET /api/purchase_order_changes/:id show Show purchase order change
PUT /api/purchase_order_changes/:id/submit_for_approval submit_for_approval Submit purchase order change for approval
PUT /api/purchase_order_changes/:id update Update purchase order change

Elements

Element Description Req'd Unique Allowable Value In Out Data Type
acknowledged-at acknowledged_at yes date
approvals <approver> attribute with <login> value must be included for PUT/PATCH to an existing PO change request. Yes* Current approver <login> must exist in Coupa yes yes Approval
attachments Attachments yes Attachment
created-at Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ yes datetime
created-by User who created yes User
current-approval Current/Pending Approval yes Approval
department department yes Department
easy_form_response_id Easy Form Response Id yes
exported Indicates if transaction has been exported yes boolean
hide-price Hide Price from supplier. True or False No No yes Order Header Change
id Coupa's unique identifier for the PO change request. Req'd for PUT update to existing change request Yes* Valid PO change request ID yes yes integer
justification justification yes
order-header-id ID of the order that is being changed. Req'd for new POST change request Yes* Valid PO header ID yes yes integer
order-line-changes Order line changes yes yes
payment-method payment_method yes string(255)
payment-term payment terms yes yes Payment Term
pcard pcard yes yes Pcard
po-number PO Number yes string(20)
price-hidden Hide Price from supplier. True or False yes boolean
reject-reason Reject reason yes Comment
requester Requesting Account's login yes User
requisition-header-id requisition_header_id yes integer
ship-to-address Ship to address yes Address
ship-to-user Ship to user yes yes User
shipping-term shipping terms yes yes Shipping Term
source-part-num source_part_num yes yes string(255)
status PO Status yes string(255)
supplier Supplier yes Supplier
transmission-emails Transmission Email comma separated list No No any yes yes text
transmission-method-override Transmission Method Override No No supplier_default, email, do_not_transmit yes yes string(30)
updated-at Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ yes datetime
version PO Supplier Version Number - Increase each time a PO is changed and triggers a resend to the supplier. yes integer
manufacturer_name Manufacturer Name yes yes string(255)
manufacturer_part_number Manufacturer Part Number yes yes string(255)
extra_line_attribute yes yes
service_type yes
currency yes yes
milestones yes yes
recurring-rules Recurring rules yes -
total PO Change document total yes decimal(32,4)
pending-cancel Is the PO pending cancellation? True or False yes boolean
lines-count Number of lines in the PO Change document yes integer
lines-pending-add-count Number of lines pending addition in PO Change document yes integer
lines-pending-delete-count Number of lines pending deletion in PO Change document yes integer

Example Calls

Create a PO change request

Create a PO change request using the API by sending an authenticated API call:
POST https://{your_instance}.coupahost.com/api/purchase_order_changes

Payload

To POST, you need to include the ID of the original header, and any elements you want to modify. Use the same format as the original PO for the attribute changes.

<?xml version="1.0" encoding="UTF-8"?>
<order-header-change>
	<order-header-id>1000</order-header-id>
	<!-- Requested changes to the PO -->
</order-header-change>

201 Success response

Coupa returns a new <order-header-change> with an ID for the change and the full PO, including any of the changes you specified in your POST payload.

<?xml version="1.0" encoding="UTF-8"?>
<order-header-change>
	<id type="integer">501</id>
	<created-at type="dateTime">2018-04-06T23:14:50+05:30</created-at>
	<updated-at type="dateTime">2018-04-06T23:14:51+05:30</updated-at>
	<order-header-id type="integer">123750</order-header-id>
	<!-- Original PO with requested changes -->
</order-header-change>

The <status> of the PO will be approved if the change didn't require new approvals, or pending_approval if the change does require new approvals.

Update a PO change request

You can modify a PO change request that's pending approval by sending an authenticated API call:
POST https://{your_instance}.coupahost.com/api/purchase_order_changes/{id} where {id} is the <id type="integer"> attribute in the 201 response. You can't modify a PO change request that's already approved.

Payload

The payload format is essentially the same as the POST, except that you need to include the current approver for the PO change.

<?xml version="1.0" encoding="UTF-8"?>
<order-header-change>
	<approver>
		<login>Approver Name</login>
	</approver>
	<!-- Requested changes to the PO -->
</order-header-change>

200 Response

The response is the same as a POST: the <order-header-change> with the ID and the full PO, including any of the changes you specified in your PUT payload.

<?xml version="1.0" encoding="UTF-8"?>
<order-header-change>
	<id type="integer">501</id>
	<created-at type="dateTime">2018-04-06T23:14:50+05:30</created-at>
	<updated-at type="dateTime">2018-04-06T23:14:51+05:30</updated-at>
	<order-header-id type="integer">123750</order-header-id>
	<!-- Original PO with requested changes -->
</order-header-change>

400 Bad request response

If you send a bad request, Coupa will provide a list of errors.

<?xml version="1.0" encoding="UTF-8"?>
<errors>
	<error>
		<!-- List of errors -->
	</error>
</errors>

Related Items


Sourcing API (/quote_requests)

03 September 2021

Use the Coupa Sourcing API to create new RFx events, see supplier responses, and award suppliers at the line level.

Projects API (/projects)

22 December 2021

Use the Projects API to create or update a Project within Coupa.

Task API (/tasks)

22 December 2021

The users API allows you to create, update, or query users.

Receiving Transactions API (/receiving_transactions)

05 April 2022

The inventory transactions API helps to create, update, or query the details of inventory receipts.