openapi: 3.1.0
info:
  title: Mercoa API
  description: |
    The Mercoa REST API powers embedded accounts payable and accounts receivable
    workflows inside vertical SaaS platforms. This spec is a curated subset of
    the canonical Mercoa OpenAPI document
    (https://github.com/mercoa-finance/openapi). All requests authenticate with
    a Bearer token (API key or JWT) in the Authorization header.
  version: "1.0"
  contact:
    name: Mercoa
    url: https://docs.mercoa.com/
servers:
  - url: https://api.mercoa.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Entity Groups
  - name: Entities
  - name: Invoices
  - name: Invoice Templates
  - name: Payment Methods
  - name: Transactions
  - name: Organization
  - name: OCR
  - name: Payment Gateway
paths:
  /entityGroups:
    get:
      tags: [Entity Groups]
      summary: List entity groups
      responses:
        "200":
          description: Paginated entity groups
  /entityGroup:
    post:
      tags: [Entity Groups]
      summary: Create entity group
      responses:
        "201":
          description: Created
  /entityGroup/{entityGroupId}:
    parameters:
      - $ref: "#/components/parameters/EntityGroupId"
    get:
      tags: [Entity Groups]
      summary: Get entity group
      responses:
        "200":
          description: Entity group
    post:
      tags: [Entity Groups]
      summary: Update entity group
      responses:
        "200":
          description: Updated
    delete:
      tags: [Entity Groups]
      summary: Delete entity group
      responses:
        "204":
          description: Deleted
  /entityGroup/{entityGroupId}/token:
    parameters:
      - $ref: "#/components/parameters/EntityGroupId"
    post:
      tags: [Entity Groups]
      summary: Generate entity group token
      responses:
        "201":
          description: Token
  /entityGroup/{entityGroupId}/addEntities:
    parameters:
      - $ref: "#/components/parameters/EntityGroupId"
    post:
      tags: [Entity Groups]
      summary: Add entities to group
      responses:
        "200":
          description: Updated group
  /entity:
    get:
      tags: [Entities]
      summary: List entities
      responses:
        "200":
          description: Paginated entities
    post:
      tags: [Entities]
      summary: Create entity
      responses:
        "201":
          description: Created
  /entity/{entityId}:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    get:
      tags: [Entities]
      summary: Get entity
      responses:
        "200":
          description: Entity
    post:
      tags: [Entities]
      summary: Update entity
      responses:
        "200":
          description: Updated
    delete:
      tags: [Entities]
      summary: Delete entity
      responses:
        "204":
          description: Deleted
  /entity/{entityId}/accept-tos:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    post:
      tags: [Entities]
      summary: Accept Mercoa TOS for entity
      responses:
        "200":
          description: TOS accepted
  /entity/{entityId}/request-kyb:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    post:
      tags: [Entities]
      summary: Request KYB verification
      responses:
        "200":
          description: Request submitted
  /entity/{entityId}/token:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    post:
      tags: [Entities]
      summary: Generate entity token
      responses:
        "201":
          description: Token
  /entity/{entityId}/counterparties/payees:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    get:
      tags: [Entities]
      summary: List payee counterparties
      responses:
        "200":
          description: Paginated payees
  /entity/{entityId}/counterparties/payors:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    get:
      tags: [Entities]
      summary: List payor counterparties
      responses:
        "200":
          description: Paginated payors
  /entity/{entityId}/paymentMethods:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    get:
      tags: [Payment Methods]
      summary: List payment methods for entity
      responses:
        "200":
          description: Payment methods
  /entity/{entityId}/paymentMethod:
    parameters:
      - $ref: "#/components/parameters/EntityId"
    post:
      tags: [Payment Methods]
      summary: Create payment method
      responses:
        "201":
          description: Created
  /entity/{entityId}/paymentMethod/{paymentMethodId}:
    parameters:
      - $ref: "#/components/parameters/EntityId"
      - name: paymentMethodId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Payment Methods]
      summary: Get payment method
      responses:
        "200":
          description: Payment method
    put:
      tags: [Payment Methods]
      summary: Update payment method
      responses:
        "200":
          description: Updated
    delete:
      tags: [Payment Methods]
      summary: Delete payment method
      responses:
        "204":
          description: Deleted
  /invoices:
    get:
      tags: [Invoices]
      summary: List invoices across the organization
      responses:
        "200":
          description: Paginated invoices
    post:
      tags: [Invoices]
      summary: Bulk create invoices
      responses:
        "201":
          description: Created
    put:
      tags: [Invoices]
      summary: Bulk update invoices
      responses:
        "200":
          description: Updated
  /invoices/approve:
    post:
      tags: [Invoices]
      summary: Bulk approve invoices
      responses:
        "200":
          description: Approved
  /invoice:
    post:
      tags: [Invoices]
      summary: Create invoice
      responses:
        "201":
          description: Created
  /invoice/{invoiceId}:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    get:
      tags: [Invoices]
      summary: Get invoice
      responses:
        "200":
          description: Invoice
    post:
      tags: [Invoices]
      summary: Update invoice
      responses:
        "200":
          description: Updated
    delete:
      tags: [Invoices]
      summary: Delete invoice
      responses:
        "204":
          description: Deleted
  /invoice/{invoiceId}/events:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    get:
      tags: [Invoices]
      summary: List invoice events
      responses:
        "200":
          description: Events
  /invoice/{invoiceId}/add-approver:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      tags: [Invoices]
      summary: Add approver to invoice
      responses:
        "200":
          description: Added
  /invoice/{invoiceId}/approve:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      tags: [Invoices]
      summary: Approve invoice
      responses:
        "200":
          description: Approved
  /invoice/{invoiceId}/reject:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      tags: [Invoices]
      summary: Reject invoice
      responses:
        "200":
          description: Rejected
  /invoice-templates:
    get:
      tags: [Invoice Templates]
      summary: List invoice templates
      responses:
        "200":
          description: Paginated templates
  /invoice-template:
    post:
      tags: [Invoice Templates]
      summary: Create invoice template
      responses:
        "201":
          description: Created
  /invoice-template/{invoiceTemplateId}:
    parameters:
      - name: invoiceTemplateId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Invoice Templates]
      summary: Get invoice template
      responses:
        "200":
          description: Template
    post:
      tags: [Invoice Templates]
      summary: Update invoice template
      responses:
        "200":
          description: Updated
    delete:
      tags: [Invoice Templates]
      summary: Delete invoice template
      responses:
        "204":
          description: Deleted
  /transactions:
    get:
      tags: [Transactions]
      summary: List transactions
      responses:
        "200":
          description: Paginated transactions
  /transaction/{transactionId}:
    parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Transactions]
      summary: Get transaction
      responses:
        "200":
          description: Transaction
  /organization:
    get:
      tags: [Organization]
      summary: Get organization
      responses:
        "200":
          description: Organization
    post:
      tags: [Organization]
      summary: Update organization
      responses:
        "200":
          description: Updated
  /ocr:
    post:
      tags: [OCR]
      summary: Synchronously OCR an invoice document
      responses:
        "200":
          description: OCR result
  /ocr-async:
    post:
      tags: [OCR]
      summary: Submit OCR job
      responses:
        "202":
          description: Job submitted
  /ocr-async/{jobId}:
    parameters:
      - name: jobId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [OCR]
      summary: Get OCR job
      responses:
        "200":
          description: Job status
  /payment-gateway/process:
    post:
      tags: [Payment Gateway]
      summary: Process payment via gateway
      responses:
        "200":
          description: Processed
  /payment-gateway/validate:
    post:
      tags: [Payment Gateway]
      summary: Validate payment via gateway
      responses:
        "200":
          description: Validated
components:
  parameters:
    EntityGroupId:
      name: entityGroupId
      in: path
      required: true
      schema:
        type: string
    EntityId:
      name: entityId
      in: path
      required: true
      schema:
        type: string
    InvoiceId:
      name: invoiceId
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: |
        Mercoa API key or JWT. Send as "Authorization: Bearer {token}". API keys
        are issued from the Mercoa Dashboard and are backend-only. JWTs scope
        access to an entity or entity group.