Requisitions API (/requisitions)
Use the requisitions API to create, update, and query requisitions.
The URL to access requisitions is: https://{your_instance_name}/api/requisitions
See Integration Best Practices for more info.
Requisitions API Objects
This is the full list of expense objects available via the UI. However, not all objects listed here have endpoints–some are only referenced by objects, and can't be updated directly.
Note
- If submitting this API using a static Chart of Accounts, any segment values included must be from an existing account.
- If submitting this API using a dynamic Chart of Accounts, any segment values included must match existing account segments or lookup values. If an account doesn't exist for a given segment value, the API automatically creates it.
Actions
Requisitions API allows you to:
| Verb | Path | Action | Description |
|---|---|---|---|
| PUT | /api/requisitions/:id/add_approver |
add_approver | Manually add an approver for a requisition |
| POST |
|
add_to_cart | Add To Cart |
| POST | /api/requisitions |
create | Create a requisition in draft status, which will then need to be submitted manually |
| GET | /api/requisitions/current_cart |
current_cart | Send current cart for user, if there is no current cart then create and send |
| GET | /api/requisitions |
index | Query requisitions |
| GET | /api/requisitions/mine |
mine | /api/requisitions/mine |
| PUT | /api/requisitions/:id/remove_approval |
remove_approval | Remove an approver who was manually added |
| PUT | /api/requisitions/:id/save_for_later |
save_for_later | Save For Later for API requisitions |
| GET | /api/requisitions/:id |
show | Show requisition |
| POST | /api/requisitions/submit_for_approval |
submit_for_approval | Create a requisition and attempt to submit it for approval / buyer action |
| PUT | /api/requisitions/:id |
update | Update requisition |
| PUT | /api/requisitions/:id/update_and_submit_for_approval |
update_and_submit_for_approval | Update requisition and submit for approval |
Elements
| Element | Description | Req'd | Unique | Allowable Value | In | Out | Data Type |
|---|---|---|---|---|---|---|---|
| approvals | approvals | yes | Approval | ||||
| approver | approver | yes | User | ||||
| attachments | attachments | yes | Attachment | ||||
| buyer-note | Any comments or notes from the Buyer | yes | yes | text | |||
| created-at | Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ | yes | datetime | ||||
| created-by | User who created | yes | yes | yes | User | ||
| currency | Currency Code | yes | USD | ||||
| current-approval | Current/Pending Approval | yes | Approval | ||||
| department | Requisition Department | yes | yes | Department | |||
| exported | Indicates if transaction has been exported | yes | boolean | ||||
| external-po-reference | External PO reference that allows customers to supply PO numbers that would override auto generated PO numbers | no | yes | any | yes | string(255) | |
| hide-price | Hide Price from supplier. True or False | no | no | yes | RequisitionHeader | ||
| id | Coupa unique identifier | yes | integer | ||||
| justification | Requisition Justification Comments | yes | yes | text | |||
| line-count | Requisition Header Line Count | no | no | any | yes | integer | |
| milestones | Milestones | yes | yes | Procurement::Milestone | |||
| mobile-currency | Default currency used | yes | USD | ||||
| mobile-total | total | yes | decimal | ||||
| need-by-date | Item Need By Date | yes | yes | datetime | |||
| pcard | Name of PCard | yes | yes | Pcard | |||
| price-hidden | Hide price from supplier. True or False | yes | boolean | ||||
| receiving-warehouse-id | Receiving Warehouse ID | no | no | any | yes | yes | integer |
| recurring-rules | Recurring Rules | yes | |||||
| reject-reason-comment | last reject reason comment | yes | string | ||||
| req_title | Optional title of the Requisition | yes | yes | string(50) | |||
| requested-by | requested_by | yes | yes | User | |||
| requester | requested_by | yes | yes | User | |||
| requisition-lines | requisition_lines | yes | yes | yes | RequisitionLine | ||
| ship-to-address | Name of Address | yes | yes | yes | Address | ||
| ship-to-attention | Ship to Address Attention | yes | yes | string(255) | |||
| status | Transaction status. To learn more about Requisition statuses, see Requisition Status Definitions. | yes |
draft, cart, pending_buyer_action, pending_approval,
approved ordered partially_received, received,
abandoned, backgrounded, withdrawn
|
yes | string(50) | ||
| submitted-at | submitted_at | yes | datetime | ||||
| tags | yes | yes | [] | ||||
| taggings | yes | yes | [] | ||||
| total | Total in own currency | yes | decimal | ||||
| updated-at | Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ | yes | datetime | ||||
| updated-by | User who updated | yes | User | ||||
| user_members | User members | yes | User | ||||
| user_group_members | User group members | yes | User |
Note
The created_by element defaults from the API User key, but it can be overridden by the Requisition API. Contact Coupa Support to allow the Requisition API to override the API User key value.
Note
- In a requisition-line, you can use either a description (free-form) or an item (catalog item). If an item id is used, the item must exist. The <source-type></source-type> is not used and ignored.
- Currencies, users in the requested-by and suppliers must be in the system with a status of active.
- Item: If a preferred supplier and price is available for an item it will be used unless the unit-price is specified. If a unit-price is specified, it will override the default pricing available for the item. While it is not an error to specify a description and an item, using an item will set the description to the item description, ignoring the passed in the description field.
- Defaulting: Unless otherwise specified in the XML, the system will respect the relevant defaulting within the system. Such as defaulting payment and shipping terms from the supplier record.
- Line Numbering: The API expects the line-num to increment by one for each new line number. If you use the same line-num, the system will ignore all other lines with the same number.
- As part of the Version 30.2.2 release update, we've resolved an issue that prevented you from creating a requisition for users outside of the requester's Content Group. Now, the requisition API reflects the functionality of the UI.
- As part of the Version 34.4.0 release update, requisition API can be used to create a new requisition by inserting a line from another requisition - only if the status of source requisition is Draft. If the status of the requisition is not Draft, then no line from the requisition can be referenced to create another new requisition.
When the “created by” user is being set via API, that user’s content group access is validated for the creation of the requisition. See the table below for reference:
| allow_created_by_override_via_api | Creator has access via Content Group | Requester has access via Content Group | Allow creation via API |
|---|---|---|---|
| TRUE | Y | N/A | Y |
| TRUE | N | N/A | N |
| FALSE | N/A | N/A | Y |
Default supplier item behavior
When a req with quantity based lines is created via API,the supplier item defaults on the req line using the following rules:
| API payload | Expected result |
|---|---|
| Item ID | Preferred or lowest priced supplier item |
| Item ID, supplier | Preferred or lowest priced supplier item matching the provided supplier id |
| Item ID, supplier, source part number | Preferred or lowest priced supplier item matching the provided supplier id and source part number |
| Item ID, supplier, source part number, supplier aux part number | Preferred or lowest priced supplier item matching the provided supplier id and source part num and supplier aux part number |
| Item ID, supplier, contract | Preferred or lowest priced supplier item matching the provided supplier id and contract id |
| Item ID, supplier, contract, price | Preferred or lowest priced supplier item matching the provided supplier id and contract id (price is not used in match) |
| Item ID, supplier, contract, source part number | Preferred or lowest priced supplier item matching the provided supplier id and contract id and source part number |
| Item ID, supplier, contract, source part number, supplier aux part number | Preferred or lowest priced supplier item matching the provided supplier id and contract id and source part num and supplier aux part number |
Note
- If the supplier item is associated to a catalog, the catalog must be in "accepted" status and the current date is within the catalog start and end dates.
- If the supplier item is associated to a contract, the contract must be in "published" status and the current date is within the catalog start and end dates.