Purchase Orders API (/purchase_orders)

Overview

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.

Actions

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

Elements

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
Note:
  • 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"?>
<order-header>
	<order-lines>
		<order-line>
			<id>coupa_line_id</id>
			<_delete>true</_delete>
		</order-line>
	</order-lines>
</order-header> 

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"?>
<order-header>
	<reason-insight-id>1</reason-insight-id>
	<reason-insight-event-comment>comment body</reason-insight-event-comment>
</order-header>

Using a reason insight code

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