Skip to main content

 

 

Coupa Success Portal

Invoices API (/invoices)

Overview

The URL to access invoices is: https://{your_instance_name}/api/invoices

As of Release 29, Coupa has enhanced the invoicing API to be fully functional, on parity with other invoice buyer channels. For more information about this update, see Extended Invoicing API Coverage for Invoice Creation.

See Integration Best Practices for more info.

Invoice API Objects

This is the full list of invoice 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.

Actions

The Invoices API allows you to:

Verb Path Action Description
PUT /api/invoices/:id/abandon abandon Abandon invoice
PUT /api/invoices/:id/add_approver Add approver Manually add an approver for an invoice
PUT /api/invoices/:id/bypass_approvals Bypass approvals

Bypass approvals

Allows a 3rd-party system on the customers side to get an invoice approved and paid as quickly as possible.

PUT /api/invoices/:id/bypass_current_approval Bypass current approval

Bypass current approval

Allows a 3rd-party system on the customers side to get an invoice approved from the current approver to get an invoice paid as quickly as possible.

PUT /api/invoices/:id/dispute Dispute

Dispute invoice

Allows moving an invoice to disputed status via a system call. Moving an invoice to disputed notifies the supplier that there is an issue with an invoice. The dispute request can include a dispute reason in the payload as follows: 

<invoice-header>
  <dispute-reason>
    <code>INCORRECT-QUANTITY</code>
  </dispute-reason>
  <comment>A supplier comment</comment>
</invoice-header>

This requires that INCORRECT_QUANTITY is a valid and active dispute reason.

PUT /api/invoices/:id/flip_to_advance_ship_notice Flip to advance ship notice

Flip invoice to Advance Ship Notice

 

PUT /api/invoices/:id/image_scan Image scan Update image scan attachment
GET /api/invoices Index Query invoices
PUT /api/invoices/:id/remove_approval Remove approval Remove an approver who was manually added
PUT /api/invoices/:id/restart_approvals Restart approvals

Restart approvals

Allows a 3rd-party system on the customers side to clear the current approval chain and regenerate an new approval chain for an invoice that has had modifications.

 

GET /api/invoices/:id/retrieve_clearance_document retrieve_clearance_document Retrieve/Download clearance document
GET /api/invoices/:id/retrieve_image_scan Retrieve image scan Retrieve/Download image scan
GET /api/invoices/:id/retrieve_legal_invoice_pdf retrieve_legal_invoice_pdf Download/retrieve the legal invoice PDF. This action allows the PDF attachment to be exported by API call.
PUT /api/invoices/:id/revalidate_tolerances Revalidate tolerances

Revalidate tolerances

Allows a 3rd-party system on the customers side to resubmit an invoice that had issues.

GET /api/invoices/:id Show Show invoice
PUT /api/invoices/:id/submit Submit Submit draft invoice for approval
PATCH /api/invoices/:id Update

Update invoice

PUT /api/invoices/:id Update

Update invoice

Used to updated information on the Invoice using the API

PUT /api/invoices/:id/update_line_accounts Update line accounts

Update line accounts

Used by mobile users to update Invoices

PUT /api/invoices/:id/void Void

Void an approved invoice

This can be used on Invoices only on approved and pending receipt Invoices.

  • BUYER_VOIDABLE_STATUSES = [:pending_receipt, :approved, :draft]
  • SUPPLIER_VOIDABLE_STATUSES = [:pending_receipt, :approved]
PUT /api/invoices/:id/withdraw_dispute Withdraw dispute

Withdraw dispute

Due to supplier inaction or a mistake on the buyer side a disputed Invoice can be returned to the approval process.

Elements

