Coupa API Integration Research

Date: 2026-02-24 Status: Research complete

1. Summary — Capability Matrix

Key finding: Coupa has a fully bidirectional API — both read and write are well-supported across all major business objects via REST. GraphQL is read-only (no mutations).

2. API Landscape

2.1 Coupa Core REST API

• Base URL: https://{instance}.coupahost.com/api/{resource}
• Format: XML (default) or JSON — set both Content-Type and Accept headers to match
• Auth: OAuth 2.0 via OpenID Connect (OIDC), or legacy API key via X-COUPA-API-KEY header
• Pagination: Max 50 records per GET; use offset parameter for paging
• Rate limits: Not publicly documented; contact Coupa for specifics
• Versioning: No explicit API versioning — single evolving API surface

2.2 Resource Categories

Reference Data (~30+ endpoints):

• Accounts, Account Types, Addresses, Business Entities, Departments, Projects
• Items, Suppliers, Supplier Sites, Supplier Items, Currencies, Exchange Rates
• Payment Terms, Shipping Terms, Tax Registrations, Lookup Values
• Users, User Groups

Transactional (~40+ endpoints):

• Purchase Orders (+ lines, changes, revisions), Requisitions
• Invoices (+ lines, payments, inbound invoice API)
• Receipts, ASN, Return Requests
• Contracts (+ clauses, terms, types, classifications)
• Expenses (+ lines, preapprovals)
• Approvals, Delegates
• CoupaPay Payments & Statements, Charges
• Inventory (adjustments, transfers, consumptions, cycle counts)
• Sourcing (quote requests/responses)

Shared: Attachments, Comments, Forms, Tags, UoM

2.3 GraphQL API

• Endpoint: Same instance, GraphQL path
• Auth: OIDC + OAuth 2.0 scopes (client credentials only)
• Capabilities: Read-only queries. No mutations — cannot create/update via GraphQL
• Value: Useful for fetching complex nested data in fewer calls; not for writes

2.4 Key API Links

3. Write Capability Verification

Verdict: Full write access confirmed via REST API.

Evidence:

• Coupa documentation explicitly states: "UTF-8 XML based interface that allows you to create, update, and take action on individual records"
• Invoices API: POST /api/invoices creates invoices, PUT /api/invoices/{id} updates them
• Suppliers API: POST /api/suppliers creates, PUT updates, GET queries
• Purchase Orders API: full CRUD including line-level operations
• Dedicated Inbound Invoice API endpoint exists for external invoice submission
• Workato connector confirms: Create Object, Update Object, Search Object, Get by ID all work for invoices, POs, contracts, suppliers, requisitions, expenses
• Official Postman collection includes example calls for common write operations

Important nuance: GraphQL is read-only (no mutations, only client_credentials + read scopes). All writes must go through the REST API.

4. iPaaS & Middleware Findings

Celigo

• Native Coupa connector with Export (read) and Import (write) operations
• Supports all major Coupa objects
• If an endpoint isn't in the connector, can switch to HTTP mode and hit any Coupa REST endpoint directly
• Recently updated URL subdomain settings
• Docs: https://docs.celigo.com/hc/en-us/articles/20841501388571-Available-Coupa-APIs

Workato

• Rich native connector with documented actions:
  • Create Object (invoices, POs, contracts, suppliers, etc.)
  • Update Object (by Coupa internal ID)
  • Search Object (predefined filters + free-form queries)
  • Get Object by ID
  • Close/Cancel Purchase Orders
  • Get Supplier Sites
  • Add File Attachment
  • Set Integration Run Status
• Triggers: Object-based polling triggers
• Docs: https://docs.workato.com/connectors/coupa.html

Make.com

• Limited connector — focused on requisition workflows only:
  • Approve/reject requisitions
  • Update requisition lines
  • Add approvers
  • Custom API call (escape hatch to any endpoint)
• Requires Enterprise plan
• Docs: https://www.make.com/en/help/app/coupa

Zapier

• No native Coupa app found in search results
• Would require webhook/custom integration approach
• Not a viable path for Coupa specifically

Other Platforms

5. Alternative Channels

SFTP / Flat File (CSV)

Coupa has extensive CSV import/export via dedicated SFTP:

