Purchase Orders API (/purchase_orders)

Use the purchase order API to create, update, or query purchase orders.


When working with the Purchase Orders API, you've got a few resource endpoints you can work from:

Resource Path Description
PO headers /api/purchase_orders Full purchase orders that contain PO lines, payment terms, addresses and more. 
PO lines /api/purchase_order_lines Detailed information about PO lines like item info and accounting details. See Purchase Order Lines API and Order Line Allocations API for details.
PO changes /api/purchase_order_changes Create and manage PO change requests regardless if they drive approvals or not.
Reason insights /api/reason_insights/ Provide reasons when reopening an order.


Purchase Orders API allows you to:

Verb Path Action Description
PUT /api/purchase_orders/:id/cancel cancel Cancel
PUT /api/purchase_orders/:id/close close Close a purchase order. See Closing Purchase Orders for more info.
POST /api/purchase_orders create Create a purchase order as part of the external purchase orders feature. Do not use for Coupa-based POs.
PUT /api/purchase_orders/:id/ignore_window_and_issue ignore_window_and_issue Ignore Windows And Issue
GET /api/purchase_orders index Query purchase orders
PUT /api/purchase_orders/:id/issue issue Issue and send the PO to the supplier.
PUT /api/purchase_orders/:id/issue_without_send issue_without_send Issue without sending the PO to the supplier.
PUT /api/purchase_orders/:id/release_from_buyer_hold release_from_buyer_hold Release purchase order on buyer hold
PUT /api/purchase_orders/:id/reopen reopen Reopen a soft-closed purchase order. See Closing Purchase Orders for more info on soft close.
GET /api/purchase_orders/:id show Show purchase order
PATCH /api/purchase_orders/:id update Update purchase order
PUT /api/purchase_orders/:id update Update purchase order


Element Description Req'd Unique Allowable Value In Out Data Type
acknowledged-at acknowledged_at         yes datetime
acknowledged-flag Has PO been acknowledged by Supplier?       yes yes boolean
attachments attachments       yes yes Attachment 
change-type Last type of change on PO, it represents whether PO was changed through change request or through revise change, revision, confirmation   yes string(255)
coupa-accelerate-status Status indicating whether the invoice has discount payment terms via Static Discounting accelerated   yes string(255)
created-at Date record was created in Coupa.         yes datetime
created-by Coupa ID of User who created Invoice         yes User
currency Currency of transaction       yes yes Currency 
current-integration-history-records Current integration history records         yes Integration History Record 
exported Indicates if transaction has been exported         yes boolean
hide-price Hide Price from supplier. True or False no no   yes   boolean
id Coupa's internal ID         yes integer
internal-revision Internal Revision Number - Increases each time a change is made to a PO whether that change is internal or causes the PO to be resent to the supplier.   yes integer
invoice-stop Invoice Stop flag         yes boolean
last-exported-at Date and time transaction was last exported in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ   yes datetime
milestones Milestones       yes yes Procurement::Milestone 
order-lines order_lines yes     yes yes Order Line 
payment-method payment_method       yes yes string(255)
payment-term Payment Terms       yes yes Payment Term 
pcard pcard       yes yes Pcard 
po-number PO Number yes yes   yes yes string(20)
price-hidden Hide Price from supplier. True or False         yes boolean
reason-insight-events Reason insight events for changes, reopens, etc.     yes Reason Insight Event
requester Requesting Account's login       yes   User
requisition-header Requisition Header         yes Requisition Header 
ship-to-address ship_to_address no no any yes yes Address 
ship-to-attention The user for whom the order will be addressed. Ship to the attention.  no no any yes yes string(255)
ship-to-user ship_to_user yes     yes yes User
shipping-term Payment Terms       yes yes ShippingTerm 
status PO Status     buyer_hold, cancelled, closed, currency_hold, draft, error, expensed, issued, supplier_hold, supplier_window_hold, exported   yes string(50)
supplier Supplier Coupa internal ID number yes     yes yes Supplier 
supplier-site Supplier Site no no any yes yes Supplier Site 
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)
transmission-status Transmission Status no no created, deferred, deferred_processing, pending_manual, pending_manual_cancel, awaiting_online_purchase, scheduled_for_email, sent_via_email, scheduled_for_cxml, scheduled_for_xml, sent_via_cxml, sent_via_xml, sent_manually, purchased_online, transmission_failure   yes string
type Type of Order     ExternalOrderHeader yes   string(255)
updated-at Last Updated at Date         yes datetime
updated-by Coupa ID of User who created Invoice         yes User 
version PO Supplier Version Number - Increase each time a PO is changed and triggers a resend to the supplier. yes yes integer
classification Classification     msp, supplier, vms yes yes string(255)
currency Currency of transaction         yes  
confirm-by-hrs Confirm by         yes integer
order-confirmation-level Confirmation Level         yes int(11)
user-members User members         yes User
user-group-members User group members         yes User


  • There are dependent fields that become queryable based the value from the source field.  For example, if you query against po-method=email, then po-email can be added as an additional query criteria. Please see fields with Yes*.
  • For large data set and for performance optimization, you should always limit your result with some GET criteria.
  • PO changes do not always increment the version number. See Fields that Cause a Purchase Order Revision for more info. The updated-at field can always be used to determine whether any changes have been made.

Code examples

Delete an order line using PUT

<?xml version="1.0" encoding="UTF-8"?>

Reopen a soft-closed PO

See Closing Purchase Orders for more info on soft close.

Using a reason insight ID

<?xml version="1.0" encoding="UTF-8"?>
	<reason-insight-event-comment>comment body</reason-insight-event-comment>

Using a reason insight code

<?xml version="1.0" encoding="UTF-8"?>
	<reason-insight-event-comment>comment body</reason-insight-event-comment>

Related Items

Differences between XML and JSON in Coupa

16 December 2016

Tagging API

24 April 2017

Use the Tagging API to bring in and export tags to your third-party system.

Integration Runs API

24 April 2017

Use this API to create, query, or update an integration run, as well as update the status.

Dispute Reason API

05 August 2017