Element Description Req'd Unique Allowable Value In Out Data Type
abandon-reason Abandon reason no no any   yes Reason Insight 
account-type Chart Of Account Reference yes     yes yes Account Type
advance-payment-received-amount Amount of advance payment received       yes yes decimal(30,4)
amount-due-less-discount Amount due after applying the discount     any   yes decimal
approvals Approvals         yes Approval
attachments           yes Attachment
archive-entity-id Archive Entity Id         yes integer
bill-to-address Bill to Address yes     yes yes Address
buyer-tax-registration Buyer tax registration yes*       yes Tax Registration
canceled Indicates if transaction has been canceled         yes boolean
cash-accounting-scheme-reference Note if using cash accounting scheme       yes yes string(255)
clearance-document Clearance document attachment file name. Accessible via /retrieve_clearance_document   yes string
comments comments       yes yes string(255)
compliant Invoice compliance indicator         yes boolean
confirmation Confirmation         yes string(50)
contract Backing contract number       yes yes Contract
coupa-accelerate-status Status indicating whether the invoice has discount payment terms via Static Discounting accelerated   yes string(40)
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
credit-note-differences-with-original-invoice Credit Note Differences With Original Invoice       yes yes decimal(30,4)
credit-reason The reason of creating the credit       yes yes string(255)
currency Currency code       yes yes Currency
current-integration-history-records Current Integration History Records         yes Integration History Record
customer-accounting-tax-less-discount Customer accounting tax after applying the discount     any   yes decimal
customs-declaration-date Customs Declaration Date       yes yes datetime
customs-declaration-number Customs Declaration Number       yes yes string(60)
customs-office Customs Office       yes yes text
date-received Date Received in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ         yes datetime
delivery-date Date of Supply no no any   yes datetime
destination-country Country of destination used for compliance         yes Country 
discount-amount Discount Amount provided by supplier       yes yes decimal(32,4)
discount-due-date Discount Due Date calculated based on the discount payment terms     yes datetime
discount-percent Discount %       yes yes float
dispute-method Dispute Method no no any   yes string(10)
dispute-reasons Dispute Reasons no no any   yes Dispute Reason
document-type Invoice or Credit Note     Invoice, Credit Note   yes string(255)
early-payment-provisions Early payment incentives       yes yes string(255)
exchange-rate Exchange Rate       yes yes decimal(30,9)
exported Indicates if transaction has been exported         yes boolean
failed-tolerances Failed tolerances       yes yes Invoice::FailedTolerance
folio-number Folio Number         yes string(20)
form-of-payment Payment Form         yes string(10)
gross-total Gross Total         yes decimal
gross-total-less-discount Invoice total after applying the discount     any   yes decimal
handling-amount Handling amount       yes yes decimal(32,4)
id Coupa unique identifier         yes integer
image-scan Invoice Image Scan attachment filename         yes string(255)
image-scan-url Invoice Image Scan URL. Must begin with 'http://' or 'https://'.     yes string(255)
inbound-invoice Inbound invoice reference         yes Inbound Invoice
inbox-name Inbox Name         yes string
internal-note Internal Note       yes yes text
invoice-charges Invoice charges       yes yes Invoice Charge
invoice-date Date of Invoice yes     yes yes datetime
invoice-from-address Invoice from address yes*       yes Supplier Remit To
invoice-lines Record identifier       yes yes Invoice Line
invoice-number Invoice number yes     yes yes string(40)
invoice-payment-receipts Invoice related payment receipts information         yes Invoice Payment Receipt 
invoice-reference-number Invoice Reference Number (IRN)       yes yes  
issuance-place Issuance Place         yes string(50)
last-exported-at Date and time transaction was last exported in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ   yes datetime
late-payment-penalties Late Payment Penalties       yes yes string(255)
legal-destination-country Legal destination country used for compliance     See the Compliant Country List.   yes Country 
line-level-taxation Flag indicating whether taxes are provided at line level in this invoice yes     yes yes boolean
lock-version-key Lock Version         yes integer
margin-scheme Reason for using margin scheme       yes yes string(255)
misc-amount Miscellaneous Amount       yes yes decimal(32,4)
net-due-date Net Due Date calculated based on the net payment terms         yes datetime
net-total-less-discount Net total after applying the discount     any   yes decimal
origin-country Country of origin used for compliance         yes Country
origin-currency-gross Local Currency Gross yes*       yes decimal(32,4)
origin-currency-net Local Currency Net yes*       yes decimal(32,4)
original-invoice-date Original invoice date required when is-credit-note=true yes**       yes datetime
original-invoice-number Original invoice date required when is-credit-note=true yes**       yes string(40)
paid Paid       yes yes boolean
payment-channel How the invoice payment will be handled - ERP (default), Coupa Pay Virtual Card, Coupa Pay Invoice Payment no no any   yes string(40)
payment-date Date of payment for invoice       yes yes datetime
payment-method Payment Method         yes string(10)
payment-notes Notes included with payment for invoice       yes yes text
payment-order-reference Payment Order Reference       yes yes string(255)
payment-term Payment term code on invoice       yes yes Payment Term
payments Payments       yes yes Payment
pre-payment-date Pre-Payment Date       yes yes datetime
reconciliation-lines Reconciliation lines       yes   Invoice/Reconciliation Line
remit-to-address Remit to Address yes     yes yes Remit To Address
requested-by Requester on the invoice         yes User
reverse-charge-reference Reverse Charge Reference       yes yes string(255)
signed-qr-code Signed QR Code         yes text
self-billing-reference Self billing reference on the invoice       yes yes string(191)
sender-email Sender Email         yes string(255)
series Series         yes string(30)
ship-from-address Ship from address yes       yes Supplier Remit To
ship-to-address Ship to Address       yes yes Address
shipping-amount Shipping Amount       yes yes decimal(32,4)
shipping-term Shipping term code on invoice         yes Shipping Term
show-tax-information Show tax information in the invoice         yes boolean
status Invoice Status         yes string(50)
supplier Supplier Name or Number       yes yes Supplier
supplier-created Supplier created indicator for invoice         yes boolean
supplier-note Note provided by supplier       yes yes text
supplier-remit-to Supplier provided remit to address yes     yes yes Supplier Remit To
supplier-tax-registration Supplier tax registration yes*       yes Tax Registration
supplier-total Supplier Total         yes decimal
taggings Taggings       yes yes Tagging
tags Tag (Deprecated, please use Taggings association to add Tags onto InvoiceHeader)   yes yes Tag
tax-amount Tax amount (not used if tax is provided at line level)   yes yes decimal
tax-amount-engine Tax amount calculated by either Coupa Native or External Tax Engine based on configuration     yes decimal
tax-code Tax code (not used if tax is provided at line level)       yes yes string(255)
tax-code-engine Tax code returned by External Tax Engine based on configuration         yes  
tax-due-to-supplier Tax due to the supplier         yes decimal(32,4)
tax-lines Line tax code (not used if tax is provided at header level)       yes yes Tax Line
tax-rate Tax rate (not used if tax is provided at line level)       yes yes float
tax-rate-engine Tax rate returned by External Tax Engine based on configuration         yes  
taxes-in-origin-country-currency Local Currency Tax yes*       yes decimal(32,4)
tolerance-failures Tolerance Failure         yes string(512)
total-with-taxes Total with taxes         yes decimal
total-taxes-less-discount Total taxes after applying the discount     any   yes decimal
type-of-receipt Type of Receipt         yes string(10)
type-of-relationship Type of Relationship         yes string(10)
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
use-of-invoice Use of the Invoice         yes string(10)
withholding-tax-lines Withholding tax lines       yes yes Withholding Tax Line
withholding-tax-override Withholding Tax Override         yes decimal(30,3)
invoice-reference-number Invoice Reference Number (IRN)       yes yes string(255)
supplier-invoice-issuer-name Supplier Invoice Issuer Name       yes yes string(255)
supplier-invoice-reviewer-name Supplier Invoice Reviewer Name       yes yes string(255)
supplier-payment-collector-name Supplier Payment Collector Name       yes yes string(255)
endorsement-on-invoices Endorsement On Invoices         yes string(10)
new-means-of-transport New Means Of Transport         yes string(10)
place-of-issuance Place Of Issuance         yes string(100)
amount-of-advance-payment Amount Of Advance Payment       yes yes decimal(46,20)
transaction-uuid Transaction UUID         yes string(50)
transaction-notification-date Transaction Notification Date         yes datetime
content-validation Invoice Content Validation Indicator         yes boolean
invoice-reference-number Invoice Reference Number (IRN)       yes yes  
supplier-invoice-issuer-name Supplier Invoice Issuer Name       yes yes string(255)
supplier-invoice-reviewer-name Supplier Invoice Reviewer Name       yes yes string(255)
supplier-payment-collector-name Supplier Payment Collector Name       yes yes string(255)
is-credit-note Document Type Credit Note       yes   boolean
requester-email Requester Email       yes   string
requester-name Requester Fullname       yes   string
requester-lookup-name Requester Lookup Name       yes   string
delivery-number Delivery Number       yes   string(255)
delivery-date Date of Supply       yes   datetime
original-value-of-supply Original Value of Supply       yes   decimal(46,20)
correct-value-of-supply Correct Value of Supply       yes   decimal(46,20)
original-invoice-date Original invoice date used in case of a Credit Note yes     yes   datetime
type-of-relationship Type of Relationship       yes   string(10)
original-invoice-number Original invoice number used in case of a Credit Note yes     yes   string(40)
place-of-supply Place Of Supply       yes   string(255)
split-payment-mechanism Split Payment Mechanism       yes   boolean
endorsement-on-invoices Endorsement On Invoices       yes   string(10)
new-means-of-transport New Means Of Transport       yes   string(10)
place-of-issuance Place Of Issuance       yes   string(100)
signed-qr-code Signed QR Code       yes   text
shipping-term Shipping term code on invoice       yes    
supplier-tax-registration   yes     yes    
buyer-tax-registration   yes     yes    
payment-order-number Payment Order Number      

