Joinways Invoices API

openapi: 3.2.0
info:
  title: Joinways Public Invoices API
  version: 1.15.0
  description: 'The Joinways REST API lets you read and manage your CRM and event data:

    events, quotes, invoices, companies, contacts, leads (requests), venues,

    catalog, tasks, reports and more. It is a **JSON over HTTPS** API described by

    this OpenAPI 3.1 document, served at `https://joinways.app/openapi.yaml`

    and rendered at `https://joinways.app/docs/api`. The same data is reachable from AI assistants through the Joinways MCP

    server (`https://mcp.joinways.app`, guide at

    `https://joinways.app/docs/claude-mcp`): both surfaces share the OAuth

    server, the tokens, the scopes, the role permissions and the services of

    the app, so a rule holds the same way in the app, in the REST API and in

    MCP. ## Authentication


    Every request needs a **Bearer token** in the `Authorization` header:


    ```

    Authorization: Bearer jw_xxxxxxxx

    ```


    Two token types work:


    - **API key** (`jw_…`): an owner or admin creates one from **Settings →

    Developers → API keys** in the workspace (guide:

    `https://joinways.app/docs/api-keys`). An API key acts as the member

    who created it: it carries the read and write scopes, and the **role

    permissions its creator holds now** in the workspace (see below; a

    creator who leaves the workspace takes the key''s access with them). It

    does not expire unless you set an expiry, and can be revoked at any

    time from the same page. - **OAuth 2.1 access token** (`jw_oat_…`): for apps acting on a user''s

    behalf (Authorization Code + PKCE S256, same flow as the MCP server). - Authorization endpoint `https://joinways.app/oauth/authorize`, token

    endpoint `https://joinways.app/api/oauth/token`, revocation

    `https://joinways.app/api/oauth/revoke` (RFC 7009), metadata

    `https://joinways.app/.well-known/oauth-authorization-server`. - **Clients**: register with Dynamic Client Registration

    (`POST /api/oauth/register`), or use an https URL as `client_id`

    (Client ID Metadata Document). - **Resource** (RFC 8707): send `resource=https://joinways.app/api/v1`

    on the authorization and token requests to bind the token to this API

    (a token bound to `https://mcp.joinways.app` is refused here, and the

    other way round). An unknown resource is refused with

    `invalid_target`. Protected resource metadata:

    `https://joinways.app/.well-known/oauth-protected-resource/api/v1`. - **Refresh**: a client registered with the `refresh_token` grant gets a

    refresh token (`jw_ort_…`) next to a **1 hour** access token. Each

    refresh rotates the refresh token (the old one stops working); a

    refresh token unused for 90 days expires. A client without the

    refresh grant gets a **30 day** access token and re-runs the flow. A refresh may ask for fewer scopes: only the new access token is

    narrowed. A user who left the workspace gets `invalid_grant` on

    refresh, and the whole token family is revoked. - **Granted scope** = requested ∩ supported (`mcp.read`, `mcp.write`)

    ∩ registered by the client. - The authorization response carries `iss` (RFC 9207). The consent

    screen shows the host of a metadata-document client, and warns when

    the `redirect_uri` is on another domain. - A workspace owner sees and revokes connected apps in **Settings →

    Developers → MCP → Connected apps**. A token is **bound to a single workspace**. You never pass an

    `account_id`: the workspace comes from the token. The API is part of

    the **Pro plan and the free trial**: a valid token of a workspace

    without either is refused with `403 forbidden`, `details.reason:

    plan_not_eligible`. Revocation takes effect within about a minute

    across our infrastructure. Tokens are stored hashed (SHA-256) and shown

    once. A `401` carries the RFC 6750 / RFC 9728 challenge:


    ```

    WWW-Authenticate: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"

    ```


    ## Scopes


    | Scope | Grants |

    |---|---|

    | `mcp.read` | Every `GET` |

    | `mcp.write` | Every `POST`, `PATCH`, `PUT`, `DELETE`, and reading (it implies `mcp.read`) |


    API keys carry both scopes.'
  contact:
    name: Joinways
    url: https://joinways.app
  license:
    name: Proprietary
  x-logo:
    url: /images/marketing/logo-header.svg
    altText: Joinways
    href: https://joinways.app
