Skip to main content

 

 

Coupa Success Portal

Purchase Order Change API

Overview

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

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 update Update purchase order change

Elements

Element Description Req'd Unique Allowable Value In Out Data Type
acknowledged-at acknowledged_at         yes date
approvals <approval> 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 
exported Indicates if transaction has been exported         yes boolean
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 
status PO Status         yes string(255)
supplier Supplier         yes Supplier 
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

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>
  • Was this article helpful?