openapi: 3.1.0
info:
  title: Lago API documentation Add_ons Taxes API
  description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
  version: 1.15.0
  license:
    name: AGPLv3
    identifier: AGPLv3
  contact:
    email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
  description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
  description: EU Lagos cluster
security:
- bearerAuth: []
tags:
- name: Taxes
  description: Everything about Tax collection
  externalDocs:
    description: Find out more
    url: https://doc.getlago.com/docs/api/taxes/tax-object
paths:
  /taxes:
    post:
      tags:
      - Taxes
      summary: Lago Create a tax
      description: This endpoint creates a new tax representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: createTax
      requestBody:
        description: Tax creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxCreateInput'
        required: true
      responses:
        '200':
          description: Tax created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - Taxes
      summary: Lago List all taxes
      description: This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: findAllTaxes
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Taxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxesPaginated'
              example:
                taxes:
                - lago_id: 41190609-391a-4368-9549-d4348a85a8cd
                  name: TVA
                  code: french_standard_vat
                  description: French standard VAT
                  rate: 20
                  applied_to_organization: true
                  customers_count: 0
                  created_at: '2023-07-06T14:35:58Z'
                - lago_id: 2e034a10-6652-4daf-a600-b085184f93ad
                  name: TVA
                  code: french_reduced_vat
                  description: French reduce VAT
                  rate: 5
                  applied_to_organization: false
                  customers_count: 0
                  created_at: '2023-07-06T14:45:23Z'
                meta:
                  current_page: 1
                  next_page: null
                  prev_page: null
                  total_pages: 1
                  total_count: 2
        '401':
          $ref: '#/components/responses/Unauthorized'
  /taxes/{code}:
    parameters:
    - name: code
      in: path
      description: The code of the tax. It serves as a unique identifier associated with a particular tax. The code is typically used for internal or system-level identification purposes.
      required: true
      schema:
        type: string
        example: french_standard_vat
    put:
      tags:
      - Taxes
      summary: Lago Update a tax
      description: This endpoint updates an existing tax representing a customizable tax rate applicable to either the organization or a specific customer.
      operationId: updateTax
      requestBody:
        description: Tax update payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxUpdateInput'
        required: true
      responses:
        '200':
          description: Tax updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - Taxes
      summary: Lago Retrieve a Tax
      description: This endpoint retrieves an existing tax representing a customizable tax rate applicable to either the organization or a specific customer. The tax is identified by its unique code.
      operationId: findTax
      responses:
        '200':
          description: Tax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Taxes
      summary: Lago Delete a tax
      description: This endpoint is used to delete a tax.
      operationId: destroyTax
      responses:
        '200':
          description: Tax deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PaginationMeta:
      type: object
      required:
      - current_page
      - total_pages
      - total_count
      properties:
        current_page:
          type: integer
          description: Current page.
          example: 2
        next_page:
          type: integer
          description: Next page.
          example: 3
          nullable: true
        prev_page:
          type: integer
          description: Previous page.
          example: 1
          nullable: true
        total_pages:
          type: integer
          description: Total number of pages.
          example: 4
        total_count:
          type: integer
          description: Total number of records.
          example: 70
    ApiErrorUnprocessableEntity:
      type: object
      required:
      - status
      - error
      - code
      - error_details
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable entity
        code:
          type: string
          example: validation_errors
        error_details:
          type: object
    TaxUpdateInput:
      type: object
      required:
      - tax
      properties:
        tax:
          allOf:
          - $ref: '#/components/schemas/TaxBaseInput'
    TaxCreateInput:
      type: object
      required:
      - tax
      properties:
        tax:
          allOf:
          - $ref: '#/components/schemas/TaxBaseInput'
          - required:
            - name
            - code
            - rate
    TaxBaseInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the tax.
          example: TVA
        code:
          type: string
          description: Unique code used to identify the tax associated with the API request.
          example: french_standard_vat
        rate:
          type: string
          pattern: ^[0-9]+.?[0-9]*$
          description: The percentage rate of the tax
          example: '20.0'
        description:
          type: string
          nullable: true
          description: Internal description of the taxe
          example: French standard VAT
        applied_to_organization:
          type: boolean
          description: Set to `true` if the tax is used as one of the organization's default
          example: true
    ApiErrorNotFound:
      type: object
      required:
      - status
      - error
      - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    ApiErrorUnauthorized:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    ApiErrorBadRequest:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 400
        error:
          type: string
          example: Bad request
    TaxesPaginated:
      type: object
      required:
      - taxes
      - meta
      properties:
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/TaxObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    TaxObject:
      type: object
      required:
      - lago_id
      - name
      - code
      - rate
      - applied_to_organization
      - customers_count
      - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the tax, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: Name of the tax.
          example: TVA
        code:
          type: string
          description: Unique code used to identify the tax associated with the API request.
          example: french_standard_vat
        description:
          type: string
          description: Internal description of the taxe
          example: French standard VAT
        rate:
          type: number
          description: The percentage rate of the tax
          example: 20
        applied_to_organization:
          type: boolean
          description: Set to `true` if the tax is used as one of the organization's default
          example: true
        add_ons_count:
          type: integer
          description: Number of add-ons this tax is applied to.
          example: 0
        charges_count:
          type: integer
          description: Number of charges this tax is applied to.
          example: 0
        customers_count:
          type: integer
          description: Number of customers this tax is applied to (directly or via the organization's default).
          example: 0
        plans_count:
          type: integer
          description: Number of plans this tax is applied to.
          example: 0
        created_at:
          type: string
          format: date-time
          description: Creation date of the tax.
          example: '2023-07-06T14:35:58Z'
    Tax:
      type: object
      required:
      - tax
      properties:
        tax:
          $ref: '#/components/schemas/TaxObject'
  responses:
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
  parameters:
    page:
      name: page
      in: query
      description: Page number.
      required: false
      explode: true
      schema:
        type: integer
        example: 1
    per_page:
      name: per_page
      in: query
      description: Number of records per page.
      required: false
      explode: true
      schema:
        type: integer
        example: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Lago Github
  url: https://github.com/getlago