OpenAPI Specification
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