openapi: 3.1.0
info:
  title: Lago API documentation Add_ons 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: Add_ons
  description: Everything about Add-on collection
  externalDocs:
    description: Find out more
    url: https://doc.getlago.com/docs/api/add_ons/add-on-object
paths:
  /add_ons:
    post:
      tags:
      - Add_ons
      summary: Lago Create an add-on
      description: This endpoint is used to create an add-on that can be then attached to a one-off invoice.
      operationId: createAddOn
      requestBody:
        description: Add-on payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOnCreateInput'
        required: true
      responses:
        '200':
          description: Add-on created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - Add_ons
      summary: Lago List all add-ons
      description: This endpoint is used to list all existing add-ons.
      operationId: findAllAddOns
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Add-ons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOnsPaginated'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /add_ons/{code}:
    parameters:
    - name: code
      in: path
      description: Unique code used to identify the add-on.
      required: true
      schema:
        type: string
        example: setup_fee
    put:
      tags:
      - Add_ons
      summary: Lago Update an add-on
      description: This endpoint is used to update an existing add-on.
      operationId: updateAddOn
      requestBody:
        description: Add-on payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOnUpdateInput'
        required: true
      responses:
        '200':
          description: Add-on updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - Add_ons
      summary: Lago Retrieve an add-on
      description: This endpoint is used to retrieve a specific add-on.
      operationId: findAddOn
      responses:
        '200':
          description: Add-on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Add_ons
      summary: Lago Delete an add-on
      description: This endpoint is used to delete an existing add-on.
      operationId: destroyAddOn
      responses:
        '200':
          description: Add-on deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOn'
        '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
    AddOnObject:
      type: object
      required:
      - lago_id
      - name
      - code
      - amount_cents
      - amount_currency
      - created_at
      properties:
        lago_id:
          type: string
          format: uuid
          description: Unique identifier of the add-on, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        name:
          type: string
          description: The name of the add-on.
          example: Setup Fee
        invoice_display_name:
          type: string
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
          example: Setup Fee (SF1)
        code:
          type: string
          description: Unique code used to identify the add-on.
          example: setup_fee
        amount_cents:
          type: integer
          description: The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
          example: 50000
        amount_currency:
          allOf:
          - $ref: '#/components/schemas/Currency'
          - description: The currency of the add-on.
            example: USD
        description:
          type: string
          nullable: true
          description: The description of the add-on.
          example: Implementation fee for new customers.
        created_at:
          type: string
          format: date-time
          description: The date and time when the add-on was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the add-on was initially created.
          example: '2022-04-29T08:59:51Z'
        taxes:
          type: array
          description: All taxes applied to the add-on.
          items:
            $ref: '#/components/schemas/TaxObject'
    AddOnCreateInput:
      type: object
      required:
      - add_on
      properties:
        add_on:
          allOf:
          - $ref: '#/components/schemas/AddOnBaseInput'
          - required:
            - name
            - code
            - amount_cents
            - amount_currency
    AddOnBaseInput:
      type: object
      properties:
        name:
          type: string
          description: The name of the add-on.
          example: Setup Fee
        invoice_display_name:
          type: string
          description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
          example: Setup Fee (SF1)
        code:
          type: string
          description: Unique code used to identify the add-on.
          example: setup_fee
        amount_cents:
          type: integer
          description: The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
          example: 50000
        amount_currency:
          allOf:
          - $ref: '#/components/schemas/Currency'
          - description: The currency of the add-on.
            example: USD
        description:
          type: string
          nullable: true
          description: The description of the add-on.
          example: Implementation fee for new customers.
        tax_codes:
          type: array
          items:
            type: string
          description: List of unique code used to identify the taxes.
          example:
          - french_standard_vat
    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
    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
    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
    AddOnsPaginated:
      type: object
      required:
      - add_ons
      - meta
      properties:
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/AddOnObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    Currency:
      type: string
      example: USD
      enum:
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHF
      - CLF
      - CLP
      - CNY
      - COP
      - CRC
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ETB
      - EUR
      - FJD
      - FKP
      - GBP
      - GEL
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HRK
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - ISK
      - JMD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KRW
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRO
      - MUR
      - MVR
      - MWK
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SEK
      - SGD
      - SHP
      - SLL
      - SOS
      - SRD
      - STD
      - SZL
      - THB
      - TJS
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - USD
      - UYU
      - UZS
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMW
    AddOn:
      type: object
      required:
      - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnObject'
    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'
    AddOnUpdateInput:
      type: object
      required:
      - add_on
      properties:
        add_on:
          $ref: '#/components/schemas/AddOnBaseInput'
  responses:
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    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