• Each Coupa instance gets a dedicated SFTP account
• 81 import types including: invoices, suppliers, supplier sites, contracts, POs, items, users, accounts, exchange rates, payments, receipts, requisitions, ASN, expense data, inventory, tax codes, and many more
• 61 export types including: invoices, POs, contracts, expense reports, payments, suppliers, receipts, sourcing, and more
• File format: RFC 4180 CSV, double-quote escaping
• Inbound folder structure: ./Incoming/{ObjectType}/ (e.g., ./Incoming/Invoices/)
• Outbound: files placed in respective outbound folders
• Processing: inbound files picked up within minutes, archived to /Archive/Incoming
• Monitoring: Setup > File Status page in Coupa UI
• Standard SFTP exports (PO, Invoice, Receipt, Expense) are included; additional exports may be an add-on

Webhooks / Event Notifications

• Coupa supports outbound webhooks (callouts)
• Configured via Coupa admin UI: name, auth, target URL
• Can trigger on business events (invoice created, PO approved, etc.)
• Cloud Elements supports polling-based events for Coupa resources
• Process Automator can trigger workflows including exports on events

Coupa Marketplace / Partner Connectors

• Coupa has an App Marketplace with certified partner connectors
• Listed integration types include certified connectors for various ERP and business systems
• URL: https://marketplace.coupa.com

File Import (UI-based)

• CSV files can be uploaded manually through the Coupa UI
• Not programmatic, but useful for initial data loads or one-off imports

6. Orcha-Specific Deep Dive

6.1 Writing Cost Centers & Accounts

Verdict: YES — full create/update via REST API.

Coupa models cost centers not as standalone objects but as lookup values within a dynamic Chart of Accounts. The data model works like this:

Account Type (CoA template) — must pre-exist, CANNOT be created via API
  └── Lookup Values — cost centers, departments, GL codes, etc.
       └── Accounts — combinations of up to 20 segments from lookup values

Lookup Values API (/api/lookup_values):

Key fields: name (required, unique), external-ref-num (the actual code, required, unique), active (boolean), lookup (parent lookup reference), parent / parent-id (for hierarchy), description, depth.

Accounts API (/api/accounts):

Key fields: segment-1 through segment-20 (the dimension values), account-type (required reference to existing CoA), name, code (auto-generated from segments), active.

Example — create a cost center:

POST /api/lookup_values
<lookup-value>
  <name>Marketing Berlin (MKT-BER)</name>
  <external-ref-num>MKT-BER</external-ref-num>
  <active>true</active>
  <lookup>
    <name>COMPANY_CostCenter</name>
  </lookup>
</lookup-value>

Example — create an account using that cost center as a segment:

POST /api/accounts
<account>
  <active>true</active>
  <name>Marketing Berlin - Travel</name>
  <segment-1>MKT-BER</segment-1>
  <segment-2>Travel</segment-2>
  <segment-3>Expense</segment-3>
  <account-type>
    <name>Corporate CoA</name>
  </account-type>
</account>

Constraint: Account Types (the CoA structure itself) cannot be created via API — they must already exist in the Coupa instance. This is a setup-time dependency, not a runtime issue.

6.2 Triggering & Managing Approval Workflows

Verdict: YES — approve, reject, and hold via REST API. Cannot create new approval chains programmatically.

Approvals API (/api/approvals):

Approvable document types: Requisitions, Purchase Orders, Invoices, Expense Reports, Contracts.

Invoice-specific approval actions (on the invoice object itself):

• add_approver — manually assign an approver
• bypass_approvals — skip entire approval chain
• bypass_current_approval — skip current step only
• remove_approval — remove a manually added approver
• restart_approvals — regenerate the approval chain

Example — reject an invoice approval with reason:

PUT /api/approvals/12612/reject?reason=Missing%20cost%20center%20allocation
→ HTTP 200 on success
→ HTTP 400 if approval is not in Pending state

Process Automator (webhook-style, configured in Coupa admin):

• Triggers on document status changes (e.g., "invoice approved")
• Can send outbound API callouts to Orcha's webhook endpoint
• Supports data mapping transformations in the payload
• Handles retry on failure
• Could notify Orcha when an invoice moves through approval stages

What this means for Orcha: We can both push approvals (approve/reject via API) and receive approval events (via Process Automator callouts or polling).

6.3 Reading Back Status & Lifecycle Data

Verdict: YES — rich status tracking via polling or event-driven.

Invoice statuses available via API: new → draft → pending_approval → approved → processing → (paid)

