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>