openapi: 3.1.0
info:
  title: Invoice Generator API
  summary: Generate invoice PDFs and UBL e-invoices from invoice details.
  description: |
    HTTP API for generating document PDFs and UBL e-invoices. Data is not stored.

    Send `type` on `POST /` to create an invoice, receipt, credit note, quote,
    estimate, pro forma invoice, purchase order, statement, timesheet,
    work order, or packing slip.
    When `type` is omitted, the API creates an invoice.

    Human docs: https://invoice-generator.com/developers
    Markdown: https://invoice-generator.com/developers.md

    The free plan is limited to 100 invoices per month.
  version: '1.0.0'
  contact:
    name: Invoice Generator
    url: https://invoice-generator.com
  license:
    name: Proprietary
    identifier: LicenseRef-Invoice-Generator

servers:
  - url: https://invoice-generator.com
    description: Production

security:
  - bearerAuth: []

tags:
  - name: Documents
    description: Generate PDF or UBL files from document details.

paths:
  /:
    post:
      operationId: createDocumentPdf
      tags: [Documents]
      summary: Create document PDF
      description: |
        Returns a PDF for the requested document type. Accepts `application/json`
        or `application/x-www-form-urlencoded`. When a value is null or zero, the
        field is omitted from the document, except the required fields `from`,
        `to`, `date`, and `items`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
            examples:
              invoice:
                $ref: '#/components/examples/CreateInvoice'
              receipt:
                $ref: '#/components/examples/CreateReceipt'
              creditNote:
                $ref: '#/components/examples/CreateCreditNote'
              quote:
                $ref: '#/components/examples/CreateQuote'
              estimate:
                $ref: '#/components/examples/CreateEstimate'
              proformaInvoice:
                $ref: '#/components/examples/CreateProformaInvoice'
              purchaseOrder:
                $ref: '#/components/examples/CreatePurchaseOrder'
              statement:
                $ref: '#/components/examples/CreateStatement'
              timesheet:
                $ref: '#/components/examples/CreateTimesheet'
              workOrder:
                $ref: '#/components/examples/CreateWorkOrder'
              packingSlip:
                $ref: '#/components/examples/CreatePackingSlip'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DocumentCreateRequest'
      responses:
        '200':
          description: Generated document PDF.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /ubl:
    post:
      operationId: createDocumentUbl
      tags: [Documents]
      summary: Create e-invoice
      description: |
        Returns a UBL e-invoice with the PDF embedded. Supported types are
        `invoice`, `receipt` (Invoice XML), and `credit_note`. Other types
        return an error.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UblCreateRequest'
            examples:
              invoice:
                $ref: '#/components/examples/CreateInvoice'
              creditNote:
                $ref: '#/components/examples/CreateCreditNote'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UblCreateRequest'
      responses:
        '200':
          description: Generated UBL e-invoice.
          content:
            application/xml:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key from Settings > Developer. Example `Authorization: Bearer myApiKey`."

  parameters:
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      description: |
        Locale used for document labels. Default is `en-US`. Translations are
        available in English, French, German, Spanish, and Thai.
      schema:
        type: string
        default: en-US
        examples:
          - en-US
          - fr-FR
          - de-DE
          - es-ES
          - th-TH

  schemas:
    DocumentCreateRequest:
      oneOf:
        - $ref: '#/components/schemas/InvoiceRequest'
        - $ref: '#/components/schemas/ReceiptRequest'
        - $ref: '#/components/schemas/CreditNoteRequest'
        - $ref: '#/components/schemas/QuoteRequest'
        - $ref: '#/components/schemas/EstimateRequest'
        - $ref: '#/components/schemas/ProformaInvoiceRequest'
        - $ref: '#/components/schemas/PurchaseOrderRequest'
        - $ref: '#/components/schemas/StatementRequest'
        - $ref: '#/components/schemas/TimesheetRequest'
        - $ref: '#/components/schemas/WorkOrderRequest'
        - $ref: '#/components/schemas/PackingSlipRequest'
      discriminator:
        propertyName: type
        mapping:
          invoice: '#/components/schemas/InvoiceRequest'
          receipt: '#/components/schemas/ReceiptRequest'
          credit_note: '#/components/schemas/CreditNoteRequest'
          quote: '#/components/schemas/QuoteRequest'
          estimate: '#/components/schemas/EstimateRequest'
          proforma_invoice: '#/components/schemas/ProformaInvoiceRequest'
          purchase_order: '#/components/schemas/PurchaseOrderRequest'
          statement: '#/components/schemas/StatementRequest'
          timesheet: '#/components/schemas/TimesheetRequest'
          work_order: '#/components/schemas/WorkOrderRequest'
          packing_slip: '#/components/schemas/PackingSlipRequest'

    UblCreateRequest:
      oneOf:
        - $ref: '#/components/schemas/InvoiceRequest'
        - $ref: '#/components/schemas/ReceiptRequest'
        - $ref: '#/components/schemas/CreditNoteRequest'
      discriminator:
        propertyName: type
        mapping:
          invoice: '#/components/schemas/InvoiceRequest'
          receipt: '#/components/schemas/ReceiptRequest'
          credit_note: '#/components/schemas/CreditNoteRequest'

    SharedDocumentFields:
      type: object
      required:
        - from
        - to
        - date
        - items
      properties:
        theme:
          type: string
          enum: [classic, slate]
          default: classic
          description: Document appearance.
        logo:
          type: string
          format: uri
          description: URL of your logo.
        from:
          type: string
          description: Your organization billing address and contact info. Multiple lines are allowed.
        to:
          type: string
          description: Entity being billed. Multiple lines are allowed.
        ship_to:
          type: string
          description: Shipping address. Multiple lines are allowed.
        number:
          oneOf:
            - type: string
            - type: number
          description: Document number.
        currency:
          type: string
          minLength: 3
          maxLength: 3
          default: USD
          description: ISO 4217 3-letter currency code.
        custom_fields:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/CustomField'
        date:
          type: string
          description: Document date. Defaults to the current date.
        items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        fields:
          $ref: '#/components/schemas/SubtotalFields'
        discounts:
          type: number
          default: 0
        tax:
          type: number
          default: 0
        shipping:
          type: number
          default: 0
        notes:
          type: string
        terms:
          type: string
        header:
          type: string
        to_title:
          type: string
        ship_to_title:
          type: string
        number_title:
          type: string
        date_title:
          type: string
        payment_terms_title:
          type: string
        due_date_title:
          type: string
        purchase_order_title:
          type: string
        quantity_header:
          type: string
        item_header:
          type: string
        unit_cost_header:
          type: string
        amount_header:
          type: string
        subtotal_title:
          type: string
        discounts_title:
          type: string
        tax_title:
          type: string
        shipping_title:
          type: string
        total_title:
          type: string
        amount_paid_title:
          type: string
        balance_title:
          type: string
        terms_title:
          type: string
        notes_title:
          type: string

    InvoiceLikeFields:
      type: object
      properties:
        purchase_order:
          type: string
          description: Purchase order or referenced invoice number.
        payment_terms:
          type: string
        due_date:
          type: string
        amount_paid:
          type: number
          default: 0
        payment_methods:
          type: array
          description: |
            Payment method objects. UBL uses `{ type: url, name, url }`.
            Not shown on the PDF.
          items:
            $ref: '#/components/schemas/PaymentMethod'

    InvoiceRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - $ref: '#/components/schemas/InvoiceLikeFields'
        - type: object
          properties:
            type:
              type: string
              const: invoice
              default: invoice

    ReceiptRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - $ref: '#/components/schemas/InvoiceLikeFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: receipt

    CreditNoteRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: credit_note
            purchase_order:
              type: string
              description: Referenced invoice number.
            amount_refunded:
              type: number
              default: 0

    QuoteRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: quote
            purchase_order:
              type: string
            payment_terms:
              type: string

    EstimateRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: estimate
            purchase_order:
              type: string
            payment_terms:
              type: string

    ProformaInvoiceRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: proforma_invoice
            purchase_order:
              type: string
            payment_terms:
              type: string

    PurchaseOrderRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: purchase_order
            payment_terms:
              type: string
            due_date:
              type: string

    StatementRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - $ref: '#/components/schemas/InvoiceLikeFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: statement
            date_header:
              type: string
            reference_header:
              type: string
            charges_header:
              type: string
            payments_header:
              type: string
            payments_title:
              type: string

    TimesheetRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - $ref: '#/components/schemas/InvoiceLikeFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: timesheet
            date_header:
              type: string

    WorkOrderRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: work_order
            payment_terms:
              type: string
              description: Technician name.
            due_date:
              type: string
              description: Scheduled date.

    PackingSlipRequest:
      allOf:
        - $ref: '#/components/schemas/SharedDocumentFields'
        - type: object
          required: [type]
          properties:
            type:
              type: string
              const: packing_slip
            purchase_order:
              type: string
              description: Related invoice number.

    LineItem:
      type: object
      properties:
        name:
          type: string
        quantity:
          type: number
          default: 1
        unit_cost:
          type: number
          default: 0
        description:
          type: string
        date:
          type: string
          description: Used on statements and timesheets.
        reference:
          type: string
          description: Used on statements.
        payment:
          type: number
          description: Payment amount on a statement line.

    CustomField:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
        value:
          type: string

    PaymentMethod:
      type: object
      required:
        - type
        - name
        - url
      properties:
        type:
          type: string
          const: url
        name:
          type: string
        url:
          type: string
          format: uri

    SubtotalFields:
      type: object
      description: |
        Toggles the discounts, tax, and shipping subtotal lines. Each setting
        can be `%`, `true`, or `false`.
      properties:
        tax:
          $ref: '#/components/schemas/SubtotalToggle'
          default: '%'
        discounts:
          $ref: '#/components/schemas/SubtotalToggle'
          default: false
        shipping:
          $ref: '#/components/schemas/SubtotalToggle'
          default: false

    SubtotalToggle:
      oneOf:
        - type: boolean
        - type: string
          enum: ['%']

    AuthError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          examples: [invalid_request]
        message:
          type: string

    ValidationError:
      type: object
      required:
        - error
      properties:
        error:
          type: string

    RateLimitError:
      type: object
      required:
        - type
        - message
      properties:
        type:
          type: string
          examples: [invalid_request]
        message:
          type: string

  responses:
    ValidationError:
      description: The document details could not be validated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'

    Unauthorized:
      description: Missing, invalid, or inactive API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          examples:
            missing:
              value:
                error: invalid_request
                message: "Missing API key! You must supply an API key in the Authorization header (eg `Authorization: Bearer myApiKey`). You can sign up for a free API key on Invoice-Generator.com."

    RateLimited:
      description: Monthly free-plan API limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the limit resets (start of next month).
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'

  examples:
    CreateInvoice:
      summary: Create invoice
      value:
        type: invoice
        from: Nikolaus Ltd
        to: Acme, Corp.
        logo: https://example.com/img/logo-invoice.png
        number: 1
        date: Feb 9, 2015
        due_date: Feb 16, 2015
        purchase_order: PO-1234
        items:
          - name: Starter plan monthly
            quantity: 1
            unit_cost: 99
        notes: Thanks for being an awesome customer!
        terms: Please pay by the due date.

    CreateReceipt:
      summary: Create receipt
      value:
        type: receipt
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        amount_paid: 99
        items:
          - name: Starter plan
            quantity: 1
            unit_cost: 99

    CreateCreditNote:
      summary: Create credit note
      value:
        type: credit_note
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: CN-1
        date: Feb 9, 2015
        purchase_order: '1'
        amount_refunded: 25
        items:
          - name: Unused time
            quantity: 1
            unit_cost: 25

    CreateQuote:
      summary: Create quote
      value:
        type: quote
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        payment_terms: Valid for 30 days
        items:
          - name: Website redesign
            quantity: 1
            unit_cost: 2500

    CreateEstimate:
      summary: Create estimate
      value:
        type: estimate
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        payment_terms: 30 days
        items:
          - name: Repair work
            quantity: 4
            unit_cost: 75

    CreateProformaInvoice:
      summary: Create pro forma invoice
      value:
        type: proforma_invoice
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        items:
          - name: Deposit
            quantity: 1
            unit_cost: 500

    CreatePurchaseOrder:
      summary: Create purchase order
      value:
        type: purchase_order
        from: Acme, Corp.
        to: Nikolaus Ltd
        number: 1
        date: Feb 9, 2015
        due_date: Mar 1, 2015
        items:
          - name: Office chairs
            quantity: 4
            unit_cost: 120

    CreateStatement:
      summary: Create statement
      value:
        type: statement
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        payment_terms: Jan 1, 2015
        due_date: Jan 31, 2015
        items:
          - name: Invoice 12
            date: Jan 8, 2015
            reference: '12'
            quantity: 1
            unit_cost: 99
            payment: 0

    CreateTimesheet:
      summary: Create timesheet
      value:
        type: timesheet
        from: Nikolaus Ltd
        to: Acme, Corp.
        number: 1
        date: Feb 9, 2015
        items:
          - name: Development
            date: Jan 8, 2015
            quantity: 6
            unit_cost: 85

    CreateWorkOrder:
      summary: Create work order
      value:
        type: work_order
        from: Nikolaus Ltd
        to: Acme, Corp.
        ship_to: "123 Job Site Rd\nAustin, TX"
        number: 1
        date: Feb 9, 2015
        payment_terms: Alex Rivera
        due_date: Mar 1, 2015
        items:
          - name: HVAC repair
            quantity: 2
            unit_cost: 95
        notes: This work order authorizes the listed work. It is not an invoice.

    CreatePackingSlip:
      summary: Create packing slip
      value:
        type: packing_slip
        from: Nikolaus Ltd
        to: Acme, Corp.
        ship_to: "Warehouse 4\nAustin, TX"
        number: 1
        date: Feb 9, 2015
        purchase_order: INV-88
        items:
          - name: Office chairs
            quantity: 4