servers:
- url: https://joinways.app/api/v1
  description: Production
security:
- bearerAuth: []
- oauth2:
  - mcp.read
  - mcp.write
tags:
- name: Invoices
paths:
  /invoices:
    get:
      tags:
      - Invoices
      summary: List invoices
      operationId: listInvoices
      description: 'Invoices of the workspace, newest first, across every channel: issued by Joinways (`joinways`, Factur-X PDF), through Stripe, Qonto or QuickBooks, or recorded from the venue''s own billing software (`external`). Each invoice carries its credit notes. Read-only: invoices are issued from the app. Same data as the MCP tool `list_invoices`. **Role permission:** `reports.view` or `quotes.manage` (invoices carry revenue).'
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      x-required-permission:
      - reports.view
      - quotes.manage
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: event_id
        in: query
        description: Only invoices of this event.
        schema:
          type: string
          format: uuid
      - name: quote_id
        in: query
        description: Only invoices of this quote.
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        description: One or more statuses (repeat the parameter or separate with commas).
        schema:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceStatus'
        style: form
        explode: true
      - name: invoice_kind
        in: query
        description: One or more kinds (`deposit`, `balance`, `full`).
        schema:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceKind'
        style: form
        explode: true
      - name: channel
        in: query
        description: One or more channels.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceChannel'
        style: form
        explode: true
      - name: issued_from
        in: query
        description: Issue date on or after this day.
        schema:
          type: string
          format: date
          example: '2026-01-01'
      - name: issued_to
        in: query
        description: Issue date on or before this day.
        schema:
          type: string
          format: date
          example: '2026-12-31'
      responses:
        '200':
          description: Page of invoices.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
          description: An id filter is not a UUID, a date is not `YYYY-MM-DD`, or a status, kind or channel is unknown (`details.field` names it).
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /invoices/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Invoices
      summary: Get an invoice
      operationId: getInvoice
      description: One invoice of the workspace, whatever its channel, with its credit notes and a PDF link valid one hour. Same data as the MCP tool `get_invoice`. **Role permission:** `reports.view` or `quotes.manage`.
      security:
      - bearerAuth: []
      - oauth2:
        - mcp.read
      x-required-permission:
      - reports.view
      - quotes.manage
      responses:
        '200':
          description: The invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  headers:
    RateLimitLimit:
      description: Requests allowed in the current window (per workspace once authenticated, per IP before).
      schema:
        type: integer
        example: 600
    RateLimitReset:
      description: When the window resets (ISO 8601).
      schema:
        type: string
        format: date-time
        example: '2026-10-04T14:31:00.000Z'
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 0
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 12
  schemas:
    LeadErrorReason:
      type: string
      description: 'Leads: convert, merge, link, status, create.'
      enum:
      - lead_not_found
      - lead_locked
      - invalid_venue
      - invalid_dates
      - venue_locked
      - venue_unavailable
      - lead_linked_elsewhere
      - same_lead
      - not_found
      - lead_archived
      - both_converted
      - target_archived
      - target_rejected
      - target_event_closed
      - other_venue_event
      - access_denied
      - event_not_found
      - event_closed
      - lead_moved_concurrently
      - validation_requires_event
      - lead_deleted
    QuoteErrorReason:
      type: string
      description: '409 state refusals, 400 validation (`min_price` with `details.params`; `package_article`: the line is an article of a package, write the package line; `package_discount_amount`: a package takes a percent discount only), 402 plan.'
      enum:
      - platform_quote_read_only
      - platform_quote_delete_forbidden
      - platform_version_signed
      - quote_conflict
      - quote_changed
      - quote_locked
      - quote_signed
      - quote_cancelled
      - quote_not_cancellable
      - quote_has_active_invoice
      - quote_has_amendments
      - quote_superseded
      - amendment_in_flight
      - amendment_nested
      - parent_not_active
      - parent_not_signed
      - parent_fully_invoiced
      - invalid_status
      - not_a_platform_version
      - event_closed
      - event_archived
      - platform_quote_no_document
      - min_price
      - invalid_location_item
      - package_article
      - package_discount_amount
      - no_fields
      - db_rule
      - validation
      - quotes_plan_required
    SignedQuoteImportErrorReason:
      type: string
      description: POST /events/{id}/quotes/import.
      enum:
      - quotes_plan_required
      - event_not_found
      - quote_not_found
      - event_archived
      - quote_not_signable
      - duplicate_reference
      - invalid_pdf
      - invalid_amounts
      - pdf_too_large
      - forbidden
    PlatformErrorReason:
      type: string
      description: Authentication and rate limits (403, 429).
      enum:
      - plan_not_eligible
      - per-ip
      - per-account-minute
      - per-account-day
      - email_rate_limited
    TaskErrorReason:
      type: string
      enum:
      - task_not_found
      - event_not_found
      - assignee_not_found
      - event_archived
      - no_fields
    CreditNote:
      type: object
      description: A credit note (avoir) on an invoice.
      properties:
        id:
          type: string
          format: uuid
        channel:
          $ref: '#/components/schemas/InvoiceChannel'
        invoice_id:
          type: string
          format: uuid
          description: The invoice it credits.
        credit_note_number:
          type:
          - string
          - 'null'
          example: AVOIR-LYON-0001
        status:
          type: string
          enum:
          - issued
          - void
        purpose:
          type:
          - string
          - 'null'
          enum:
          - cancellation
          - adjustment
          - null
          description: 'Joinways only: `cancellation` cancels the invoice (now `void`), `adjustment` lowers it after an amendment. `null` on other channels.'
        currency:
          $ref: '#/components/schemas/Currency'
        total_incl_tax:
          type: number
          example: 360
        total_excl_tax:
          type:
          - number
          - 'null'
          description: '`null` on Stripe credit notes.'
          example: 300
        already_deducted:
          type: boolean
          description: 'Already subtracted from the invoice''s `total_incl_tax` (a Stripe credit note issued before payment): do not subtract it again.'
        counted_in_paid:
          type: boolean
          description: Already inside the invoice's `amount_paid` (a QuickBooks credit memo applied to the invoice).
        reason:
          type:
          - string
          - 'null'
        issue_date:
          type:
          - string
          - 'null'
          format: date
        pdf_url:
          type:
          - string
          - 'null'
          description: 'Joinways: signed link valid one hour. Stripe: its PDF. Otherwise `null`.'
        hosted_url:
          type:
          - string
          - 'null'
        created_at:
          type:
          - string
          - 'null'
          format: date-time
    InvoiceKind:
      type: string
      description: '`deposit` (acompte), `balance` (solde) or `full` (single invoice).'
      enum:
      - deposit
      - balance
      - full
    ErrorReason:
      description: '`details.reason` of an error: snake_case lower case, the same value as the `code` of the matching MCP tool error. One list per domain.'
      anyOf:
      - $ref: '#/components/schemas/PlatformErrorReason'
      - $ref: '#/components/schemas/EventErrorReason'
      - $ref: '#/components/schemas/LeadErrorReason'
      - $ref: '#/components/schemas/TaskErrorReason'
      - $ref: '#/components/schemas/QuoteErrorReason'
      - $ref: '#/components/schemas/CatalogErrorReason'
      - $ref: '#/components/schemas/SignedQuoteImportErrorReason'
      - $ref: '#/components/schemas/EmailErrorReason'
    Invoice:
      type: object
      description: An invoice of a quote (`GET /invoices`, `GET /invoices/{id}`, the `data` of the `invoice.*` webhooks). Amounts are in currency units (`360` = 360.00), like the quote totals.
      properties:
        id:
          type: string
          format: uuid
        channel:
          $ref: '#/components/schemas/InvoiceChannel'
        event_id:
          type: string
          format: uuid
        quote_id:
          type: string
          format: uuid
        invoice_kind:
          $ref: '#/components/schemas/InvoiceKind'
        invoice_number:
          type:
          - string
          - 'null'
          description: Legal number (Joinways), the provider's number, or the number typed for an external invoice. `null` on a draft.
          example: FACT-LYON-0007
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        currency:
          $ref: '#/components/schemas/Currency'
        total_excl_tax:
          type:
          - number
          - 'null'
          description: '`null` on Stripe invoices (not kept by Joinways).'
          example: 300
        total_tax:
          type:
          - number
          - 'null'
          example: 60
        total_incl_tax:
          type: number
          example: 360
        amount_paid:
          type: number
          example: 0
        amount_remaining:
          type:
          - number
          - 'null'
          example: 360
        issue_date:
          type:
          - string
          - 'null'
          format: date
          description: 'Stripe invoices: the day of creation.'
        due_date:
          type:
          - string
          - 'null'
          format: date
        paid_at:
          type:
          - string
          - 'null'
          format: date-time
        voided_at:
          type:
          - string
          - 'null'
          format: date-time
        payment_method:
          type:
          - string
          - 'null'
          enum:
          - bank_transfer
          - card
          - check
          - cash
          - other
          - null
          description: Joinways and external invoices, as recorded when marked paid.
        payment_reference:
          type:
          - string
          - 'null'
        software:
          type:
          - string
          - 'null'
          description: External invoices only, the software that issued it.
          example: Opera
        hosted_url:
          type:
          - string
          - 'null'
          description: The provider's page for the client (Stripe, Qonto, QuickBooks payment link).
        pdf_url:
          type:
          - string
          - 'null'
          description: 'Joinways: signed link valid one hour (Factur-X PDF), `null` in webhooks. Stripe: its PDF. Otherwise `null`.'
        credit_notes:
          type: array
          description: Credit notes on this invoice, oldest first. What is still owed is `amount_remaining`; to compute a net billed amount, subtract the credit notes whose `already_deducted` is false.
          items:
            $ref: '#/components/schemas/CreditNote'
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    Currency:
      type: string
      description: ISO 4217 currency code.
      enum:
      - EUR
      - USD
      - GBP
      - CHF
      - CAD
      - AUD
      - JPY
      - CNY
      - INR
      - KRW
      - SEK
      - NOK
      - DKK
      - PLN
      - CZK
      - HUF
      - RON
      - RUB
      - MXN
      - BRL
      - ARS
      - CLP
      - COP
      - PEN
      - SGD
      - THB
      - PHP
      - IDR
      - MYR
      - VND
      - AED
      - SAR
      - ILS
      - TRY
      - NZD
      - ZAR
      - NGN
      - KES
      - MAD
      - TND
      - DZD
      example: EUR
    InvoiceStatus:
      type: string
      description: '`draft` (not issued yet, integrations only), `open` (issued, to be paid), `paid`, `void` (cancelled, usually by a credit note), `uncollectible` (Stripe).'
      enum:
      - draft
      - open
      - paid
      - void
      - uncollectible
    InvoiceChannel:
      type: string
      description: 'Who issued the invoice: `joinways` (Joinways itself, legal numbering of the venue, Factur-X PDF), `stripe`, `qonto`, `quickbooks` (the venue''s connected account), `external` (the venue''s own billing software, recorded in Joinways; no document here).'
      enum:
      - joinways
      - stripe
      - qonto
      - quickbooks
      - external
    EventErrorReason:
      type: string
      description: Events, their sub-resources and the BEO.
      enum:
      - event_not_found
      - event_archived
      - event_not_archived
      - event_has_dependencies
      - venue_locked
      - venue_required
      - venue_unavailable
      - invalid_venue_spaces
      - invalid_dates
      - invalid_timezone
      - invalid_reference
      - invalid_assignee
      - invalid_stage
      - platform_duplicate
      - no_fields
      - revenue_access_required
      - version_conflict
    CatalogErrorReason:
      type: string
      description: 'Catalog writes, packages mostly. All `400` except `package_component` (`409`). `package_price_read_only`: the price and tax rate of a package come from its components, they are never sent (nor `pricing_mode` without `components`). `package_components_required`: a package needs at least one component (or `is_package: false`). `package_flag_required`: `components` sent for a plain item without `is_package: true`. `package_component_duplicate`: an item listed twice. `package_component_self`: the package among its own components. `package_component_not_found`: a component that is not an item of the package''s venue (unknown, another venue, another workspace). `package_component_is_package`: a package cannot contain a package. `package_component_vat_required`: a component has no tax rate and the venue no country to take one from. `package_price_zero`: the components add up to 0. `min_price_above_price`: `min_price` above the price of the package. `price_required`: a plain item (created, or a package turned back into one) without a price. `package_components_refused`: the database refused the composition (a rule above, lost to a concurrent change). `package_component` (409): the item is a component of a package; it cannot be deleted, nor become a package, before it is removed from that package.'
      enum:
      - package_price_read_only
      - package_components_required
      - package_flag_required
      - package_component_duplicate
      - package_component_self
      - package_component_not_found
      - package_component_is_package
      - package_component_vat_required
      - package_price_zero
      - min_price_above_price
      - price_required
      - package_components_refused
      - package_component
    Error:
      type: object
      description: Standard error envelope returned on any non-2xx response.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code (see the Errors table).
              enum:
              - invalid_request
              - unauthorized
              - payment_required
              - forbidden
              - not_found
              - conflict
              - idempotency_conflict
              - payload_too_large
              - idempotency_key_reuse
              - quota_exceeded
              - rate_limited
              - server_error
              example: not_found
            message:
              type: string
              description: Human-readable message (do not parse it). Generic on 5xx.
              example: Event not found
            details:
              description: 'Structured details: field errors on validation (`formErrors`, `fieldErrors`), the query parameter at fault (`field`), `reason` (a stable code) on refusals, or `null`.'
              oneOf:
              - type: object
                additionalProperties: true
                properties:
                  reason:
                    $ref: '#/components/schemas/ErrorReason'
                  field:
                    type: string
                    description: The parameter or body field at fault.
              - type: 'null'
    EmailErrorReason:
      type: string
      description: POST /events/{id}/emails.
      enum:
      - event_not_found
      - event_archived
      - connection_not_found
      - connection_inactive
      - connection_cannot_send
      - no_connection
      - reconnect_required
      - email_rate_limited
    Paginated:
      type: object
      description: Envelope wrapping a page of results.
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          description: The page of results (item type depends on the endpoint).
          items: {}
        pagination:
          type: object
          required:
          - page
          - per_page
          - total
          - total_pages
          properties:
            page:
              type: integer
              description: Current 1-based page.
              example: 1
            per_page:
              type: integer
              description: Items per page.
              example: 50
            total:
              type:
              - integer
              - 'null'
              description: Total matching items across all pages (`null` only on a page past the last one, when unknown).
              example: 1234
            total_pages:
              type:
              - integer
              - 'null'
              example: 25
  responses:
    Unauthorized:
      description: Missing, invalid, expired or revoked bearer token (`unauthorized`).
      headers:
        WWW-Authenticate:
          description: RFC 6750 challenge pointing at the protected resource metadata (RFC 9728).
          schema:
            type: string
          example: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or expired token
              details: null
    NotFound:
      description: Not found in this workspace, or the id of the path is not a UUID (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Event not found
              details: null
    Forbidden:
      description: '`forbidden`: the token lacks the scope, its owner''s role lacks the permission named by the operation, or the workspace has neither the Pro plan nor a trial (`details.reason` `plan_not_eligible`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: 'Missing required permission: quotes.manage'
              details: null
    RateLimited:
      description: 'Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests
              details:
                reason: per-account-minute
    BadRequest:
      description: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: Validation failed
              details:
                formErrors: []
                fieldErrors:
                  start_date:
                  - Required
  parameters:
    PerPage:
      name: per_page
      in: query
      description: Items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    Page:
      name: page
      in: query
      description: 1-based page number.
      schema:
        type: integer
        minimum: 1
        default: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth token
      description: 'Paste a token in the `Authorization: Bearer …` header: an **API key** (`jw_…`, created in Settings → Developers → API keys, acting with the role of the member who created it) or an **OAuth 2.1 access token** (`jw_oat_…`). A token is bound to a single workspace.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 authorization code grant with mandatory PKCE (S256). Access tokens are opaque strings prefixed `jw_oat_`, presented as `Authorization: Bearer …`: valid 1 hour with a refresh token (`jw_ort_…`, rotated on each use, 90 days idle), 30 days for a client without the refresh grant. Send `resource=https://joinways.app/api/v1` (RFC 8707). Clients register dynamically or use an https `client_id` (Client ID Metadata Document). Tokens are bound to a single workspace.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://joinways.app/oauth/authorize
          tokenUrl: https://joinways.app/api/oauth/token
          refreshUrl: https://joinways.app/api/oauth/token
          scopes:
            mcp.read: Read the workspace data the member's role can read.
            mcp.write: Create, update, delete and actions within the member's role (implies read).