EN globe icon
user icon
On This Page
  • Last edited on: 13 May 2022
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.

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.

    wiki.tree();

    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