Worders Invoices API

openapi: 3.0.1
info:
  title: Worders API V1 Customers Invoices API
  version: v1
  description: Worders API endpoints (freelance invoice verification, webhooks, ...).
servers:
- url: https://api.worders.net
tags:
- name: Invoices
paths:
  /V1/invoices:
    get:
      summary: List invoices
      tags:
      - Invoices
      description: Returns invoices mirroring the invoice PDF. Items are flattened with grouping fields (requester, order_reference, project_name) so the consumer can group freely.
      security:
      - cookie_session: []
      - bearer_auth: []
      parameters:
      - name: customer_plunet_id
        in: query
        required: false
        schema:
          type: integer
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: updated_since
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: matching invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          description: unauthenticated
  /V1/invoices/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Plunet invoice id (e.g. "2847") or invoice_number (e.g. "I-2847").
    get:
      summary: Show a single invoice
      tags:
      - Invoices
      security:
      - cookie_session: []
      - bearer_auth: []
      responses:
        '200':
          description: lookup by decorated invoice_number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          description: unknown invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    QuoteItem:
      type: object
      properties:
        id:
          type: string
          nullable: true
          example: I-44556
          description: Plunet item id
        plunet_id:
          type: string
          nullable: true
          description: Same as id
        language_source:
          type: string
          nullable: true
          example: en-US
        language_target:
          type: string
          nullable: true
          example: fr-FR
        client_price:
          type: number
          format: float
          nullable: true
          example: 49.5
          description: Item price in the customer-facing currency.
        status:
          type: string
          nullable: true
          example: invoiced
        price_line:
          type: array
          items:
            $ref: '#/components/schemas/PriceLineEntry'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              nullable: true
          required:
          - code
          - message
      required:
      - error
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 42
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 50
    QuoteCustomer:
      type: object
      nullable: true
      properties:
        plunet_id:
          type: integer
          nullable: true
          example: 12345
        name:
          type: string
          example: EBSCO
        address:
          type: string
          nullable: true
          example: 'EBSCO

            10 Estes Street

            01938 Ipswich

            United States'
    InvoiceLine:
      type: object
      description: A single billable line on the invoice, flattened with grouping fields (requester, order_reference, project_name) so the consumer can group freely.
      properties:
        requester:
          type: string
          nullable: true
          example: Amber Russell
          description: Order contact person full name.
        order_reference:
          type: string
          nullable: true
          example: O-9703
          description: Falls back to the originating quote order_reference.
        project_name:
          type: string
          nullable: true
          example: Weekly Researcher task - May 5
        description:
          type: string
          nullable: true
        total_price:
          type: number
          format: float
          nullable: true
          example: 9.0
          description: Line total in the customer-facing currency.
        order_item:
          $ref: '#/components/schemas/QuoteItem'
          nullable: true
    PriceLineEntry:
      type: object
      properties:
        price_unit_id:
          type: integer
          nullable: true
          example: 12
        service:
          type: string
          nullable: true
          example: Culturalization
        unit:
          type: string
          nullable: true
          example: Hour
        amount:
          type: number
          format: float
          example: 0.55
        unit_price:
          type: number
          format: float
          example: 90.0
        total:
          type: number
          format: float
          example: 49.5
    Invoice:
      type: object
      properties:
        invoice_number:
          type: string
          nullable: true
          example: Worders-Invoice2847
        created_at:
          type: string
          format: date-time
        payment_due_date:
          type: string
          format: date
          nullable: true
        payment_date:
          type: string
          format: date
          nullable: true
        description:
          type: string
          nullable: true
          example: Collective invoice - May 2026
        po_number:
          type: string
          nullable: true
        client_ccy:
          type: string
          nullable: true
          example: USD
        status:
          type: string
          nullable: true
          example: outstanding
        totals:
          type: object
          properties:
            net:
              type: number
              format: float
              nullable: true
              example: 5778.0
            outgoing:
              type: number
              format: float
              nullable: true
              example: 5778.0
            paid:
              type: number
              format: float
              nullable: true
              example: 0
        customer:
          $ref: '#/components/schemas/QuoteCustomer'
        payment_request_id:
          type: string
          format: uuid
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLine'
  securitySchemes:
    cookie_session:
      type: apiKey
      in: cookie
      name: _worders_session
      description: Authenticated Devise session cookie (api.worders.net).
    bearer_auth:
      type: http
      scheme: bearer
      description: 'Service API key issued from the admin UI. Sent as `Authorization: Bearer wrd_live_…`.'