yes

  string
invoice-issuance-time Invoice Issuance Time       yes   string(255)
cash-register-operator Cash Register Operator       yes   string(255)
means-of-payment Means Of Payment       yes   string(255)
unique-identification-code-of-cash-receipt Unique Identification Code Of Cash Receipt       yes   string(255)
security-code-of-issuer Security Code Of Issuer       yes   string(255)
state-tax-number State Tax ID Number       yes   string(255)
state-tax-number-for-substitute-taxpayer State Tax ID Number for Substitute Taxpayer       yes   string(255)
municipal-tax-number Municipality Tax ID Number       yes   string(255)
serial-code-of-fiscal-invoice Serial Code of Fiscal Invoice       yes   string(255)
verification-code Verification Code       yes   string(255)
type-of-document Type of Document       yes   string(255)
protocol-number Protocol Number       yes   string(255)
nature-of-operation Nature of Operation       yes   string(255)
type-of-operation Type of Operation       yes   string(255)
freight-type Freight Type       yes   string(255)
vehicle-license-plate Vehicle License Plate       yes   string(255)
national-enrollment-of-conveyor National Enrollment of Conveyor       yes   string(255)
volume-amount Volume Amount       yes   string(255)
volume-gross-weight Volume Gross Weight       yes   string(255)
volume-liquid-weight Volume Liquid Weight       yes   string(255)
volume-brand Volume Brand       yes   string(255)
volume-type Volume Type       yes   string(255)
volume-numbering Volume Numbering       yes   string(255)
payment-agreement-notes Payment Agreement Notes     Fully paid via Prepayment Agreement, Partially paid via Prepayment Agreement, Already paid for a Recurring Agreement, Retain payment per agreement yes   string(255)
tcs-tax-lines         yes   -
invoice-from-address   yes     yes   Address
ship-from-address   yes     yes   Address

