openapi: 3.1.0
info:
title: Lago API documentation Add_ons Plans 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: Plans
description: Everything about Plan collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/plans/plan-object
paths:
/plans:
post:
tags:
- Plans
summary: Lago Create a plan
description: This endpoint creates a plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
operationId: createPlan
requestBody:
description: Plan payload
content:
application/json:
schema:
$ref: '#/components/schemas/PlanCreateInput'
required: true
responses:
'200':
description: Plan created
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Plans
summary: Lago List all plans
description: This endpoint retrieves all existing plans.
operationId: findAllPlans
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
responses:
'200':
description: Plans
content:
application/json:
schema:
$ref: '#/components/schemas/PlansPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
/plans/{code}:
parameters:
- name: code
in: path
description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
required: true
schema:
type: string
example: startup
put:
tags:
- Plans
summary: Lago Update a plan
description: This endpoint updates a specific plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
operationId: updatePlan
requestBody:
description: Plan payload
content:
application/json:
schema:
$ref: '#/components/schemas/PlanUpdateInput'
required: true
responses:
'200':
description: Plan updated
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Plans
summary: Lago Retrieve a plan
description: This endpoint retrieves a specific plan.
operationId: findPlan
responses:
'200':
description: Plan
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Plans
summary: Lago Delete a plan
description: This endpoint deletes a specific plan. Note that this plan could be associated with active subscriptions.
operationId: destroyPlan
responses:
'200':
description: Plan deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Plan'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
ChargeFilterObject:
type: object
description: Values used to apply differentiated pricing based on additional event properties.
required:
- invoice_display_name
- properties
- values
properties:
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 values of the filter will be used as the default display name.
example: AWS
nullable: true
properties:
allOf:
- $ref: '#/components/schemas/ChargeProperties'
- description: List of all thresholds utilized for calculating the charge.
values:
type: object
description: List of possible filter values. The key and values must match one of the billable metric filters.
additionalProperties:
type: array
items:
type: string
example:
region:
- us-east-1
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
PlanUpdateInput:
type: object
required:
- plan
properties:
plan:
type: object
properties:
name:
type: string
example: Startup
description: The name of the plan.
invoice_display_name:
type: string
example: Startup plan
description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.
code:
type: string
example: startup
description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
interval:
type: string
description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `quarterly`, `monthly`, or `weekly`.'
example: monthly
enum:
- weekly
- monthly
- quarterly
- yearly
description:
type: string
description: The description on the plan.
example: Plan for early stage startups.
amount_cents:
type: integer
description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
example: 10000
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
example: USD
trial_period:
type: number
description: The duration in days during which the base cost of the plan is offered for free.
example: 5
pay_in_advance:
type: boolean
description: This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period.
example: true
bill_charges_monthly:
type: boolean
description: This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly`.
nullable: true
example: null
tax_codes:
type: array
items:
type: string
description: List of unique code used to identify the taxes.
example:
- french_standard_vat
minimum_commitment:
$ref: '#/components/schemas/MinimumCommitmentInput'
charges:
type: array
description: Additional usage-based charges for this plan.
items:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the charge created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
billable_metric_id:
type: string
format: uuid
description: Unique identifier of the billable metric created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
charge_model:
type: string
description: Specifies the pricing model used for the calculation of the final fee. It can be `standard`, `graduated`, `graduated_percentage`, `package`, `percentage`, `volume` or `dynamic`.
enum:
- standard
- graduated
- graduated_percentage
- package
- percentage
- volume
- dynamic
example: standard
pay_in_advance:
type: boolean
example: false
description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
invoiceable:
type: boolean
description: This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
example: true
regroup_paid_fees:
type: string
nullable: true
enum:
- null
- invoice
description: 'This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
This field determines whether and when the charge fee should be included in
the invoice. If `null`, no invoice will be issued for this charge fee.
If `invoice`, an invoice will be generated at the end of the period,
consolidating all charge fees with a succeeded payment status.'
example: invoice
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
prorated:
type: boolean
example: false
description: 'Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.
- If set to `true`, the charge is prorated based on the remaining days in the current billing period.
- If set to `false`, the charge is billed in full.
- If not defined in the request, default value is `false`.'
min_amount_cents:
type: integer
description: The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period.
example: 0
properties:
allOf:
- $ref: '#/components/schemas/ChargeProperties'
- description: List of all thresholds utilized for calculating the charge.
filters:
type: array
description: List of filters used to apply differentiated pricing based on additional event properties.
items:
$ref: '#/components/schemas/ChargeFilterInput'
tax_codes:
type: array
items:
type: string
description: List of unique code used to identify the taxes.
example:
- french_standard_vat
example:
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
charge_model: package
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
prorated: false
min_amount_cents: 3000
properties:
amount: '30'
free_units: 100
package_size: 1000
tax_codes:
- french_standard_vat
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
charge_model: graduated
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
prorated: false
min_amount_cents: 0
properties:
graduated_ranges:
- to_value: 10
from_value: 0
flat_amount: '10'
per_unit_amount: '0.5'
- to_value: null
from_value: 11
flat_amount: '0'
per_unit_amount: '0.4'
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
charge_model: standard
invoiceable: true
invoice_display_name: Setup
pay_in_advance: true
regroup_paid_fees: null
prorated: false
min_amount_cents: 0
properties: {}
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
charge_model: volume
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
prorated: false
min_amount_cents: 0
properties:
volume_ranges:
- from_value: 0
to_value: 100
flat_amount: '0'
per_unit_amount: '0'
- from_value: 101
to_value: null
flat_amount: '0'
per_unit_amount: '0.5'
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
charge_model: percentage
invoiceable: false
invoice_display_name: Setup
pay_in_advance: true
regroup_paid_fees: invoice
prorated: false
min_amount_cents: 0
properties:
rate: '1'
fixed_amount: '0.5'
free_units_per_events: 5
free_units_per_total_aggregation: '500'
usage_thresholds:
type: array
description: List of usage thresholds to apply to the plan.
items:
$ref: '#/components/schemas/UsageThresholdInput'
cascade_updates:
type: boolean
description: This field determines whether the changes made to the plan should be cascaded to the children plans. When set to `true`, the changes will be cascaded into children. Conversely, when set to `false`, the changes will only be applied to the plan itself. If not defined in the request, default value is `false`.
example: true
UsageThresholdObject:
type: object
required:
- lago_id
- amount_cents
- recurring
- created_at
- updated_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the usage threshold created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
threshold_display_name:
type: string
nullable: true
description: The display name of the usage threshold.
example: Threshold 1
amount_cents:
type: integer
description: The amount to reach to trigger a `progressive_billing` invoice.
example: 10000
recurring:
type: boolean
description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount.
example: true
created_at:
type: string
format: date-time
description: The date and time when the usage threshold was created. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2023-06-27T19:43:42Z'
updated_at:
type: string
format: date-time
description: The date and time when the usage threshold was last updated. It is expressed in UTC format according to the ISO 8601 datetime standard.
example: '2023-06-27T19:43:42Z'
PlanCreateInput:
type: object
required:
- plan
properties:
plan:
type: object
properties:
name:
type: string
example: Startup
description: The name of the plan.
invoice_display_name:
type: string
example: Startup plan
description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name.
code:
type: string
example: startup
description: The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.
interval:
type: string
description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `quarterly`, `monthly`, or `weekly`.'
example: monthly
enum:
- weekly
- monthly
- quarterly
- yearly
description:
type: string
description: The description on the plan.
example: Plan for early stage startups.
amount_cents:
type: integer
description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan.
example: 10000
amount_currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed.
example: USD
trial_period:
type: number
description: The duration in days during which the base cost of the plan is offered for free.
example: 5
pay_in_advance:
type: boolean
description: This field determines the billing timing for the plan. When set to `true`, the base cost of the plan is due at the beginning of each billing period. Conversely, when set to `false`, the base cost of the plan is due at the end of each billing period.
example: true
bill_charges_monthly:
type: boolean
description: This field, when set to `true`, enables to invoice usage-based charges on monthly basis, even if the cadence of the plan is yearly. This allows customers to pay charges overage on a monthly basis. This can be set to true only if the plan's interval is `yearly`.
nullable: true
example: null
tax_codes:
type: array
items:
type: string
description: List of unique code used to identify the taxes.
example:
- french_standard_vat
minimum_commitment:
$ref: '#/components/schemas/MinimumCommitmentInput'
charges:
type: array
description: Additional usage-based charges for this plan.
items:
type: object
properties:
billable_metric_id:
type: string
format: uuid
description: Unique identifier of the billable metric created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
charge_model:
type: string
description: Specifies the pricing model used for the calculation of the final fee. It can be `standard`, `graduated`, `graduated_percentage` `package`, `percentage`, `volume` or `dynamic`.
enum:
- standard
- graduated
- graduated_percentage
- package
- percentage
- volume
- dynamic
example: standard
pay_in_advance:
type: boolean
example: false
description: This field determines the billing timing for this specific usage-based charge. When set to `true`, the charge is due and invoiced immediately. Conversely, when set to false, the charge is due and invoiced at the end of each billing period.
invoiceable:
type: boolean
description: This field specifies whether the charge should be included in a proper invoice. If set to false, no invoice will be issued for this charge. You can only set it to `false` when `pay_in_advance` is `true`.
example: true
regroup_paid_fees:
type: string
nullable: true
enum:
- null
- invoice
description: 'This setting can only be configured if `pay_in_advance` is `true` and `invoiceable` is `false`.
This field determines whether and when the charge fee should be included in
the invoice. If `null`, no invoice will be issued for this charge fee.
If `invoice`, an invoice will be generated at the end of the period,
consolidating all charge fees with a succeeded payment status.'
example: invoice
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
prorated:
type: boolean
example: false
description: 'Specifies whether a charge is prorated based on the remaining number of days in the billing period or billed fully.
- If set to `true`, the charge is prorated based on the remaining days in the current billing period.
- If set to `false`, the charge is billed in full.
- If not defined in the request, default value is `false`.'
min_amount_cents:
type: integer
description: The minimum spending amount required for the charge, measured in cents and excluding any applicable taxes. It indicates the minimum amount that needs to be charged for each billing period.
example: 0
properties:
allOf:
- $ref: '#/components/schemas/ChargeProperties'
- description: List of all thresholds utilized for calculating the charge.
filters:
type: array
description: List of filters used to apply differentiated pricing based on additional event properties.
items:
$ref: '#/components/schemas/ChargeFilterInput'
tax_codes:
type: array
items:
type: string
description: List of unique code used to identify the taxes.
example:
- french_standard_vat
example:
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a91
charge_model: package
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
regroup_paid_fees: null
prorated: false
min_amount_cents: 3000
properties:
amount: '30'
free_units: 100
package_size: 1000
tax_codes:
- french_standard_vat
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a92
charge_model: graduated
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
prorated: false
min_amount_cents: 0
properties:
graduated_ranges:
- to_value: 10
from_value: 0
flat_amount: '10'
per_unit_amount: '0.5'
- to_value: null
from_value: 11
flat_amount: '0'
per_unit_amount: '0.4'
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a93
charge_model: standard
invoiceable: true
invoice_display_name: Setup
pay_in_advance: true
prorated: false
min_amount_cents: 0
properties: {}
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a94
charge_model: volume
invoiceable: true
invoice_display_name: Setup
pay_in_advance: false
prorated: false
min_amount_cents: 0
properties:
volume_ranges:
- from_value: 0
to_value: 100
flat_amount: '0'
per_unit_amount: '0'
- from_value: 101
to_value: null
flat_amount: '0'
per_unit_amount: '0.5'
- billable_metric_id: 1a901a90-1a90-1a90-1a90-1a901a901a95
charge_model: percentage
invoiceable: false
invoice_display_name: Setup
pay_in_advance: true
regroup_paid_fees: invoice
prorated: false
min_amount_cents: 0
properties:
rate: '1'
fixed_amount: '0.5'
free_units_per_events: 5
free_units_per_total_aggregation: '500'
usage_thresholds:
type: array
description: List of usage thresholds to apply to the plan.
items:
$ref: '#/components/schemas/UsageThresholdInput'
MinimumCommitmentObject:
type: object
nullable: true
required:
- lago_id
- amount_cents
- created_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier of the minimum commitment, created by Lago.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
plan_code:
type: string
example: premium
description: The unique code representing the plan to be attached to the customer.
amount_cents:
type: integer
description: The amount of the minimum commitment in cents.
example: 100000
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 default name will be used as the display name.
example: Minimum Commitment (C1)
interval:
type: string
description: 'The interval used for recurring billing. It represents the frequency at which subscription billing occurs. The interval can be one of the following values: `yearly`, `quarterly`, `monthly` or `weekly`.'
enum:
- weekly
- monthly
- quarterly
- yearly
example: monthly
created_at:
type: string
format: date-time
description: The date and time when the minimum commitment 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 minimum commitment was initially created.
example: '2022-04-29T08:59:51Z'
updated_at:
type: string
format: date-time
description: The date and time when the minimum commitment was updated. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the minimum commitment was initially created.
example: '2022-04-29T08:59:51Z'
taxes:
type: array
description: All taxes applied to the minimum commitment.
items:
$ref: '#/components/schemas/TaxObject'
MinimumCommitmentInput:
type: object
description: Minimum commitment for this plan.
nullable: true
required:
- amount_cents
properties:
amount_cents:
type: integer
description: The amount of the minimum commitment in cents.
example: 100000
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 default name will be used as the display name.
example: Minimum Commitment (C1)
tax_codes:
type: array
items:
type: string
description: List of uniq
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-plans-api-openapi.yml