{ "openapi": "3.1.0", "info": { "title": "Lago API — agent discovery profile", "version": "1.51.0", "description": "A compact, agent-friendly profile of common Lago billing operations. The complete OpenAPI 3.1 description is available at https://getlago.com/api/openapi.yaml. Lago announces breaking changes through versioned migration guides with dated deprecation timelines before old behavior is removed.", "contact": { "email": "tech@getlago.com" }, "license": { "name": "AGPLv3", "url": "https://github.com/getlago/lago-openapi/blob/main/LICENSE" }, "x-deprecation-policy": { "description": "Migration guides document affected endpoints and fields, the replacement, and a dated support timeline.", "url": "https://getlago.com/docs/api-reference/versioning" }, "x-agent-profile": { "purpose": "Compact discovery and function calling for common Lago billing operations.", "canonicalSpecification": "https://getlago.com/api/openapi.yaml", "sdkGeneration": "Use the canonical specification for complete API coverage and generated clients." } }, "servers": [ { "url": "https://api.getlago.com/api/v1", "description": "US Lago Cloud" }, { "url": "https://api.eu.getlago.com/api/v1", "description": "EU Lago Cloud" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/customers": { "get": { "operationId": "findAllCustomers", "summary": "List all customers", "description": "Retrieve existing Lago customers with optional pagination and search.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "search_term", "in": "query", "required": false, "description": "Match a customer name, legal name, external ID, or email.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated customers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "customers", "meta" ], "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "operationId": "createCustomer", "summary": "Create or update a customer", "description": "Create a Lago customer, or update the customer identified by the supplied external ID.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateInput" } } } }, "responses": { "200": { "description": "Customer created or updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request fields are invalid or violate a Lago billing rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/customers/{external_customer_id}": { "get": { "operationId": "findCustomer", "summary": "Retrieve a customer", "description": "Retrieve one customer using the stable external identifier supplied by your application.", "parameters": [ { "$ref": "#/components/parameters/ExternalCustomerId" } ], "responses": { "200": { "description": "Customer", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "The requested Lago resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/events": { "post": { "operationId": "createEvent", "summary": "Send a usage event", "description": "Transmit one idempotent usage measurement event for a customer or subscription.", "x-idempotency": { "mechanism": "request-body", "property": "event.transaction_id", "retrySafe": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventInput" } } } }, "responses": { "200": { "description": "Usage event accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request fields are invalid or violate a Lago billing rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/events/batch": { "post": { "operationId": "createBatchEvents", "summary": "Send a batch of usage events", "description": "Transmit up to 100 idempotent usage events in one request. Each event is deduplicated by transaction_id and external_subscription_id.", "x-idempotency": { "mechanism": "request-body", "property": "events[].transaction_id", "retrySafe": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventBatchInput" } } } }, "responses": { "200": { "description": "Usage event batch accepted", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request fields are invalid or violate a Lago billing rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/subscriptions": { "get": { "operationId": "findAllSubscriptions", "summary": "List subscriptions", "description": "Retrieve active subscriptions, optionally filtered by customer, plan, or status.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "name": "external_customer_id", "in": "query", "required": false, "description": "Filter by your application's customer identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated subscriptions", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "subscriptions", "meta" ], "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "operationId": "createSubscription", "summary": "Assign a plan to a customer", "description": "Create a subscription or change the plan assigned to an existing customer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateInput" } } } }, "responses": { "200": { "description": "Subscription created or changed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "Request fields are invalid or violate a Lago billing rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/invoices": { "get": { "operationId": "findAllInvoices", "summary": "List invoices", "description": "Retrieve Lago invoices with pagination and documented filters.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated invoices", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoices", "meta" ], "properties": { "invoices": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "description": "Bearer API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "The organization has exceeded the current REST API rate limit. Wait until X-RateLimit-Reset before retrying.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Structured Lago API error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A scoped Lago API key. See https://getlago.com/auth.md." } }, "parameters": { "Page": { "name": "page", "in": "query", "required": false, "description": "One-based result page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "description": "Maximum number of records returned per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "ExternalCustomerId": { "name": "external_customer_id", "in": "path", "required": true, "description": "The unique customer identifier supplied by your application.", "schema": { "type": "string" } } }, "headers": { "XRateLimitLimit": { "description": "Maximum requests allowed in the current rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitReset": { "description": "Seconds until the current rate-limit window resets.", "schema": { "type": "integer", "minimum": 0 } } }, "schemas": { "Customer": { "type": "object", "required": [ "external_id" ], "properties": { "external_id": { "type": "string", "description": "Stable customer identifier supplied by your application." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" } }, "additionalProperties": true }, "CustomerCreateInput": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "type": "object", "required": [ "external_id" ], "properties": { "external_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "additionalProperties": true } } }, "EventInput": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "object", "required": [ "transaction_id", "code", "external_subscription_id" ], "properties": { "transaction_id": { "type": "string", "description": "Unique idempotency identifier for this usage event." }, "code": { "type": "string", "description": "Billable metric code." }, "external_customer_id": { "type": "string" }, "external_subscription_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "properties": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "EventBatchInput": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Event" } } }, "additionalProperties": false }, "Event": { "type": "object", "required": [ "transaction_id", "code", "external_subscription_id" ], "properties": { "transaction_id": { "type": "string", "description": "Unique idempotency identifier for this usage event." }, "code": { "type": "string", "description": "Billable metric code." }, "external_customer_id": { "type": "string" }, "external_subscription_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "properties": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "Subscription": { "type": "object", "required": [ "external_id", "external_customer_id", "plan_code" ], "properties": { "external_id": { "type": "string" }, "external_customer_id": { "type": "string" }, "plan_code": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "canceled", "terminated" ] } }, "additionalProperties": true }, "SubscriptionCreateInput": { "type": "object", "required": [ "subscription" ], "properties": { "subscription": { "type": "object", "required": [ "external_customer_id", "plan_code", "external_id" ], "properties": { "external_customer_id": { "type": "string" }, "plan_code": { "type": "string" }, "external_id": { "type": "string" }, "billing_time": { "type": "string", "enum": [ "anniversary", "calendar" ] } }, "additionalProperties": true } } }, "PaginationMeta": { "type": "object", "required": [ "current_page", "total_pages" ], "properties": { "current_page": { "type": "integer", "minimum": 1 }, "next_page": { "type": [ "integer", "null" ], "minimum": 1 }, "prev_page": { "type": [ "integer", "null" ], "minimum": 1 }, "total_pages": { "type": "integer", "minimum": 0 }, "total_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": true }, "ApiError": { "type": "object", "required": [ "status", "error" ], "properties": { "status": { "type": "integer", "description": "HTTP status code." }, "error": { "type": "string", "description": "Stable machine-readable error label." }, "code": { "type": "string", "description": "More specific error code when the operation supplies one." }, "message": { "type": "string", "description": "Human-readable resolution detail when supplied." } }, "additionalProperties": true, "description": "Consistent JSON error returned by Lago REST API operations." } } }, "externalDocs": { "description": "Complete Lago API documentation", "url": "https://getlago.com/docs/api-reference/intro" } }