What can we help you find? Products Coupa Product Documentation Integration Technical Documentation The Coupa Core API Resources Transactional Resources Invoices API (/invoices)

Invoices API (/invoices)

Use the invoice API to create, update, or query invoices associated with a purchase order.

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.

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
GET	`/api/invoices/:id/retrieve_image_scan`	Retrieve image scan	Retrieve/Download image scan
PUT	`/api/invoices/:id/image_scan`	Image scan	Update image scan attachment or image scan URL
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_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(255)
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(25)
image-scan-content-type	Content type of image scan					yes	string(191)
image-scan-file-name	File name of the image scan					yes	string(255)
image-scan-file-size	Size of image scan file in MB					yes	string(12)
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
pay-invoice	Pay invoice					yes
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
resolution-number	Resolution Number				yes	yes	string(255)
reverse-charge-reference	Reverse Charge Reference				yes	yes
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. For more information about invoice statuses, see Invoice Progression through Statuses.			new, ap_hold, draft, on_hold, pending_receipt, rejected, abandoned. disputed. pending_approval, booking_hold, pending_action, approved, voided, processing, invalid, pending_action, payable_adjustment		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

Note

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

Related Items

Supplier Risk Aware Feed API (/supplier_risk_aware_feed)

01 May 2020

Use the Supplier Risk Aware Feed API to load your governance, risk, and compliance (GRC) data into Risk Aware.

Learn More

Invoices Import

27 April 2023

The invoice loader has header columns, charge columns, line columns, line allocation columns and tax columns.

Learn More

Custom Field Namespace

18 April 2019

All new custom-fields are added to a custom-field namespace to avoid name conflicts and to make customer-added fields more easily identifiable.

Learn More

Sourcing API (/quote_requests)

03 September 2021

Use the Coupa Sourcing API to create new RFx events, see supplier responses, and award suppliers at the line level.

Learn More