openapi: 3.1.0
info:
  title: Sage Accounting Bank Accounts Sales Invoices API
  description: 'Sage Accounting API (v3.1) is a RESTful web service that connects software to Sage''s cloud accounting platform. Supports Sage Business Cloud Accounting and Sage Business Cloud Start products. Covers contacts, sales and purchase invoices, payments, bank accounts, ledger accounts, products/services, and financial reporting. Uses OAuth 2.0 for authentication. Rate limits apply: 1,296,000 daily requests, 150 concurrent, 100 per minute per company.'
  version: 3.1.0
  contact:
    name: Sage Developer Support
    url: https://developer.sage.com/support/
  license:
    name: Sage Developer Agreement
    url: https://developer.sage.com/
servers:
- url: https://api.accounting.sage.com/v3.1
  description: Sage Accounting API v3.1
security:
- OAuth2: []
tags:
- name: Sales Invoices
  description: Sales invoice creation and management
paths:
  /sales_invoices:
    get:
      operationId: listSalesInvoices
      summary: List Sales Invoices
      description: Returns a paginated list of sales invoices.
      tags:
      - Sales Invoices
      parameters:
      - name: contact_id
        in: query
        schema:
          type: string
        description: Filter by customer contact ID
      - name: status_id
        in: query
        schema:
          type: string
          enum:
          - DRAFT
          - SENT
          - PAID
          - VOID
      - name: from_date
        in: query
        schema:
          type: string
          format: date
      - name: to_date
        in: query
        schema:
          type: string
          format: date
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: items_per_page
        in: query
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: Sales invoice list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesInvoiceList'
    post:
      operationId: createSalesInvoice
      summary: Create Sales Invoice
      description: Creates a new sales invoice for a customer.
      tags:
      - Sales Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSalesInvoiceRequest'
      responses:
        '201':
          description: Sales invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesInvoice'
  /sales_invoices/{key}:
    get:
      operationId: getSalesInvoice
      summary: Get Sales Invoice
      description: Returns a specific sales invoice by ID.
      tags:
      - Sales Invoices
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Sales invoice details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesInvoice'
    put:
      operationId: updateSalesInvoice
      summary: Update Sales Invoice
      description: Updates a draft sales invoice.
      tags:
      - Sales Invoices
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSalesInvoiceRequest'
      responses:
        '200':
          description: Invoice updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesInvoice'
    delete:
      operationId: deleteSalesInvoice
      summary: Delete Sales Invoice
      description: Voids or deletes a sales invoice.
      tags:
      - Sales Invoices
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Invoice deleted
components:
  schemas:
    LineItem:
      type: object
      properties:
        id:
          type: string
        description:
          type: string
        quantity:
          type: number
        unit_price:
          type: number
        net_amount:
          type: number
        tax_amount:
          type: number
        total_amount:
          type: number
        ledger_account:
          $ref: '#/components/schemas/LedgerAccountRef'
        tax_rate:
          $ref: '#/components/schemas/TaxRateRef'
    SalesInvoice:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
        date:
          type: string
          format: date
        due_date:
          type: string
          format: date
        reference:
          type: string
        status:
          $ref: '#/components/schemas/StatusRef'
        contact:
          $ref: '#/components/schemas/ContactRef'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        net_amount:
          type: number
        tax_amount:
          type: number
        total_amount:
          type: number
        outstanding_amount:
          type: number
        currency:
          $ref: '#/components/schemas/CurrencyRef'
    LineItemInput:
      type: object
      required:
      - description
      - quantity
      - unit_price
      - ledger_account_id
      properties:
        description:
          type: string
        quantity:
          type: number
          default: 1
        unit_price:
          type: number
          format: double
        ledger_account_id:
          type: string
        tax_rate_id:
          type: string
    SalesInvoiceList:
      type: object
      properties:
        $items:
          type: array
          items:
            $ref: '#/components/schemas/SalesInvoice'
        $total:
          type: integer
        $page:
          type: integer
    CurrencyRef:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
    TaxRateRef:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
    StatusRef:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
    UpdateSalesInvoiceRequest:
      type: object
      properties:
        sales_invoice:
          type: object
          properties:
            date:
              type: string
              format: date
            due_date:
              type: string
              format: date
            reference:
              type: string
            line_items:
              type: array
              items:
                $ref: '#/components/schemas/LineItemInput'
    ContactRef:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
    CreateSalesInvoiceRequest:
      type: object
      properties:
        sales_invoice:
          type: object
          required:
          - contact_id
          - date
          - line_items
          properties:
            contact_id:
              type: string
            date:
              type: string
              format: date
            due_date:
              type: string
              format: date
            reference:
              type: string
            line_items:
              type: array
              items:
                $ref: '#/components/schemas/LineItemInput'
    LedgerAccountRef:
      type: object
      properties:
        id:
          type: string
        displayed_as:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.sageone.com/oauth2/auth
          tokenUrl: https://oauth.accounting.sage.com/token
          scopes:
            full_access: Full read/write access to all accounting data
            readonly: Read-only access to accounting data