Full status enum: new, draft, pending_approval, approved, ap_hold, on_hold, pending_receipt, rejected, abandoned, disputed, booking_hold, pending_action, voided, processing, invalid, payable_adjustment

Key fields for lifecycle tracking:

Polling pattern for status updates:

GET /api/invoices?status=approved&status=pending_approval&status=on_hold&updated-at[gt]=2026-02-24T00:00:00Z

Payment status via CoupaPay:

GET /api/coupa_pay/payments?status[in]=completed_successfully,completed_with_errors&updated-at[gt]=2026-02-24

Event-driven alternative:

• Configure Process Automator to call Orcha's webhook on invoice status changes
• Supports real-time data export via API callout
• Includes response processing (can set Coupa fields based on Orcha's response)

SFTP alternative: Delta invoice updates delivered to /Outgoing/InvoiceUpdates as CSV.

6.4 Orcha Integration Capability Summary

7. Recommended Path Forward

Architecture Decision Matrix

Recommendation for Orcha

Given Orcha's focus on document ingestion, invoice processing, and accounting automation, the integration should cover the full invoice lifecycle:

Primary: Direct REST API integration (all endpoints included with Coupa license)

1. Ingest phase — Sync reference data from Coupa into Orcha:

   • GET /api/accounts — pull chart of accounts for validation
   • GET /api/lookup_values — pull cost centers, GL codes, departments
   • GET /api/suppliers — pull supplier master data for matching
   • Polling on updated-at for delta sync

2. Push phase — Write extracted invoice data back:

   • POST /api/invoices (or Inbound Invoice API) — create invoice from extracted data
   • Attachment API — attach original PDF
   • POST /api/lookup_values — create new cost centers if needed
   • POST /api/accounts — create new account code combinations if needed

3. Approval phase — Trigger and manage workflows:

   • PUT /api/approvals/:id/approve or /reject — programmatic approval
   • Invoice approval actions — add/remove/bypass approvers
   • Process Automator callout → Orcha webhook — receive approval events

4. Tracking phase — Monitor lifecycle:

   • GET /api/invoices?status=...&updated-at[gt]=... — poll for status changes
   • GET /api/coupa_pay/payments?... — track payment status
   • Or: Process Automator → webhook for real-time events

One known limitation: Account Types (CoA structure) cannot be created via API — they must be pre-configured in the Coupa instance by the customer's admin. This is a one-time setup dependency.

What you'd need from the Coupa customer:

1. OAuth 2.0 credentials (client ID/secret) with scopes for invoices, accounts, lookup_values, approvals, suppliers
2. Instance URL ({tenant}.coupahost.com)
3. Their Account Type names (for account creation)
4. Their Lookup names for cost centers (e.g., COMPANY_CostCenter)
5. Process Automator webhook configuration (if event-driven sync is desired)

7. Sources

Official Coupa Documentation

• The Coupa Core API
• Get Started with the API
• API Resources
• Transactional Resources
• Reference Data Resources
• Invoices API
• Inbound Invoice API
• Invoices API Example Calls
• Suppliers API
• Purchase Orders API
• Introducing GraphQL
• CSV Flat File Import
• CSV Flat File Export
• Postman Collection for Coupa APIs
• OAuth 2.0 Getting Started
• Additional SFTP Exports Add-on
• Coupa REST API Integration

Deep-Dive: Accounts, Cost Centers, Approvals

• Accounts API
• Accounts API Example Calls
• Account Types API
• Account Validation Rules API
• Lookup Values API
• Departments API
• Departments API Example Calls
• Accounting Data — Cost Center (SAP Playbook)
• COA / Accounts / Lookup Integration Scenarios
• Create a Lookup Value
• Modify a Lookup Value
• Approvals API
• Approvals API Example Calls
• Process Automator
• Process Automator Triggers
• Process Automator Actions
• Export Invoices using Process Automator
• Export Real-Time Data Updates
• Retrieve Invoice Status Updates
• Payments API

iPaaS & Middleware

• Celigo — Available Coupa APIs
• Workato — Coupa Connector
• Workato — Coupa Object Actions
• Workato — Coupa Supplier Actions
• Workato — Coupa Purchase Order Actions
• Make.com — Coupa
• MuleSoft — Coupa Connector
• Informatica — Coupa V2 Connector
• Boomi — Coupa Connector

Other

• Coupa App Marketplace
• Coupa API Tracker
• Postman — Coupa Collection (OAuth)
• Informatica — Creating a Webhook in Coupa