OpenAPI Specification
openapi: 3.1.0
info:
title: Lago API documentation Add_ons Subscriptions 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: Subscriptions
description: Everything about Subscription collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/subscriptions/subscription-object
paths:
/subscriptions:
post:
tags:
- Subscriptions
summary: Lago Assign a plan to a customer
description: This endpoint assigns a plan to a customer, creating or modifying a subscription. Ideal for initial subscriptions or plan changes (upgrades/downgrades).
operationId: createSubscription
requestBody:
description: Subscription payload
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateInput'
required: true
responses:
'200':
description: Subscription created
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Subscriptions
summary: Lago List all subscriptions
description: This endpoint retrieves all active subscriptions.
operationId: findAllSubscriptions
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- name: external_customer_id
in: query
description: The customer external unique identifier (provided by your own application)
required: false
explode: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
- name: plan_code
in: query
description: The unique code representing the plan to be attached to the customer. This code must correspond to the code property of one of the active plans.
required: false
explode: true
schema:
type: string
example: premium
- name: status[]
in: query
description: 'If the field is not defined, Lago will return only `active` subscriptions. However, if you wish to fetch subscriptions by different status you can define them in a status[] query param. Available filter values: `pending`, `canceled`, `terminated`, `active`.'
required: false
explode: true
schema:
type: array
items:
type: string
enum:
- pending
- canceled
- terminated
- active
example:
- active
- pending
responses:
'200':
description: List of subscriptions
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionsPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/subscriptions/{external_id}:
parameters:
- name: external_id
in: path
description: External ID of the existing subscription
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
get:
tags:
- Subscriptions
summary: Lago Retrieve a subscription
description: This endpoint retrieves a specific subscription.
operationId: findSubscription
responses:
'200':
description: Subscription
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- Subscriptions
summary: Lago Update a subscription
description: This endpoint allows you to update a subscription.
operationId: updateSubscription
requestBody:
description: Update an existing subscription
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionUpdateInput'
required: true
responses:
'200':
description: Subscription updated
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
tags:
- Subscriptions
summary: Lago Terminate a subscription
description: This endpoint allows you to terminate a subscription.
operationId: destroySubscription
parameters:
- name: status
in: query
description: If the field is not defined, Lago will terminate only `active` subscriptions. However, if you wish to cancel a `pending` subscription, please ensure that you include `status=pending` in your request.
required: false
explode: true
schema:
type: string
example: pending
responses:
'200':
description: Subscription terminated
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/NotAllowed'
/subscriptions/{external_id}/lifetime_usage:
parameters:
- name: external_id
in: path
description: External ID of the existing subscription
required: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
get:
tags:
- Subscriptions
summary: Lago Retrive subscription lifetime usage
description: This endpoint enables the retrieval of the lifetime usage of a subscription.
operationId: getSubscriptionLifetimeUsage
responses:
'200':
description: Subscription lifetime usage
content:
application/json:
schema:
$ref: '#/components/schemas/LifetimeUsage'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- Subscriptions
summary: Lago Update a subscription lifetime usage
description: This endpoint allows you to update the lifetime usage of a subscription.
operationId: updateSubscriptionLifetimeUsage
requestBody:
description: Update the lifetime usage of a subscription
content:
application/json:
schema:
$ref: '#/components/schemas/LifetimeUsageInput'
required: true
responses:
'200':
description: Subscription lifetime usage updated
content:
application/json:
schema:
$ref: '#/components/schemas/LifetimeUsage'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
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
LifetimeUsageInput:
type: object
required:
- lifetime_usage
properties:
lifetime_usage:
type: object
required:
- external_historical_usage_amount_cents
properties:
external_historical_usage_amount_cents:
type: integer
example: 100
description: The historical usage amount in cents for the subscription (provided by your own application).
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
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'
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'
LifetimeUsage:
type: object
required:
- lifetime_usage
properties:
lifetime_usage:
$ref: '#/components/schemas/LifetimeUsageObject'
LifetimeUsageObject:
type: object
required:
- lago_id
- lago_subscription_id
- external_subscription_id
- external_historical_usage_amount_cents
- invoiced_usage_amount_cents
- current_usage_amount_cents
- from_datetime
- to_datetime
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the lifetime usage record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the lifetime usage record within the Lago system
lago_subscription_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the subscription record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription record within the Lago system
external_subscription_id:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
description: The subscription external unique identifier (provided by your own application).
external_historical_usage_amount_cents:
type: integer
example: 100
description: The historical usage amount in cents for the subscription (provided by your own application).
invoiced_usage_amount_cents:
type: integer
example: 100
description: The total invoiced usage amount in cents for the subscription.
current_usage_amount_cents:
type: integer
example: 100
description: The current usage amount in cents for the subscription on the current billing period.
from_datetime:
type: string
format: date-time
example: '2024-01-01T00:00:00Z'
description: The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
to_datetime:
type: string
format: date-time
example: '2024-12-31T23:59:59Z'
description: The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
usage_thresholds:
type: array
description: Array of usage thresholds attached to the subscription's plan.
items:
$ref: '#/components/schemas/LifetimeUsageThresholdObject'
Subscription:
type: object
required:
- subscription
properties:
subscription:
$ref: '#/components/schemas/SubscriptionObjectExtended'
ApiErrorNotAllowed:
type: object
required:
- status
- error
- code
properties:
status:
type: integer
format: int32
example: 405
error:
type: string
example: Method Not Allowed
code:
type: string
example: not_allowed
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
ChargeProperties:
type: object
properties:
graduated_ranges:
type: array
description: Graduated ranges, sorted from bottom to top tiers, used for a `graduated` charge model.
items:
type: object
required:
- from_value
- to_value
- flat_amount
- per_unit_amount
properties:
from_value:
type: integer
description: Specifies the lower value of a tier for a `graduated` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
example: 0
to_value:
type: integer
description: 'Specifies the highest value of a tier for a `graduated` charge model.
- This value must be higher than the from_value of the same tier.
- This value must be null for the last tier.'
nullable: true
example: 10
flat_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The flat amount for a whole tier, excluding tax, for a `graduated` charge model. It is expressed as a decimal value.
example: '10'
per_unit_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The unit price, excluding tax, for a specific tier of a `graduated` charge model. It is expressed as a decimal value.
example: '0.5'
graduated_percentage_ranges:
type: array
description: Graduated percentage ranges, sorted from bottom to top tiers, used for a `graduated_percentage` charge model.
items:
type: object
required:
- from_value
- to_value
- rate
- flat_amount
properties:
from_value:
type: integer
description: Specifies the lower value of a tier for a `graduated_percentage` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
example: 0
to_value:
type: integer
description: 'Specifies the highest value of a tier for a `graduated_percentage` charge model.
- This value must be higher than the from_value of the same tier.
- This value must be null for the last tier.'
nullable: true
example: 10
rate:
type: string
format: ^[0-9]+.?[0-9]*$
description: The percentage rate that is applied to the amount of each transaction in the tier for a `graduated_percentage` charge model. It is expressed as a decimal value.
example: '1'
flat_amount:
type: string
format: ^[0-9]+.?[0-9]*$
description: The flat amount for a whole tier, excluding tax, for a `graduated_percentage` charge model. It is expressed as a decimal value.
example: '10'
amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: '- The unit price, excluding tax, for a `standard` charge model. It is expressed as a decimal value.
- The amount, excluding tax, for a complete set of units in a `package` charge model. It is expressed as a decimal value.'
example: '30'
free_units:
type: integer
description: The quantity of units that are provided free of charge for each billing period in a `package` charge model. This field specifies the number of units that customers can use without incurring any additional cost during each billing cycle.
example: 100
package_size:
type: integer
description: The quantity of units included in each pack or set for a `package` charge model. It indicates the number of units that are bundled together as a single package or set within the pricing structure.
example: 1000
rate:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The percentage rate that is applied to the amount of each transaction for a `percentage` charge model. It is expressed as a decimal value.
example: '1'
fixed_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The fixed fee that is applied to each transaction for a `percentage` charge model. It is expressed as a decimal value.
example: '0.5'
free_units_per_events:
type: integer
description: The count of transactions that are not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the number of transactions that are exempt from the calculation of charges based on the specified percentage rate and fixed fee.
nullable: true
example: 5
free_units_per_total_aggregation:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The transaction amount that is not impacted by the `percentage` rate and fixed fee in a percentage charge model. This field indicates the portion of the transaction amount that is exempt from the calculation of charges based on the specified percentage rate and fixed fee.
nullable: true
example: '500'
per_transaction_max_amount:
type: string
format: ^[0-9]+.?[0-9]*$
description: Specifies the maximum allowable spending for a single transaction. Working as a transaction cap.
nullable: true
example: '3.75'
per_transaction_min_amount:
type: string
format: ^[0-9]+.?[0-9]*$
description: Specifies the minimum allowable spending for a single transaction. Working as a transaction floor.
nullable: true
example: '1.75'
grouped_by:
type: array
description: The list of event properties that are used to group the events on the invoice for a `standard` charge model.
items:
type: string
example:
- agent_name
volume_ranges:
type: array
description: Volume ranges, sorted from bottom to top tiers, used for a `volume` charge model.
items:
type: object
required:
- from_value
- to_value
- flat_amount
- per_unit_amount
properties:
from_value:
type: integer
description: Specifies the lower value of a tier for a `volume` charge model. It must be either 0 or the previous range's `to_value + 1` to maintain the proper sequence of values.
example: 0
to_value:
type: integer
description: 'Specifies the highest value of a tier for a `volume` charge model.
- This value must be higher than the `from_value` of the same tier.
- This value must be `null` for the last tier.'
nullable: true
example: 10
flat_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The unit price, excluding tax, for a specific tier of a `volume` charge model. It is expressed as a decimal value.
example: '10'
per_unit_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The flat amount for a whole tier, excluding tax, for a `volume` charge model. It is expressed as a decimal value.
example: '0.5'
SubscriptionObject:
type: object
required:
- lago_id
- lago_customer_id
- billing_time
- external_customer_id
- created_at
- subscription_at
- plan_code
- external_id
- status
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription's record within the Lago system
external_id:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
description: The subscription external unique identifier (provided by your own application).
lago_customer_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system
external_customer_id:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
description: The customer external unique identifier (provided by your own application).
billing_time:
type: string
description: The billing time for the subscription, which can be set as either `anniversary` or `calendar`. If not explicitly provided, it will default to `calendar`. The billing time determines the timing of recurring billing cycles for the subscription. By specifying `anniversary`, the billing cycle will be based on the specific date the subscription started (billed fully), while `calendar` sets the billing cycle at the first day of the week/month/year (billed with proration).
example: anniversary
enum:
- calendar
- anniversary
name:
type: string
example: Repository A
description: The display name of the subscription on an invoice. This field allows for customization of the subscription's name for billing purposes, especially useful when a single customer has multiple subscriptions using the same plan.
nullable: true
plan_code:
type: string
example: premium
description: The unique code representing the plan to be attached to the customer. This code must correspond to the `code` property of one of the active plans.
status:
type: string
description: 'The status of the subscription, which can have the following values:
- `pending`: a previous subscription has been downgraded, and the current one is awaiting automatic activation at the end of the billing period.
- `active`: the subscription is currently active and applied to the customer.
- `terminated`: the subscription is no longer active.
- `canceled`: the subscription has been stopped before its activation. This can occur when two consecutive downgrades have been applied to a customer or when a subscription with a pending status is terminated.'
example: active
enum:
- active
- pending
- terminated
- canceled
created_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The creation date of the subscription, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). This date provides a timestamp indicating when the subscription was initially created.
canceled_at:
type: string
format: date-time
example: '2022-09-14T16:35:31Z'
description: The cancellation date of the subscription. This field is not null when the subscription is `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
nullable: true
started_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The effective start date of the subscription. This field can be null if the subscription is `pending` or `canceled`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
nullable: true
ending_at:
type: string
format: date-time
example: '2022-10-08T00:00:00Z'
description: The effective end date of the subscription. If this field is set to null, the subscription will automatically renew. This date should be provided in ISO 8601 datetime format, and use Coordinated Universal Time (UTC).
subscription_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with `anniversary` billing time. The `anniversary_date` should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
terminated_at:
type: string
format: date-time
example: '2022-09-14T16:35:31Z'
description: The termination date of the subscription. This field is not null when the subscription is `terminated`. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC)
nullable: true
previous_plan_code:
type: string
example: null
description: The code identifying the previous plan associated with this subscription.
nullable: true
next_plan_code:
type: string
example: null
description: The code identifying the next plan in the case of a downgrade.
nullable: true
downgrade_plan_date:
type: string
format: date
example: '2022-04-30'
description: The date when the plan will be downgraded, represented in ISO 8601 date format.
nullable: true
trial_ended_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The date when the free trial is ended, represented in ISO 8601 date format.
nullable: true
current_billing_period_started_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The date and time when the current billing period started, represented in ISO 8601 date format.
nullable: true
current_billing_period_ending_at:
type: string
format: date-time
example: '2022-09-08T00:00:00Z'
description: The date and time when the current billing period ends, represented in ISO 8601 date format.
nullable: true
PlanObject:
type: object
required:
- lago_id
- name
- created_at
- code
- interval
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-subscriptions-api-openapi.yml