Required fields marked with an asterisk * are additional required fields for compliant invoices.  Required fields marked with two asterisks ** are only required when is-credit-note=true .

Compliant Country List

This list shows which countries are permitted for compliant invoicing. It is not a list of compliant countries Coupa currently supports.

#id Code Name
14 AU Australia
15 AT Austria
22 BE Belgium
31 BR Brazil
34 BG Bulgaria
39 CA Canada
53 HR Croatia
55 CY Cyprus
56 CZ Czech Republic
58 DK Denmark
67 EE Estonia
72 FI Finland
73 FR France
79 DE Germany
82 GB United Kingdom
83 GR Greece
96 HK Hong Kong
97 HU Hungary
98 IS Iceland
103 IE Ireland
104 IL Israel
105 IT Italy
108 JP Japan
118 LV Latvia
123 LI Liechtenstein
124 LT Lithuania
125 LU Luxembourg
133 MT Malta
138 MX Mexico
141 MC Monaco
144 MA Morocco
151 NL Netherlands
154 NZ New Zealand
161 NO Norway
171 PL Poland
173 PT Portugal
175 QA Qatar
177 RO Romania
183 SA Saudi Arabia
187 SG Singapore
188 SK Slovakia
189 SI Slovenia
192 ZA South Africa
193 ES Spain
204 SE Sweden
205 CH Switzerland
222 AE

United Arab Emirates

223 US United States
250 IM Isle Of Man
  • Was this article helpful?